▲ Claude Academy
Sign in

Vault / wiki/301/cca-domain-2-tools-mcp.md

updated 2026-05-28

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

How to define tools the LLM uses well, and how MCP fits in.

Topics

2.1 Tool description quality

  • Description = teacher's note: "Use when X, don't use when Y."
  • Disambiguate from sibling tools explicitly.
  • Mention required params in description (model picks defaults better).
  • Sub-500 tokens; long descriptions dilute.

2.2 Input schema design

  • JSON Schema with type, properties, required, enum, description per property.
  • Enums beat free-form strings for fixed vocabularies.
  • Nullable: {"type": ["string", "null"]}.
  • Provide defaults for optional fields.
  • Validate inputs at the tool boundary; return structured errors on violation.

2.3 Output design

  • Return structured short results, not walls of text.
  • Include IDs / timestamps for provenance.
  • For large data: return a resource URI Claude can fetch on demand.
  • Multimodal: tool results can include image blocks (screenshots from a browser tool, e.g.).

2.4 Tool choice control

  • auto — Claude decides (default).
  • any — forces some tool call.
  • {type: "tool", name} — forces specific tool (great for structured extraction).
  • none — disables tools.

2.5 Parallel tool use

  • Claude can return multiple tool_use blocks per turn.
  • Server returns all tool_result in one user turn.
  • Encourage via independent tools + a system-prompt nudge.

2.6 Error responses (huge in this domain)

TypeRetry?Example message
transientYes"Rate limited. retry_after_ms=2000."
permanentNo"ticket-1234 not found."
validationNo (model must fix call)"param id must be UUID."
uncertainDefensive read first"Payment status unknown; call check_payment before retrying."
user_declinedNo"User declined confirmation."
unavailableMaybe (after delay)"Service down for maintenance until 14:00."

Always include is_error: true and a model-readable message.

2.7 MCP primitives — who decides

  • Tools: model-controlled.
  • Resources: application-controlled (the host attaches them).
  • Prompts: user-controlled (slash commands).

Choosing the right primitive is a frequent question.

2.8 MCP trust & configuration

  • Config scopes: project-local > project-shared > user > enterprise.
  • Destructive tools should require user confirmation.
  • Use scoped credentials (least privilege).
  • Never put plaintext secrets in config; use env-var substitution.

2.9 MCP transports

  • stdio: local subprocess. Easy. No auth.
  • SSE: legacy remote.
  • Streamable HTTP: current remote standard. OAuth 2.1.

Common question shapes

  • "Which MCP primitive for [scenario]?" → tool / resource / prompt mapping.
  • "Tool keeps getting called for the wrong question — what's the fix?" → Improve description; add explicit "don't use when".
  • "Tool returned an error. What should the agent do?" → Distinguish transient/permanent/uncertain; choose retry vs adapt vs escalate.
  • "How to expose internal MCP server to multiple users without local install?" → Streamable HTTP + OAuth.
  • "Tool returns 20KB JSON. How to keep context lean?" → Return resource URI.

Cheatsheet

  • One tool, one verb.
  • Description is the prompt.
  • Enums > strings, optional > required.
  • Errors are structured and model-readable.
  • Resources for read, tools for do, prompts for user-invoked templates.

See also