Domain 2 — Tool Design & MCP Integration (18%)

How to design tools an LLM agent can use reliably, how to structure tool errors, and how the Model Context Protocol (MCP) connects agents to external systems.

Subtopics to cover

1. Tool interface design — parameters, descriptions, identifiers.
2. Tool output and composition — structured output, mechanical vs. decision-requiring composition, pagination, progressive availability.
3. Error handling in tools — error categories, retry responsibility, uncertain side effects.
4. MCP fundamentals — tools vs. resources vs. prompts; the three building blocks.
5. MCP advanced — annotations and trust, tool search, transports, notifications, MCP in Claude Code.

Key concepts

Tool interface design

• Tool descriptions must explain what, when, why, and limitations — not a one-liner.
• Use enums for closed sets; use a lookup-then-act pattern for ambiguous names.
• Prefer stable identifiers over derived/computed values as parameters.
• Split tools when constraints are interdependent — don’t fold separate decision points into one composite tool.
• Don’t encode format hints in parameter names; don’t make everything a free-text string.

Tool output and composition

• Return structured, compact output including downstream IDs the agent will need next — not just human-readable prose.
• Mechanical composition (tool A’s output feeds tool B with no judgment) can be combined; decision-requiring composition should stay separate so the model can choose.
• Pagination for large result sets; progressive availability (a discovery/search tool) for large tool sets instead of exposing everything at once.
• requires_review boolean with calibrated thresholds; preview-then-execute with single-use confirmation tokens for high-impact actions.

Error handling in tools

• Categorize errors: transient infrastructure, permanent validation, business rule, permission, uncertain write state.
• Application-level errors are normal results with isError: true — not thrown exceptions.
• Retry responsibility: tool-level retry for safe operations; model-level when a strategy change is needed.
• Never mark an uncertain side effect as retryable — a write that may have partially succeeded must not be blindly retried.
• Give the model a retryable flag and structured fields — don’t make it parse free-text errors.

MCP

• MCP is an open standard connecting applications to external systems. Three building blocks:
  • Tools — model-controlled actions.
  • Resources — application-controlled context / reference material.
  • Prompts — reusable workflows (surface as slash commands).
• Use a resource for stable reference material; use a tool for dynamic/computed content.
• Annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) are untrusted hints, not security boundaries.
• JSON-RPC protocol errors ≠ tool execution errors (isError: true).
• Tool search returns a ranked shortlist before the agent selects — better than a monolithic tool list. List-changed notifications support dynamic availability.
• MCP scope in Claude Code: project (shared) > local (user/project) > user (global) — that’s the precedence order.

Common pitfalls (distractor patterns)

• Encoding format hints in parameter names; making everything free-text.
• Returning only human-readable prose with no IDs for the next step.
• Combining separate decision points into one composite tool.
• Assuming descriptions or annotations enforce security.
• Throwing exceptions for expected business errors.
• Marking uncertain side effects as retryable; returning empty data for backend failures.
• Using a tool where a resource fits better; assuming MCP handles auth and retries for you.
• Writing minimal tool descriptions.

Interview / exam angle

• “A tool failed but may have written data — retryable or not?” — Not retryable. Uncertain side effects must surface for the model/human to reconcile, never blind-retried.
• “Static company policy doc the agent needs — tool or resource?” — Resource. It’s stable reference context, application-controlled.
• “A self-reported readOnlyHint: true annotation — can you rely on it for security?” — No. Annotations are untrusted hints; enforce read-only in code.
• “50 tools overwhelm the agent — what’s the fix?” — Progressive availability: a search/discovery tool returns a ranked shortlist instead of exposing all 50.

See also: ../01_agentic_architecture_orchestration/README.md (tool distribution across agents), ../03_claude_code_config_workflows/README.md (MCP in Claude Code).

Interview angle

• “What makes a tool description good?” - it says what the tool does, when to use it, when not to, and its limitations. A one-line description is the most common cause of an agent calling the wrong tool, and it is cheaper to fix than any prompt change.
• “How should a tool report failure?” - application errors as a normal result with an error flag and a message the model can act on, not a thrown exception. The model needs to read the failure and decide; an exception just ends the turn.
• “When do you split a tool versus combine two?” - combine when the composition is mechanical (output of A always feeds B with no judgement); keep separate when the model must make a decision between them. Folding a decision point into one tool removes the model’s ability to choose.
• “What changed in the 2026-07-28 MCP spec?” - a stateless protocol core with session management removed from the transport, multi-round-trip requests, header-based routing, cacheable list results and an extensions framework. Anything describing MCP as session-oriented at the transport level predates it.
• “How do you handle a large tool catalogue?” - progressive availability: a search or discovery tool rather than exposing hundreds of definitions, which otherwise consume context and degrade selection accuracy.