Day 2 · Lesson 2 — Agent Tools & MCP
The difference between a tool an agent wields and one it fumbles is design.
Lesson 1 said a tool is a contract. This lesson is how to write a contract the model actually honours. None of it is exotic, but skip it and even a capable agent picks the wrong tool, calls it wrong, or drowns in its output. A tool's docs are its user interface, and the user is the model.
From Lesson 1: a tool's description is written mainly for —
The model. Name, description, and parameter docs are all passed into the request context. They're instructions, not comments, so write them for the reader who acts on them.
Everything about a tool that the model sees (name, description, parameter docs) is passed to it as context.1 Compare:
# ✓ the model knows exactly when and how to call this
def get_product_information(product_id: str) -> dict:
"""Retrieve full details for a product by its unique ID.
Returns: product_name, brand, description, category, status
(e.g. status is 'active' | 'inactive' | 'suspended')."""
# ✗ the model is guessing
def fetchpd(pid):
"""Retrieves product data. Args: pid: id. Returns: dict of data."""Rules that follow from this: clear, specific names (create_critical_bug_in_jira,
not update_jira); describe every parameter and keep the list short;
add targeted examples for tricky cases; document default values.
1 · Describe actions, not implementations. Your instructions should say what,
not how: "create a bug to describe the issue," not "use the create_bug tool."
Don't dictate a fixed workflow; state the objective and let the model choose tools.1
(Notice this is the factory's "success criteria, not step-by-step"
from Day 1 L3, reappearing at the tool layer.)
2 · Publish tasks, not API calls. A tool should encapsulate a task the agent performs, not thinly wrap an enterprise API with a hundred parameters. APIs are for human devs with full context; a tool is chosen at runtime by a model that must decide which parameters to pass. Wrap the task, and it calls correctly far more often.1
3 · Stay granular. One tool, one well-documented responsibility. Avoid "multi-tools" that run long workflows in a single call. They're hard to document, and the model uses them inconsistently.1
4 · Design for concise output. A tool that dumps a giant table or file swamps the context window, and that output usually lands in conversation history, taxing every subsequent call. Return a handle instead: write the result to storage and hand back a reference.1
Two often-skipped moves pay off twice. Schema validation on inputs/outputs is both documentation (it tells the model the shape) and a runtime check (it catches wrong calls). And error messages are an instruction channel: the tool's error is fed back to the model, so make it actionable:1
✗ "Error 404"
✓ "No product found for ID 'X'. Ask the customer to confirm the product
name, then look it up by name to get the correct ID."The second one tells the agent how to recover. The first makes it guess.
Schema validation is a build-time V Validation seed, a runtime check
that a tool is being called correctly. "Publish tasks, not API calls" is quietly a
least-privilege move: a narrow task-tool can do far less harm than a broad API wrapper if an
agent is tricked into misusing it (hold that for the confused-deputy lesson, D2·5). And clear names +
actionable errors both feed the E Evidence trail: a logged call that
reads create_critical_bug_in_jira with a descriptive failure tells an auditor what
happened without guesswork.
Ladder read: none of this enforces anything at runtime. It's still build-time hygiene. But a well-designed tool surface is what makes the L3 Controlled enforcement (gateways, allowlists, scoped credentials) in the next lessons tractable.
Write each tool's docstring as if onboarding a new teammate who will only ever read that text. Return handles, not blobs. Make every error tell the agent its next move.
Adopt a tool-design checklist in review: clear name, all params documented, single responsibility, schema on both ends, actionable errors. A fumbled tool is a shared cost: every agent that calls it inherits the confusion.
Standardise task-shaped tools over raw API wrappers across teams. It's both a reliability win and a security one: narrow tools are smaller blast radii when something goes wrong.
Recall, don't re-read.
The best tool encapsulates —
A task. A model chooses tools at runtime with limited context, so a task-shaped tool is the one it calls correctly, rather than a 100-parameter API wrapper or a giant multi-step tool.
Your instruction to the model should say —
Describe the action (what), not the tool or the workflow (how). Naming tools or dictating steps creates brittle coupling and confuses the model, especially when tools change.
A good tool error message should —
The error is fed back to the model, so it's an instruction channel: name the problem and the recovery step. A bare code makes the agent guess its way out.
Open the worst-documented tool your agents call. Rewrite its description and its error messages so a stranger, or a model, would know exactly when to use it and what to do when it fails. That single rewrite often fixes an "agent bug" that was never a model problem (Day 1 L2: configuration failure).
The Google ADK tools docs and the MCP tools specification are the working references; both encode these practices in their schemas.
Up next → Day 2 · Lesson 3: MCP, The N×M Problem & Host/Client/Server. Once every team writes good tools, a new problem appears: connecting N models to M tools without building N×M custom connectors. That's the problem MCP exists to solve.
Related: Glossary: tool · ← Day 2 L1: Tools · Day 1 L3: success criteria not steps · Course home