How to build a Tool Wrapper

A Tool Wrapper (sometimes called a pre-configured tool) is a custom tool you build by wrapping an existing tool — a built-in one like web search, or a tool from a connection — and pinning some of its arguments so the AI agent only has to supply the rest. You give the wrapper its own name, its own inputs, and a clear job, and the agent calls it instead of the more general tool underneath.

Use a Tool Wrapper when a broad tool is almost right but you want to narrow it to one repeatable task. For example, a property_search tool might take a single city input and, under the hood, call web search with the query fixed to find properties for sale in <city> on a specific set of sites. The agent only chooses the city; everything else is decided for it.

Why wrap a tool

General-purpose tools have many options, and the AI agent picks a value for each of them on every call. That flexibility is useful, but it is also where inconsistency creeps in: the agent might search the whole web one time and your preferred sites the next, or ask for three results when you need ten. A wrapper takes those decisions out of the agent's hands:

Consistency. Arguments you fix are the same on every call, in every step that uses the wrapper.
A clearer choice for the agent. A tool named property_search with one city input is easier to pick correctly than a general search tool with half a dozen options.
Less to repeat in instructions. Instead of writing "only search zillow.com and redfin.com" in every step's instructions, you put it in the tool once.
Reshaped results. The wrapper can trim, filter, or restructure what the underlying tool returns, so later steps get exactly the fields they need.

A Tool Wrapper is a good fit when the underlying tool already does the work and you mainly want to constrain, rename, or reshape it. If the task instead needs judgment over unstructured text, use a Custom AI Tool; if it is a fixed rule or calculation with no existing tool to lean on, use a Custom Code Tool. Both are covered in Custom Tools. For a comparison of every tool type, see AI Tools.

Before you start

The wrapper can only wrap a tool that is already available on the thunk — the same tools the AI agent can call today. If the tool you want to wrap comes from a connection, add that connection first so its tools are enabled. See Connections to Business Applications.

If the tool is in a library that is turned off, or the tool itself is turned off, turn it on in the thunk's Connections pane first.

Create the wrapper

In the thunk's Custom-built tools, open Add New Tool and choose Tool Wrapper. A Create tool wrapper dialog opens.
Under Tool to wrap, pick the existing tool this wrapper should call under the hood. The list shows only tools already available on the thunk.
Under Logic/Intent, describe what the wrapper should do — the inputs it should take and how it should call the underlying tool. This is the one thing you must write; the dialog suggests some ideas:
- Restrict it to only some of the parameters, and fix the rest.
- Transform or reshape the output before returning it.
- Call it multiple times and combine the results.
Choose Create tool.

You do not name the wrapper in this dialog. From your intent, a builder writes the tool for you — it names the tool, writes its description, defines exactly the inputs you described, and writes the logic that calls the underlying tool. The new tool opens with its builder pane, where you can watch it work and refine it in plain language, exactly as with any custom tool.

Example: a property search tool

Suppose your workflow researches homes for sale, and you want every search to go to the same listing sites.

Tool to wrap: web_search — Web (the picker shows each tool with the library it comes from)

Logic/Intent:

Take one input, city (the city and state, for example "Austin, TX").
Search for "homes for sale in ", limited to zillow.com and redfin.com,
and return 10 results. Return only the title, link, and snippet of each result.

From that intent, the builder:

names the tool (for example property_search) and writes a description the AI agent can act on, such as Find homes for sale in a city on Zillow and Redfin;
defines one required input, city, with the description you gave;
writes code that calls web_search with the query built from city, the two sites, and 10 results;
keeps only the fields you asked for, and defines the tool's outputs to match.

The generated code looks roughly like this:

const { city } = getTypedInput();
const results = await tools.web_search({
  query: `homes for sale in ${city}`,
  type: "search",
  sites: ["zillow.com", "redfin.com"],
  numResults: 10,
  language: null,
  country: null,
});
return (results.organic ?? []).map((r) => ({
  title: r.title,
  link: r.link,
  snippet: r.snippet,
}));

You don't have to write or read this code — the intent is what drives it — but it is there on the tool's Implementation tab if you want to check exactly what the wrapper does.

More ideas for wrappers

Each of the dialog's suggestions can be written as a short intent. These examples show the pattern; change the tools and values to fit your connections.

Fix most of the arguments. Wrap a connection's "create ticket" tool so the agent only supplies the summary and details:

Inputs: summary and details. Create a ticket in the "IT Support" project
with priority "Normal" and the label "thunk-intake". Return the new ticket's ID and URL.

Reshape the output. Wrap a CRM "get account" tool that returns a large record:

Input: accountId. Call the account lookup and return only the account name,
owner email, renewal date, and annual contract value.

Call it several times and combine the results. Wrap web search to compare vendors:

Input: a list of vendor names. For each vendor, search for
" pricing" and keep the top 3 results. Return one list grouped by vendor.

Write a good intent

The builder takes your intent literally, so a precise intent produces a precise tool:

Name every input and say what it contains, including its format (city and state, for example "Austin, TX"). The builder defines exactly the inputs you describe — no more.
State every fixed value — sites, counts, project names, labels. Anything you leave unstated may become something the agent has to choose, or a default you did not expect.
Say what to return. If you only need some fields, list them. Smaller results are easier for the next step to use.
Say what to do when nothing is found — return an empty list, or report an error — if it matters to the workflow.

If the builder guesses wrong, tell it in the builder pane ("the sites should be zillow.com and redfin.com only") or edit Logic/Intent on the tool's Definition tab and let the builder update the code.

Wrap a connection's tool directly

You can also start a wrapper from the tool you want to wrap. On a connection's tool — including MCP and REST tools — open the tool's detail and choose Customize this tool. This opens the same Create tool wrapper dialog with that tool already chosen as the one to wrap, so you only supply the logic/intent. This option is available to thunk admins when the tool is enabled.

After it is built

A Tool Wrapper becomes an ordinary custom code tool once the builder finishes. There is nothing special to maintain:

Edit its intent, name, and description on the Definition tab, and its inputs, outputs, and code on the Implementation tab.
Try it on the Try It tab with test inputs, and confirm it behaves before the workflow relies on it.
Add tests on the Tests tab so later edits don't break it. See Automated tests for custom tools.
Use more tools. The wrapped tool is turned on under Tools on the Implementation tab. If the wrapper should also call a second tool, turn that one on there too, then describe the change in the intent.

Until the builder has written the code, the AI agent does not see the new tool, so a half-built wrapper is never called by a running workflow.

Once built, enable the wrapper on the steps that should use it. Consider turning the underlying general tool off on those steps, so the agent is not choosing between the two.

Troubleshooting

What you see	What it means
No tools are available on this thunk to wrap. Enable a tool first.	No tool libraries or connection tools are turned on for the thunk. Turn one on in the Connections pane, then try again.
That tool isn't enabled on this thunk. Enable it, or pick another tool to wrap.	You started from Customize this tool on a tool that is turned off for this thunk. Turn it on, or choose a different tool.
The wrapper fails when called after working before	The tool it wraps may have been turned off, or its connection removed. A wrapper depends on its underlying tool and fails the same way any custom tool does when a tool it calls goes away. Turn the tool back on, or rebuild the wrapper on another tool.
The wrapper asks for an input you didn't want	The intent left that value unstated. Add the fixed value to Logic/Intent and ask the builder to update the tool.