Tool Design & the Model Context Protocol

An agent is only as good as its tools. The earlier chapters on function calling covered how a model requests a tool. This chapter is about the other side: designing tools that a model can use correctly on the first or second try, and the protocol that is becoming the standard way to connect them.

Imagine hiring a capable cook who has never seen your kitchen. Labeled drawers, knives stored where you expect, a thermometer that beeps when something is wrong all help them work well. A confusing kitchen, with two similar-looking tools that do different things, causes mistakes. Anthropic's guide on agents says to put as much care into the interface between agent and tool, which it calls the agent-computer interface, as you would put into a human-computer interface.

• -Write the description like a prompt: say what the tool does, when to use it, what each input means, and give an example. If a new engineer would need to ask a question, the model will too.
• -Make mistakes hard to commit. Anthropic's example is requiring absolute file paths, which removed a whole class of errors that arose from relative paths once the agent changed directories.
• -Prefer formats the model has seen plenty of, and avoid overhead such as counting lines or escaping a large block of code.
• -Return what is useful and no more. A tool that dumps 6,000 tokens when a 200-token answer would do fills the context quickly.
• -Keep tools distinct. Two tools with overlapping purposes force the model to guess. A few well-chosen tools beat many similar ones.
• -Test with many inputs, watch where the model goes wrong, and revise the tool, not only the prompt.

When a tool call is invalid, the message that comes back is the model's only guide to fixing it. "Error 422" teaches nothing. A message that says what was wrong and what to do lets the agent correct itself in one step. The code defines two tools, validates six calls, and prints the message each would receive. Press Run and read the messages as if you were the model.

Each message names the problem and the fix. The quoted order number gets "must be an integer, but got str '48213'". The missing amount is called out by name. The refund of 250 is stopped at the limit and sent to a human, which keeps a spending rule in code where the model cannot argue with it. The unknown tool call lists the tools that do exist. Validation like this is cheap, and it also protects you, since a model's tool call is untrusted input.

Every application that wanted to give a model access to a tool or a data source used to write its own integration. The Model Context Protocol, or MCP, is an open standard that replaces those one-off integrations. A server exposes capabilities, such as tools the model can call, data it can read, and reusable prompts. A client, usually an AI application, discovers what a server offers and calls it in a uniform way. Write a server once, and any compatible application can use it.

• -Benefit: less glue code, and a shared way to describe tools, so they can be reused across applications and models.
• -Governance: Anthropic donated MCP in December 2025 to the Agentic AI Foundation, a directed fund under the Linux Foundation, co-founded with Block and OpenAI, so no single vendor controls it. Anthropic reported more than 10,000 active public servers.
• -Caution: a standard makes it easy to connect many tools, which also makes it easy to connect too many, or untrusted ones.

• -Least privilege: give each agent only the tools and permissions the task needs. An agent that cannot delete data cannot be tricked into deleting it.
• -Untrusted outputs: text returned by a tool, a web page, or an email may contain instructions meant for the model. This is indirect prompt injection, covered in the safety evals chapter. Treat tool output as data.
• -Human approval for actions that spend money, send messages, or cannot be undone.
• -Vet servers: use servers you trust, review what they expose, and watch for a server changing its tools after you approve it.
• -Log every tool call with its arguments, so that you can audit what the agent did.