D2 — Tool design and MCP integration (18 %)

Two tools, both correctly implemented, both connected, both tested. And the agent keeps calling the wrong one. Nothing is broken — the model chose from the only thing it had, and what it had was two sentences that said the same thing.

That is the guide's first knowledge point, and it is the sentence the whole domain rests on: tool descriptions are the primary mechanism an LLM uses for tool selection, and minimal descriptions lead to unreliable selection among similar tools. The model does not read your implementation. It reads name, description and input_schema, and it decides.

The guide's own pair is the one to memorise, because it is deliberately banal:

{ "name": "analyze_content",  "description": "Analyzes content and extracts key information." }
{ "name": "analyze_document", "description": "Analyzes documents and extracts key information." }

Nothing here is wrong. Both are true. And there is no property in either sentence that lets a model prefer one over the other, so the routing decision falls back to whatever the phrasing of the request happens to echo.

What a description has to carry

The guide names four things that belong in it — input formats, example queries, edge cases, and boundary explanations — and the API documentation puts a floor under the volume: aim for three to four sentences minimum, covering what the tool does, when to use it and when not to, what each parameter means, what it returns, and its limitations.

{
  "name": "extract_web_results",
  "description": "Extracts the ranked result list from a fetched search-engine
    results page: title, URL, snippet and rank for each entry. Use this AFTER a
    page has been retrieved, and only on a SERP — for the body text of an
    ordinary article or a PDF, use extract_data_points instead. Returns an empty
    list, not an error, when the page carries no results. Does not follow the
    result links.",
  "input_schema": {
    "type": "object",
    "properties": {
      "html": { "type": "string", "description": "Raw HTML of the results page" },
      "max_results": { "type": "integer", "description": "Cap on entries returned; default 10" }
    },
    "required": ["html"]
  },
  "input_examples": [
    { "html": "<html>…</html>", "max_results": 25 },
    { "html": "<html>…</html>" }
  ]
}

Two details of that block are cheap and often skipped. input_examples shows typical calls including one with the optional parameter omitted, which is how the model learns that omitting it is legitimate rather than an oversight. And the negative clause — "for an ordinary article, use extract_data_points instead" — is the boundary explanation: it names the sibling tool, so the description does the disambiguation instead of leaving it to the request.

The three repairs, and which symptom calls for which

The guide's skills are three distinct moves. Reading the scenario for which one it describes is most of the work on this task statement.

The split deserves a second look, because it is the one that looks like extra work. A tool named analyze_document has no output contract: "analysis" can be a summary, a table of figures, or a verdict on a claim, and the model picks by guessing. Three tools with three names each carry an implicit promise about what comes back, and the promise is what makes the selection decidable.

Splitting is not free, and 2.3 is the counterweight: a tool set that grows past four or five degrades selection for a different reason. Split a tool because its jobs have different output contracts, not because more tools are tidier.

Naming, so the name works with the description

Two habits from the API documentation, both mechanical:

• Namespace with the service. github_list_prs, slack_send_message. A bare search in a session holding four servers is an invitation to misroute.
• Group related operations behind an action parameter rather than shipping create_pr, review_pr and merge_pr as three tools. The same economy the tool-count rule of 2.3 asks for, applied at design time.

The name itself must match ^[a-zA-Z0-9_-]{1,64}$, which allows letters, digits, underscore and hyphen, up to sixty-four characters.

The system prompt can override a good description

This is the guide's fourth knowledge point and the one people miss, because the tool definitions are where they are looking. A keyword-sensitive instruction in the system prompt creates unintended tool associations.

# System prompt
You are a support assistant. ALWAYS verify the customer's identity before
answering anything.

Nothing in that sentence names a tool. But "verify the customer" matches get_customer closely enough, and "always" carries further than any per-turn wording, so the model now calls get_customer on turns where identity is not in question, including "what are your opening hours". The tool descriptions are fine. The instruction above them is what routed the turn.

The guide's skill is a review, not a rewrite: read the system prompt for keyword-sensitive instructions that might override well-written tool descriptions. The fix is to scope the absolute — "verify the customer's identity before disclosing order or account data" — so the keyword stops attaching to every turn.

A tool fails. The agent now has to decide one thing: call it again, change the arguments, tell the user, or hand over to a human. Every one of those decisions is made from the payload the tool returned — and this is what the payload usually says:

{ "isError": true, "content": [{ "type": "text", "text": "Operation failed" }] }

The guide's knowledge point is the consequence: uniform error responses prevent the agent from making appropriate recovery decisions. The agent will still do something. It will retry a permission denial four times, or give up on a timeout that would have cleared on the second attempt, because nothing in the payload distinguishes them.

