Cheat Sheet · Domain 2

Tool Design & MCP Integration

The Architect's blueprint for creating high-reliability tool interfaces and Model Context Protocol (MCP) servers.

🛠️ Tool Interfacing

Selection Logic

Naming camelCase, verb-noun (get_user), globally unique

Descriptions Must specify *how* and *why*, not just *what*.

Enum Power Strict enums prevent hallucinated inputs.

tool_choice "any" = forced tool, "auto" = Claude decides.

Payload Health

Trimming Filter to relevant fields in PostToolUse (reduce tokens).

Flattening Depth < 3 is ideal for LLM reasoning.

Formatting ISO 8601 for dates, string IDs for numbers.

🚨 Error Taxonomy

Severity Scale

isError: true Sets the loop to "recovery mode".

transient Retryable. Network blips, timeouts (Retryable: true).

validation Claude fixed its input. Re-run allowed.

permission Auth failure. Stop + escalate human.

business Policy hit (e.g. past return date). Explain policy.

The Reliability Matrix

Pattern	Implementation	950+ Impact
Empty Results	`isError: false, found: false`	Prevents loop thrashing on valid nulls.
Wait Hint	`retryAfterSeconds: 30`	Prevents hammering struggling services.
Sanitization	`customerFriendlyMessage`	Prevents leaking DB structure to UI.
MCP Auth	`${ENV_VAR}` in .mcp.json	Security hygiene; never commit real tokens.

🎯 950+ Architect's Subtle Nuance

The "Ambiguous Tooling" Trap

If two tools (e.g., jira.get_issue and github.get_issue) share names, Claude will hallucinate or pick randomly. To score 950+, you must prefix tools (jira_get_issue) and enhance descriptions with "Negative Boundaries" (e.g., 'Do NOT use this for GitHub PRs; use github_get_issue instead'). This creates 100% deterministic routing even with overlapping schemas.

The "isError" Silent Fail

Never return isError: false for an operation that didn't complete its intended side effect. If a DB write fails but you return {"status": "error"} with isError: false, Claude thinks the application succeeded but the data was bad. This prevents Claude from entering its retry/fix routine. isError: true is the signal to the model, not just the user.

← Previous Summary Domain 1: Agentic Architecture

Next Summary → Domain 3: Claude Code