Tool calling

What is tool calling?

The mechanism that turns a text generator into something capable of acting. It is arguably the single most consequential primitive in any agentic system and certainly the most widely misunderstood, largely because the name describes an action the model itself never performs.

The misunderstanding is worth correcting precisely, because every governance question on this page follows from it.

That second row is the whole argument. A model cannot do anything to your systems; software you wrote does things on the strength of what a model suggested. Which means the question is never whether to trust the model, but what your executor is prepared to run on its say-so.

What happens in a tool call?

A tool call has six steps, and only one of them belongs to the model. Going through them in order shows where each control needs to go. A common mistake is placing a control too late, at a stage where the decision has already been made and the only thing left to do is act on it.

The sequence, with the point of intervention marked.

1. 01
   You supply the tool listNames, natural-language descriptions and parameter schemas go into the model's context. What this decides: the entire set of things that can possibly be proposed. Scoping happens here, not later.
2. 02
   The model proposesIt emits a tool name and arguments in a defined format. Note: this is the only step the model performs, and nothing has happened in the world yet.
3. 03
   Your code parses and validatesShape, types, ranges, permissions, and whether this caller may do this now. What this decides: everything. This is the only point where a control can hold.
4. 04
   Your code executes, and returns the resultThe output goes back into context and the model reasons again with it. What this decides: what the model now believes, which is why tool output is an injection surface. See prompt injection.

Reading the sequence this way settles a common design argument. Instructing the model not to do something is a preference expressed at step one; refusing to execute it is a control applied at step three, and only the second survives a model that behaves unexpectedly or a prompt somebody manipulated.

Why does the tool description matter more than the model?

The model chooses a tool based on its description. It compares the plain-language sentence you wrote with the task it is working on. This means that vague or overlapping descriptions cause far more wrong choices in practice than any weakness in the model’s reasoning.

Which makes tool descriptions an unusual artefact: documentation that is also executable instruction.

• Ambiguity between two tools is the top cause of wrong selection. If two descriptions could plausibly cover the same request, selection becomes close to arbitrary, and no model upgrade fixes a distinction you never drew.
• Parameter names carry meaning. A field called id invites the model to supply something that looks like an identifier. A field called customer_account_number invites the right one. Naming is prompt engineering with a schema attached.
• Describe when not to use it. The most valuable sentence in most tool descriptions is the exclusion, because models over-apply tools that sound generally useful.
• The description is read by the model, so it is an attack surface. Instruction-shaped text in a tool description is instruction, which is the tool poisoning problem covered at the Model Context Protocol.

A practical consequence worth acting on before anything else. When an agent picks the wrong tool, rewrite the description before you change the model, since it is a five-minute change with a larger effect, and the alternative is paying more per call to compensate for a sentence nobody edited.

Where does the trust boundary sit?

Inside your executor, and nowhere else. Everything preceding execution is just text: text you supplied, text the model returned. The boundary is the instant your own code resolves to act on that text, which makes it the single place where a security control is enforced rather than politely requested.

Four consequences that follow directly.

• Validate as though the arguments came from the internet. They effectively did, since anything in context can influence them. Schema validation, range checks and authorisation belong in the executor, not in the instructions.
• The agent's permissions are the real blast radius. A tool executes with whatever credentials your code holds, so scoping credentials per agent is the control that bounds the worst case. See agent identity.
• Tool output re-enters the prompt. Whatever a tool returns becomes context the model reasons over, so an untrusted tool is an untrusted input channel rather than merely an unreliable one.
• Irreversible tools need a gate, not a warning. A description saying to be careful is read by something with no concept of consequence. Approval has to be enforced in the executor.

What goes wrong?

There are five causes, and only one of them involves the model being factually wrong. The other four are design problems that look like model problems. That is why switching to a more capable model so rarely fixes any of them.

In rough order of how often they appear in production.

• Wrong tool chosen. Two descriptions overlapped. A description problem.
• Right tool, wrong arguments. The model inferred a value the context did not contain. Usually a schema that permitted something it should have rejected.
• Tool not called at all. The model answered from memory instead of checking. This is the most dangerous failure because the output looks normal, and it is why grounding matters more than fluency.
• Called repeatedly. No stopping condition, so the agent retries variations of the same call. The largest avoidable cost line in most token bills.
• Succeeded, wrong outcome. The call returned a valid result that did not answer the question, and nothing errored. This is the 200 OK problem described at AI agent observability.

The third one deserves separating out because it inverts the usual diagnosis. An agent that did not call a tool produces the most convincing wrong answers, since there is no failed call in the trace to investigate and the response reads exactly like a successful one.

How do you design tools for agents?

Differently from how you design an API for developers. A developer reads documentation once, learns the system and remembers it. A model re-reads the description on every call and has no memory of having used the tool before, which changes what a good interface looks like.

Five rules, in order of effect.

1. Fewer tools, more sharply distinguished

   Twelve well-separated tools beat forty overlapping ones. Every additional tool adds a chance of wrong selection and consumes context on every single call.

2. Write the description for selection, not for completeness

   One sentence on what it does, one on when to use it, one on when not to. Exhaustive documentation makes the model worse at choosing, which is the opposite of the instinct.

3. Make the schema strict enough to reject nonsense

   Enumerations rather than free strings wherever the set is known. A schema that accepts anything turns a validation problem into a production incident.

4. Return errors the model can act on

   A message saying which argument was invalid and what was expected lets the agent correct itself. A generic failure produces a retry loop, which is where the cost goes.

5. Register tools centrally rather than per agent

   One definition, one scope, one place to revoke. Tools defined inside individual agents cannot be inventoried, which is how an estate loses track of what its agents can reach.

One design principle that is easy to state and routinely ignored. Design the tool around the decision the agent has to make, not around the system behind it. Exposing an existing API surface verbatim gives the model six calls to assemble an answer where one well-shaped tool would have returned it, and each of those six is an opportunity to go wrong.