isError is the flag MCP gives you: it tells the agent the call failed rather than returning data. Everything that makes the failure actionable is what you put beside it.

{
  "isError": true,
  "content": [{
    "type": "text",
    "text": "{\"errorCategory\": \"transient\", \"isRetryable\": true, \"description\": \"Order service timed out after 5s. Retry in a few seconds.\", \"attempted_query\": \"order_id=12345\"}"
  }]
}

Two error mechanisms, and only one of them is yours

Before the categories, a frontier the protocol draws and a distractor loves. MCP reports failures in two different places, and they are not interchangeable.

Read the second row twice, because it is counter-intuitive and it is the whole of this task statement. A violated business rule is not a protocol error. The call reached the tool, the tool ran, and it decided the operation must not happen. The answer therefore comes back as a normal result whose isError is true and whose content the agent can read. A booking outside the 90-day horizon is not a malformed request; it is a request the tool understood and refused.

That is why everything below is about the content of a result rather than about error codes. The protocol errors are the transport's business and there is nothing for you to design in them. The execution errors are yours, and the agent's recovery decision is made entirely out of what you put in them.

The four categories, and the decision each one enables

The two right-hand columns are the whole point. Retryability is a claim about whether repeating the call can succeed, and it is knowable at the tool, not at the agent. Structured metadata prevents wasted retry attempts. That is the guide's phrasing, and the waste is billed per attempt.

The row that is misread most often is validation. It is retryable, and its retry is not a repetition: the agent repairs its own arguments and calls again. Filing it beside permission because "the call failed for a reason the tool gave" costs you a recovery the agent could have made alone.

Business errors need a sentence a customer can hear

The guide asks for two things on a business rule violation: retriable: false and a customer-friendly explanation. The second is not decoration. The agent is going to relay this to somebody, and "BOOKING_RULE_4171" relays badly.

{
  "isError": true,
  "content": [{
    "type": "text",
    "text": "{\"errorCategory\": \"business\", \"retriable\": false, \"description\": \"Appointments cannot be booked more than 90 days ahead. The earliest available slot inside that window is 12 March.\", \"policy\": \"booking_horizon_90d\"}"
  }]
}

The machine-readable code stays, for logs and for routing. The sentence beside it is what lets the agent answer the customer without inventing the rule.

An access failure is not an empty result

The guide's last skill on this task statement is a distinction, and it is the one that produces silent wrong answers rather than loud ones.

Collapse them and you get one of two defects. Report the empty result as an error and the agent retries a question that has already been answered. Report the timeout as an empty result and the agent concludes, in good faith, that there is nothing to find, and the gap never appears in the final answer.

// Not an error: the catalogue was searched, and it holds no match.
{ "isError": false, "content": [{ "type": "text",
  "text": "{\"results\": [], \"searched\": \"parts_catalog\", \"query\": \"part_no=88-2210\"}" }] }

Local recovery, and what crosses the boundary

The guide asks for local error recovery within subagents: a subagent handles its own transient failures and propagates to the coordinator only what it cannot resolve locally, together with its partial results and what it attempted.

{
  "status": "partial",
  "completed": ["order_lookup", "customer_profile"],
  "failed": [{
    "step": "shipping_status",
    "errorCategory": "permission",
    "isRetryable": false,
    "attempted": "carrier_api.track(tracking_id=1Z999) — 3 attempts, 403 each time",
    "description": "The carrier account has no tracking scope. A human must grant it."
  }]
}

Three properties make that payload useful upstream: the partial results survive, the failed step names its category so the coordinator does not re-attempt a permission denial, and attempted says what was already tried so the retry budget is not spent twice on the same call.

Every tool you add to an agent is a branch it has to evaluate on every turn. The guide puts a number on where that stops working: giving an agent access to too many tools — 18 instead of 4-5 — degrades tool selection reliability by increasing decision complexity.

This is D1's debt, and it is worth being precise about what it claims. Nothing degrades in the model; what degrades is the decision. Eighteen descriptions, some of them adjacent, produce a selection problem that no individual description can solve, which is why 2.1's remedy is the wrong answer here, and why reading the scenario matters more than knowing both remedies.

Scoped tool access

The second knowledge point explains what goes wrong beyond the count: agents with tools outside their specialization tend to misuse them. The guide's own case is a synthesis agent attempting web searches. The tool is there, the turn is hard, and reaching for it is a locally sensible move that produces work nobody asked for.

So each subagent gets the tools its role needs, and no others:

A tool you leave out is not in the agent's session at all. There is no prompt to ignore and no refusal to log: the agent simply works without it. That is what makes the omission stronger than the instruction.

Constrain the tool rather than instruct around it

