Practice: Tools other agents can trust
Self-check
Section titled “Self-check”Six short questions. Answer each in your head before opening the collapsible. Active retrieval is where the learning sticks.
1. When an agent chooses which tool to call, what does it actually read?
Show answer
The tool’s name, its description, and its input schema. It never reads the tool’s source code. That is why the description is the selection mechanism itself, not documentation attached to the tool, and why a three-word description makes selection unreliable.
2. What five things does a selection-worthy tool description state?
Show answer
Purpose (the job in one sentence), expected inputs (each parameter’s meaning and format, with an example where format matters), what comes back (including what an empty result means), boundaries (what it will not do, read-only or state-changing), and when to use it versus its nearest sibling tools, named outright.
3. What is wrong with one tool that takes an action parameter for search, check, reserve, and adjust?
Show answer
One schema must now permit every parameter combination any action might need, so it can no longer refuse invalid combinations, and the agent has to guess which ones are valid. Split along jobs, one strict contract each. The counterweight: do not create one tool per backend endpoint either; if the agent always chains the same calls to do one job, merge them. The unit is a job the agent performs.
4. Name the four error cases a well-designed tool keeps distinct.
Show answer
Transient failures (a timeout; retrying is likely to help, and the error says so). Business-rule refusals (the request was understood and rejected; retrying the identical call can never help; the error says what would). Permission problems (this caller may not do this at all; needs a different caller or a human). Empty results (the query succeeded and found nothing, which is a true answer about the world, never to be reported as an error).
5. Why is handing an agent fewer tools both a reliability move and a safety move?
Show answer
Reliability: too many or overlapping tools degrade selection; every extra tool competes for attention on the context desk and makes the choice harder. Safety: a tool never granted is a guarantee the agent cannot misuse it, while an instruction not to use it is only a request. That is lesson 1’s decide-versus-enforce trade-off applied to tool distribution.
6. Your team shares an MCP server through version control. How do the API keys stay out of the repository?
Show answer
The shared configuration lives in a project-scoped file (.mcp.json) that gets committed, but it references credentials by environment variable, a plain reference (${VAR}) or one with a default (${VAR:-default}). Each machine supplies its own value at load time. The committed file names the secret and never contains it, and a missing variable with no default fails the config load loudly.
Try it yourself
Section titled “Try it yourself”Design exercise: a toolset an agent could trust.
Pick a system you know well: a spreadsheet you maintain, a database at work, a folder of documents, a hobby project’s data. Imagine exposing it to an agent through three tools. On paper or in a note:
- Name the three tools. Use a shared prefix, and make the sibling names pass the cover test: would a colleague seeing only the names know which tool answers a given question?
- Write the full description for one of them. Purpose, inputs with formats and an example, what comes back, boundaries, and when to use it versus the other two, named outright. Then reread it as a new hire who can ask no follow-up questions. What is still implicit? Make it explicit.
- Draw the error table: for each tool, write one transient failure, one business-rule refusal, one permission problem, and what an empty result means. For each, write the exact sentence the agent would read, including whether retrying can help.
- Decide distribution: if two different agents used this system (say, one that answers questions and one that makes changes), which tools does each get? Which tool does neither get?
- Sketch the shared configuration: a project-scoped entry that runs your imaginary server, with every credential referenced by variable name only.
You have just done the whole lesson in miniature. If you want to make it real, the build-server tutorial at modelcontextprotocol.io turns step 2’s description into a working docstring in about an hour.
Flashcards
Section titled “Flashcards”Q. What does an agent read when choosing a tool?
The name, the description, and the input schema. Never the source code. The description is the selection mechanism.
Q. What five things does a good tool description state?
Purpose, expected inputs (with formats), what comes back, boundaries, and when to use it versus its named sibling tools.
Q. Who is the imagined reader of a tool description?
A new hire on your team who can ask no follow-up questions. Implicit context that stays implicit does not exist for the model.
Q. What is wrong with a do-everything tool with an action parameter?
Its single schema must permit every parameter combination, so it can no longer refuse invalid calls. Split it along jobs, one strict contract each.
Q. What is the right unit for one tool?
One job the agent performs. Not one tool for everything, and not one tool per backend endpoint. If the agent always chains the same calls for one job, merge them.
Q. What is namespacing for tools?
Grouping related tools under a common prefix (inventory_, docs_) so they cluster together and cannot be confused with another server’s tools.
Q. Name the four error cases to keep distinct.
Transient failure (retry helps), business-rule refusal (retry never helps; say what would), permission problem (needs a different caller or a human), and empty result (a successful answer, not an error).
Q. Why must 'found nothing' never be reported as an error?
Because it is a true answer about the world. An agent that reads it as a failure tells a customer the item is sold out while it sits on the shelf.
Q. Why give each agent only its role's tools?
Selection degrades as the menu grows, and a tool never granted is a guarantee where an instruction is only a request. Least privilege is both an accuracy feature and a safety feature.
Q. Tools versus resources on an MCP server: what is the split?
Tools are functions the model can call to act, with user approval. Resources are file-like data for reading. If the agent only needs to read something, expose a resource, not another tool.
Q. Where does description craft land when you build an MCP server in Python?
In the docstring and type hints of the decorated tool function. The docstring becomes the tool definition the model reads.
Q. How do shared MCP configs keep credentials out of version control?
Project scope commits a config file (.mcp.json) that references secrets by environment variable (${VAR}, or ${VAR:-default} with a fallback); each machine supplies the value. Missing variable with no default fails the load loudly.