A Tool-shaped Hole

When was the last time you really questioned what a model told you? We don’t blindly trust everything a model says, but we also don’t blindly trust any source, human or non-human. Consciously or not, we cross-check new information against information we receive from other sources – friends, colleagues, or our own research. That we now treat model output the same way means we’ve passed a threshold. We finally consider them as fundamentally reliable actors.

But even the most capable models are hamstrung by tools that are poorly designed, underpowered, or missing. So, how do you identify and design the right tools for an agent’s job? Let’s turn this mystic art into a methodology.

The tool-builder’s tradeoff

A tool, here, is whatever an agent calls to affect the outside world. Most tools usually are API requests wrapped in a schema the model reads or similar call to an external service. Design decisions revolve around defining:

1. How much the tool can do.
2. How hard the tool is to use.

These typically trade off against each other. The most powerful tools are also the hardest to use and the easiest tend to be the least capable. A good tool design is the work of managing that tradeoff instead of accepting it.

One school of thought offers “code mode” tools as the way out, and on paper it looks great on both axes at once: maximum power (arbitrary code) behind a familiar interface (a language the model already knows). This approach recognizes that most models have seen enormous amounts of real code in their training data, so all an agent needs to issue a request to an external service is a single all-purpose tool for writing and executing code. With access to the API spec, the model will be able to simply write and execute the requests it needs. In theory, once equipped with this tool, an agent will need no other.

In practice, writing code for every interaction works well for agents whose job is to write code. For every other agent, it imposes hoops that non-code-writing agents must jump through: instructions on how CLIs work, or elaborate skills for using different APIs. Models are also trained to call tools, with dedicated definitions, formats and special tokens for exactly that. A well-shaped, purpose-built tool is often something a model handles better than arbitrary code. So the single-code-tool bet undercuts itself for the majority of agents, in favor of a broader set of use-case-specific tools.

Vectara implements this through a wide range of tools; from built-in platform tools to custom tools, from MCP tools to client-side tools. These tools coexist on the same agent, with access to a sandbox for when you genuinely do want the agent to write and run code. Each agent is equipped with task-specific tools instead of a universal one.

Example: Google Sheets tool suite

Vectara builds platform tools when customers ask for them or we need them internally. Recently, we built a tool suite that lets Vectara agents operate on Google Sheets directly, helping you create spreadsheets and tabs, read values and formulas, update cells or append rows, add validation and conditional formatting, and do so much more. We learned a ton about tool design in the process.

Google Sheets is a complicated product. It has many features, a lot of ways to interact, and a huge amount of data. Its API concentrates most of that power in a single function, batchUpdate, that can do essentially everything. Models use it because they've seen it in training.

When we built this tool suite, we saw how models work with all that knowledge. Fable 5, a strong model, handled it best, but still got a lot wrong. GPT 5.5 struggled. Most of its calls errored out before landing the right sequence. For Haiku 4.5, the raw API was simply too hard to generate any accurate requests at all.

In response, we flipped the approach and broke batchUpdate into a few small tools focusing on the important parts. And tested against Haiku 4.5, the model that most consistently failed our original approach. And it succeeded! It turns out, the capability was always there, it just needed a different means of using Google’s API.

Agentic tool-building

At Vectara, we use agents to build tools. We primarily do this work using io, our homegrown AI assistant which drafts and configures agents based on our direction. Over time we’ve converged on a few design guidelines to help agents build dependable tools:

1. Integration-first. Reason about the integration before you write anything, and do it empirically. Not every API exposes thoughtfully designed endpoints, and a few behave exactly according to spec. Take the time to experiment with live endpoints and auth roles, and record the behavior you observe. It’s time well-spent.
2. Goldilocks signatures. Keep each tool easy to use. It is a Goldilocks rule, but the signs are clear: more than four arguments is a red flag, and "stringly-typed" arguments are almost always a mistake. Good tool design is just good function design.
3. Descriptions as documentation. Sweat the tool descriptions. They should explain how to use the tool without drowning the agent in detail. For any complicated interaction, the description is a guide. Argument names and types matter for the same reason, they're documentation the model actually reads, and it’s reading them on every call.
4. Output as progressive disclosure. Sweat the return output even more. Think of it as progressive disclosure: the output should tell the agent what to do next, or, when something fails, how to recover. Recall the Sheets example: a tool that only errors forces the model into a flailing loop of retries before it stumbles onto the right call. An output that says what failed and what to try next collapses that loop. And a return should also protect the agent. Dumping unneeded context into the conversation wastes tokens and actively degrades performance.

A caveat on MCP

Building tools with MCP is usually a pain. MCP is a hard protocol to implement well, mostly due to its persistent sessions, complexity, and non conforming client/servers. With Vectara’s sandbox and tool configuration capabilities, an agent can build a purposeful tool that calls a remote service, input and output transforms, overridden descriptions and arguments, without deploying anything. This is usually enough for most interactions. When it isn’t, the sandbox lets you write the exact tool signature in Python and call any tools you need, including web get, to integrate with basically anything.

Uncouple auth from the agent

Once the functionality of the tool is right, you have to worry about governance and authentication. Agent identity is a complicated topic, but the working principle is short. A tool’s principal is either the agent itself, a shared service account, or the person interacting with the agent. Either way, one rule holds: the tool, not the agent, enforces authorization boundaries. The tool never should ask the agent for identity. The identity should be delivered out of band to the agent’s context. Vectara has this ability by overriding tool arguments from secrets directly into the tool configuration without agent knowledge.

Taking it to production

So you have a tool. Does it actually work? Does the agent see what it needs to see? Yes, there are traces, metrics, and evals. But the strongest, cleanest signal is just to ask the agent. Ask it what it sees and run it through a sample task while it narrates. Better still, close the loop: have the agent that builds the tool run the agent being built, and ask the builder how the tools look from the inside.

The tool-shipping checklist

• Probe the live API first. Trust what it does, not what the spec says.
• One task per tool. Wrap what the agent wants to do, not every endpoint that exists.
• ≤ 4 arguments, all typed. Stringly-typed args are a bug with extra steps.
• The description explains how to use the tool. The model reads it on every call.
• Every output teaches agents the next step.
• Return nothing the next decision doesn't need.
• The tool enforces auth. The agent never holds the keys.

The models are capable now and have earned our trust. But a capable model behind a sprawling, over-permissioned API is a brilliant new hire with no login and no map. Reason about the real integration. Keep tools small. Make outputs teach. And never hand over the keys. This turns a model that struggled against a raw API into one that knows how to solve a task with the right tool.