The guide's second skill is a substitution: replace fetch_url with load_document, which validates that the URL points at a document. The scenario behind it is a document-analysis subagent that, holding a tool able to retrieve any URL, ends up downloading search-engine result pages instead of documents.

{
  "name": "load_document",
  "description": "Fetches a document by URL and returns its text. Accepts PDF,
    DOCX, TXT and Markdown URLs only; rejects any other URL with a validation
    error. Use this to read a document you already have the address of — it does
    not search, and it does not follow links inside the document.",
  "input_schema": {
    "type": "object",
    "properties": {
      "url": { "type": "string", "description": "Direct URL to a .pdf, .docx, .txt or .md file" }
    },
    "required": ["url"]
  }
}

Cross-role tools, scoped rather than opened

Strict scoping has a cost, and the guide names the case: the synthesis agent needs to check a single claim constantly. Sending each check back through the coordinator — which invokes the web research agent, waits, and relays the answer — pays two or three round trips for what is usually a date or a name.

The guide's answer is neither "give it web search" nor "keep sending it back". It is a limited cross-role tool for a specific high-frequency need:

{
  "name": "verify_fact",
  "description": "Verifies one specific claim against a named source document
    and returns a confidence level (high/medium/low) with the supporting
    excerpt. Use this only to check a claim you can already state and whose
    source you can already name — for open-ended research, route the request
    through the coordinator to the web research agent.",
  "input_schema": {
    "type": "object",
    "properties": {
      "claim":     { "type": "string", "description": "The single claim to verify" },
      "source_id": { "type": "string", "description": "Id of the source document to check against" }
    },
    "required": ["claim", "source_id"]
  }
}

Two properties make it a scoped cross-role tool rather than a hole in the scoping. It is narrower in capability than the tool it replaces: it checks a claim against a named source, it does not search. And its description states where its remit ends, so the complex cases keep going through the coordinator. The high-frequency simple case gets a direct path; the rest keeps the architecture.

tool_choice, and what it guarantees here

tool_choice is the request field that decides whether calling a tool is optional, mandatory, or mandatory and named. The field itself — all four values, their behaviour under extended thinking, and their use for structured output — is taught in D4.3, which owns it. What belongs to this task statement is the two uses the guide names, and one thing it does not fix.

{
  "tools": [ /* extract_metadata, enrich_entities, score_relevance */ ],
  "tool_choice": { "type": "tool", "name": "extract_metadata" }
}

Note what the forced call buys and what it does not. It fixes the first action of the turn. Sequencing the rest is a matter of processing the result and issuing another request. The ordering lives in your loop, not in a single parameter.

Everything this task statement configures is a connection to an MCP server. MCP shifts the burden of tool definition and execution off your application and onto dedicated servers. Without it, exposing GitHub to Claude means you author, test and maintain a schema and a function for every repository, pull request and issue operation you want. With it, you connect to a GitHub MCP server that already carries them.

That is also the answer to the question the course flags as a common confusion: MCP and tool use are not the same thing. Tool use is how Claude calls a tool. MCP is where the tool came from: someone else already wrote it.

The two scopes

A server is declared at one of two scopes, and the choice turns on a single question: does the whole team need it?

claude mcp add --scope user writes to that second file: the command and its effect are the same fact seen from two sides, and the guide's wording and the tool's behaviour agree here.

They coexist. Tools from all configured MCP servers are discovered at connection time and are available to the agent simultaneously, whatever scope declared them. Putting a personal server in ~/.claude.json does not cut you off from the project servers. You get the union.

That discovery-at-connection-time property is worth holding as a mechanism and not just a fact. The client asks each server what it provides — a ListToolsRequest, answered with a ListToolsResult — and the collected tool definitions are what accompanies the user's query to Claude. Nothing is discovered lazily mid-turn: a server that failed to start simply has no tools in the set, and the agent works without them exactly as if you had never declared it.

Secrets, by environment variable expansion

.mcp.json is tracked. Tokens are not. The guide's mechanism is environment variable expansion:

{
  "mcpServers": {
    "github": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" }
    }
  }
}

${GITHUB_TOKEN} resolves at launch from the developer's own environment. The file can be committed and shared; each teammate supplies their own credential, and the repository never carries one. type says how the server is reached: "stdio" for a process launched by command, "http" for one reached at a url.

Two properties of the expansion are worth carrying. It accepts a default, written ${VAR:-default}, so an optional setting can ship with a value while a credential stays mandatory. And it applies to more than env: command, args, env, url and headers all go through it, which is what lets a server's address or its authorisation header be per-developer too.

"env": {
  "GITHUB_TOKEN": "${GITHUB_TOKEN}",
  "GITHUB_API_URL": "${GITHUB_API_URL:-https://api.github.com}"
}

Resources, and why they exist beside tools

