Summary: Tools other agents can trust

An agent choosing a tool reads the tool’s name, description, and input schema, and nothing else. It never sees your code. That makes the description the selection mechanism, not documentation, and it makes tool design a writing problem before it is a programming problem. Anthropic’s engineers put the stakes in one line: “Agents are only as effective as the tools we give them.”

Core ideas

• The description is the tool. A three-word description gives the model a coin to flip. Selection becomes reliable when the description states five things: purpose, expected inputs (with formats and an example), what comes back (including what an empty result means), boundaries (read-only or state-changing), and when to use this tool versus its named siblings.
• Write for a reader who cannot ask. Anthropic’s advice is to describe the tool as you would to a new hire, someone who knows none of your abbreviations or formats. A model cannot ask follow-up questions, so implicit context that stays implicit does not exist.
• One tool, one job. The do-everything tool with a mode switch (an action parameter) forces one schema to permit every parameter combination, so the schema can no longer refuse invalid calls. Split it along jobs, each with a strict contract. But do not shatter tools into one per backend endpoint either: when an agent must always chain the same three calls, merge them. The unit is a job the agent performs.
• Names carry selection weight. Group a server’s tools under a shared prefix (inventory_) so they cluster and cannot be mistaken for a neighbor server’s tools. Make sibling names non-interchangeable: if a colleague seeing only the names cannot tell which tool answers a given question, rename.
• Errors are interface. An agent reads the error text and decides its next move on the spot, so errors should communicate specific, actionable next steps, not opaque codes. Keep four cases distinct: transient failures (retrying helps, say so), business-rule refusals (retrying can never help, say what would), permission problems (needs a different caller or a human), and empty results.
• “Found nothing” is not “failed.” The most damaging confusion in the taxonomy. A search that succeeds and finds zero matches is a true answer about the world. Report it as an error and the agent tells a customer the item is sold out while it sits on the shelf.
• Distribute tools by least privilege. Too many or overlapping tools can degrade an agent’s selection and strategy. And a tool never granted is a guarantee, while an instruction not to use it is only a request, which is lesson 1’s decide-versus-enforce trade-off applied to toolsets. Give each agent only the tools its role needs.
• MCP has a builder side. A server exposes tools (functions the model can call, with user approval), resources (file-like data for reading), and prompts. If the agent only needs to read something, expose a resource instead of another tool. In the official Python SDK, a decorated typed function’s docstring becomes the tool definition the model reads, so everything about description craft lands in the docstring.
• Configuration has scopes, and secrets have a place. In Claude Code, local and user scopes keep a server personal; project scope shares it with the team through a version-controlled file (.mcp.json). Environment-variable expansion, a plain reference (${VAR}) or a defaulted one (${VAR:-default}), lets the committed file name the credential while each machine supplies the value. A missing variable with no default fails the whole config load, loudly, which is the schema lesson’s refusal to paper over a gap, applied to configuration.

What changes for you

You stop treating tool descriptions as an afterthought field and start treating them as the most consequential text in the system, revised as deliberately as any prompt. When an agent misbehaves around a tool, you check the interface before blaming the model: was the description ambiguous, did the error say what to do next, did an empty result arrive dressed as a failure? And when your team shares a server, you know the shape of doing it safely: project scope for the configuration, environment variables for the keys, approval prompts respected. The next lesson takes these well-made tools and hands them to a team: orchestration, and what it takes for several agents to survive real failures together.