HASZB_AIHASZB_AI

Search across courses, lessons, glossary terms, prompts and tools.

Stage 7 · APIs, MCP & Connectors

What a tool call really is

The model does not call anything. It writes a structured request, and your code decides what to do with it.

6 min read

In this lesson

  • Trace a tool call from description to result
  • Explain why the model never executes anything
  • Write a tool description that gets chosen correctly

"The model called the API" is a convenient shorthand and it is wrong in a way that matters. Understanding what really happens tells you where your security controls go.

The actual sequence

1. You describe the tools. Alongside the prompt, you send a list: each tool's name, what it does, and a schema for its parameters.

2. The model emits a request. Instead of prose, it produces structured output:

{
  "tool": "get_order",
  "arguments": { "order_id": "4471" }
}

That is text. Nothing has happened yet.

3. Your code decides. It parses the request and — this is the important part — chooses whether to honour it. Is the tool allowed here? Are the arguments valid? Does this user have permission? Does it need approval first?

4. Your code executes it. The real HTTP request, database query or file operation happens in your process, with your credentials.

5. The result goes back as text. Success or failure, appended to the conversation. The model reads it and decides what to do next.

Descriptions are how selection happens

The model picks a tool by reading the descriptions. That makes wording functional, not documentation.

Weak:

search — searches

Strong:

search_orders — Find customer orders by email address, order ID or date range. Returns up to 20 matching orders with status and total. Use this for questions about existing orders. Does not create or modify orders.

The difference: it says what the tool covers, what it returns, when to use it, and what it explicitly does not do. That last clause prevents a large share of wrong selections.

Rules that hold up:

  • One clear job per tool. Tools that overlap get confused with each other.
  • Say when not to use it. Especially where two tools are adjacent.
  • Describe the return value. It affects whether the model expects more steps.
  • Name parameters plainly. start_date beats sd.

Validate before executing

Never pass model-produced arguments straight through. The model can produce well-formed requests that are wrong — an ID that does not exist, a date in the wrong century, a recipient outside your organisation, a limit of 100,000.

Check types, check ranges, check permissions, and return a useful error when something fails. "order_id must be numeric, received 'recent'" lets the model correct itself on the next iteration. A generic failure does not, and it will try the same thing again.

Why the shorthand is dangerous

If you believe the model calls the API, it is natural to think of safety as prompting the model correctly. Once you see that your code sits between the request and the execution, it becomes obvious that safety is an ordinary engineering problem in your own codebase — which is much better news.