MCP servers expose three primitives, and the guide is explicit about which two it tests. Its appendix names MCP tools and MCP resources; the in-scope list says "MCP tool and resource design". Prompts are listed here so you recognise them as a distractor.

A resource is closer to an HTTP GET handler than to a tool: a URI comes in, data goes out, and your application decides when to read it. The model does not call it. A direct resource has a static URI; a templated one carries parameters in the URI, which the SDK parses and hands to your function as keyword arguments.

@mcp.resource("docs://documents", mime_type="application/json")
def list_docs() -> list[str]:
    return list(docs.keys())            # the catalogue

@mcp.resource("docs://documents/{doc_id}", mime_type="text/plain")
def fetch_doc(doc_id: str) -> str:      # one entry, by URI parameter
    if doc_id not in docs:
        raise ValueError(f"Doc with id {doc_id} not found")
    return docs[doc_id]

When the agent ignores your MCP tool and uses Grep instead

You connect a server exposing a code-search tool far more capable than Grep — it understands structure, follows imports, returns context. The agent keeps calling Grep. The server is up, the tool is listed: this is not a configuration fault.

The cause is 2.1's, seen from the integration side. Built-in tools ship with detailed, well-tested descriptions. Many MCP tools carry one line generated from a function name. Faced with "Search files" on one side and Grep's full description on the other, the model picks the one it understands.

The guide's skill is the repair: enhance the MCP tool's description to explain its capabilities and outputs in detail, so it stops losing the comparison.

# Before — loses to Grep every time
Search files.

# After — states capability, output, and what the built-in cannot do
Searches the indexed codebase semantically. Given a symbol or a natural-language
description, returns the definition site, every caller with its file and line,
and the import chain that connects them. Unlike a textual search, it resolves
re-exports and aliases, so a function reached through a wrapper module is still
found. Use it to trace how a symbol is used across the repository; use Grep for
a literal string you can spell exactly.

Community server or custom server

The last skill is a build-or-adopt decision with a default: use an existing community MCP server for standard integrations — Jira, GitHub, Slack — and reserve a custom server for workflows specific to your team that nobody else has implemented. Anyone can author a server, and service providers often publish official ones, so the standard integration you are about to write probably exists, maintained, with its schemas already tested.

The six built-in tools are the ones an agent already has before any MCP server is connected, and the guide tests one thing about them: picking the right one. Two pairs account for most of the questions.

Grep against Glob is the first pair, and the trap is that both are described as "searching". Glob never opens a file: it matches paths. Grep never cares about the filename: it matches contents. "Find every test file for the checkout flow" is Glob. "Find every caller of applyDiscount" is Grep.

When Edit fails, Read + Write is the documented fallback

Edit works by matching text that must be unique in the file. When the anchor appears more than once, the edit is refused, and the refusal is deliberate: the tool cannot know which occurrence you meant.

The guide names the fallback: Read the file in full, amend the content, and Write it back.

# runbooks/db-failover.yaml — the line "owner: unassigned" appears 23 times.
Edit(old_string="owner: unassigned", new_string="owner: sre-oncall")
  → refused: the anchor is not unique.

# Fallback
Read("runbooks/db-failover.yaml")        # the whole file, with its structure
→ amend step 14 only
Write("runbooks/db-failover.yaml", …)    # the amended file, written whole

The reason this works where Edit could not is that the full content carries the position the anchor could not express: step 14 is identifiable in context even though its text is identical to twenty-two others.

Building understanding incrementally

The guide's strategy for an unfamiliar codebase is explicit, and its value is as much about context as about correctness: start with Grep to find entry points, then Read to follow imports and trace flows, rather than reading all files upfront.

1. Grep "createCheckoutSession"    → the definition, and three call sites
2. Read src/checkout/session.ts    → what it does, and what it imports
3. Grep "from './session'"         → who consumes it
4. Read the consumers              → how it is used
5. Repeat until the flow is complete

Reading everything first fills the context window with files that turn out to be irrelevant, and the relevant ones then compete for attention with them. Each Grep in the loop above is a filter that decides what is worth a Read.

Tracing a function through wrapper modules

The last skill is a specific failure of the naive approach, and it is worth knowing as a procedure. A single Grep for a function name misses every call made through an alias or a re-export.

# Misses the indirect callers
Grep "analyzeDocument"

# Two passes, as the guide describes
1. Grep "export.*analyzeDocument"   → find every exported name for it
     export { analyzeDocument }
     export { analyzeDocument as analyze }
     export { analyzeDocument as docAnalyze }
2. Grep each of those names          → analyzeDocument, analyze, docAnalyze
                                     → now every caller is found

The order is the substance: first identify all the exported names, then search for each name across the codebase. Searching for the original name alone answers a narrower question than the one that was asked.