Tool Design & MCP Integration flashcards

Every card in this deck

The whole deck as a list, for scanning or printing.

What is the primary mechanism LLMs use for tool selection?

Tool descriptions. The model reads them to decide which tool to call, so two tools with minimal, near-identical descriptions are genuinely indistinguishable to it — no amount of surrounding metadata compensates.

What regex must a Messages API client tool's name match?

^[a-zA-Z0-9_-]{1,64}$

What three fields are required in a client tool definition?

name, description, input_schema (input_examples is optional).

What optional fields does an MCP tool definition add beyond name/description/inputSchema?

title, outputSchema, annotations.

How does an MCP client discover and execute tools?

tools/list to discover; tools/call to execute.

What is Anthropic's single most important factor in tool-use performance?

Extremely detailed tool descriptions.

What is Claude Code's truncation limit for tool descriptions and server instructions?

2KB each — put critical details near the start.

What does Claude Code's tool search do by default?

Defers MCP tool definitions from context; Claude searches for and loads only the tools it actually uses.

What are the five elements of a production-grade tool description?

Purpose, expected inputs with formats, example queries, edge cases/limitations, explicit boundaries vs similar tools.

A tool is misrouted because two descriptions overlap. What's the correct first fix?

Expand/improve the descriptions — not few-shot examples, not a routing classifier, not tool consolidation.

Instead of list_users, list_events, create_event, what single workflow tool should you build?

schedule_event — a consolidated workflow tool, not an API wrapper.

What two forms of namespacing does Anthropic's tool-writing guidance describe?

By service (asana_search) and by resource (asana_projects_search).

What mistake-proofing example did Anthropic give for tool schemas?

Requiring absolute filepaths (instead of allowing relative) eliminated the model's path errors entirely.

What evidence shows tool description quality is measurable, not just stylistic?

SWE-bench Verified SOTA followed description refinements; a tool-testing agent's rewritten descriptions cut future task completion time by 40%.

What are MCP's two error-reporting mechanisms?

Protocol errors (standard JSON-RPC — unknown tool, invalid args) vs tool execution errors (isError: true inside a successful result).

What does isError: true signal to the agent?

Tool execution failed — the model should reason about recovery, not treat the text as a normal successful result.

What's the Messages API tool_result field equivalent to MCP's isError?

is_error (optional boolean) on the tool_result block; the MCP connector's mcp_tool_result carries the same field.

What field carries structured JSON tool output in MCP?

structuredContent — also serialised into a text block for backwards compatibility.

If a tool declares an outputSchema, what's the server's obligation?

MUST provide structured results conforming to it; the client SHOULD validate against it.

Name MCP's four error categories and whether each is retryable.

Transient (retry after delay) · validation (fix input, retry) · business (never retry) · permission (never retry, escalate).

What question does isRetryable answer?

"Can a retry ever succeed" — not "will the identical request succeed unchanged."

How do you structurally distinguish an access failure from a valid empty result?

Access failure = isError: true (couldn't reach data); valid empty result = isError: false with resultCount: 0 (reached data, found nothing).

What does the MCP spec say about human oversight of tool invocations?

There SHOULD always be a human in the loop with the ability to deny tool invocations.

How many times does Claude automatically retry a malformed tool_use call before apologising?

2-3 times, with corrections — an automatic model-level behaviour.

How does Claude's automatic malformed-call retry differ from your tool's isRetryable flag?

Automatic retry fixes an invalid call before execution; isRetryable is a deliberate agent-level signal about retrying after execution failure.

In the Agent SDK, what happens when a custom tool handler throws an uncaught exception?

The SDK's in-process MCP server catches it and converts it to an error result automatically — the agent loop is not stopped.

In multi-agent error propagation, what should a subagent do first with a transient failure?

Attempt local recovery; only propagate errors it cannot resolve, along with partial results and what was attempted.

What are the four documented tool_choice types?

auto, any, tool, none.

Which tool_choice type is the default when tools are provided?

auto.

Which tool_choice type is the default when no tools are provided?

none.

What JSON shape forces a specific tool?

{"type": "tool", "name": "..."}

What visible model behaviour does forcing tool_choice to any/tool suppress?

Natural-language commentary before the tool_use block — the API prefills the assistant message to force the tool call.

Which tool_choice types are compatible with manual extended thinking?

Only auto and none — any and tool produce an error alongside manual extended thinking.

Where does disable_parallel_tool_use live in the request?

Inside the tool_choice object — it is not a top-level request parameter.

With tool_choice auto + disable_parallel_tool_use: true, how many tools can Claude call?

At most one — Claude may still return plain text with no tool call.

With tool_choice any/tool + disable_parallel_tool_use: true, how many tools does Claude call?

Exactly one.

What happens to prompt caching when you change tool_choice between turns?

Cached message blocks are invalidated (must be reprocessed); tool definitions and the system prompt remain cached.

What is the optimal number of tools per agent?

4-5 tools, scoped to that agent's specific role.

What is a "scoped cross-role tool"?

A constrained version of another role's capability given directly to an agent for its high-frequency simple case; complex cases still route through the coordinator.

What failure mode does Anthropic's context-engineering guidance name for bloated tool sets?

Tools covering too much overlapping functionality create ambiguous decision points about which tool to use.

What command adds a remote HTTP MCP server?

claude mcp add --transport http <name> <url>

What command shape adds a local stdio MCP server?

claude mcp add [options] <name> -- <command> [args...] — the -- separator is required.

What command adds a server directly from a JSON definition?

claude mcp add-json <name> '<json>'

What are the three MCP server configuration scopes?

local (default), project, user.

Where is a local-scoped MCP server stored?

~/.claude.json, nested under that project's path — loads only in that project, private to you.

Where is a project-scoped MCP server stored?

.mcp.json in the project root — version-controlled and shared with the team.

Where is a user-scoped MCP server stored?

~/.claude.json — available across all of your projects.

What were "local" and "user" scope called in older Claude Code versions?

local was called "project"; user was called "global."

What is the MCP server scope precedence order when a name collides?

local > project > user > plugin-provided servers > claude.ai connectors — the whole entry from the winning source is used, fields are never merged.

How does MCP "local scope" differ from general "local settings"?

MCP local scope lives in ~/.claude.json (home directory); general local settings live in .claude/settings.local.json (project directory).

What are the two environment-variable expansion forms in .mcp.json?

${VAR} and ${VAR:-default}.

In which .mcp.json fields does variable expansion work?

command, args, env, url, headers.

What are the two standard MCP transports per the spec?

stdio and Streamable HTTP — clients SHOULD support stdio whenever possible.

What MCP transport is deprecated in Claude Code?

Standalone SSE — use HTTP servers instead where available.

What alias does the .mcp.json "type" field accept for "http"?

"streamable-http" — so configs copied from vendor docs work unmodified.

What's the Agent SDK's transport-choice heuristic?

Command to run → stdio; URL → HTTP or SSE; tools built in your own code → SDK MCP server.

How do you check MCP server status inside a Claude Code session?

/mcp

What must happen before Claude Code uses a project-scoped server from .mcp.json?

It prompts for approval; reset those choices with claude mcp reset-project-choices.

How does Claude Code authenticate to a remote MCP server requiring OAuth?

Via /mcp or claude mcp login <name>; tokens are stored securely and refreshed automatically.

How do you reference an MCP resource directly in Claude Code?

@server:protocol://resource/path — it's fetched and attached automatically.

What format do MCP prompts take as Claude Code slash commands?

/mcp__servername__promptname

What are Claude Code's MCP tool output token limits?

Warns above 10,000 tokens; caps output at 25,000 tokens by default (raise via MAX_MCP_OUTPUT_TOKENS).

What is the MCP tool naming pattern?

mcp__<server-name>__<tool-name>, e.g. mcp__github__list_issues.

When should you build a custom MCP server instead of using a community one?

Only when the team has specific workflows or proprietary systems that community servers can't handle.

What does Grep search?

File contents — patterns like function calls, error messages, import statements.

What does Glob search?

File paths, by naming pattern — e.g. **/*.test.tsx.

What is Edit's failure mode, and what safety purpose does it serve?

Fails when old_string matches more than one location — prevents accidentally changing text you didn't mean to touch.

What's the documented recovery order when Edit reports a non-unique match?

Widen old_string with more surrounding context, or set replace_all: true; fall back to Read + Write only when neither can disambiguate.

What's the correct incremental codebase-exploration order?

Grep for entry points → Read to trace flows → Grep again for wrappers/barrels → Read only what's justified by prior findings.

Beyond Read/Write/Edit/Bash/Grep/Glob, which two built-in tools does the Agent SDK reference name explicitly?

WebFetch (fetches external content) and Agent (spawns subagents). The docs list them followed by "and others" — treat the roster as open-ended, not a closed set of six.

What does the SDK's tools option control?

Which built-ins are available to the agent; tools: [] removes all built-ins (MCP tools are unaffected).

What tool spawns subagents, and what was it previously called?

Agent — renamed from Task in Claude Code v2.1.63; allowedTools must include it to auto-approve subagent invocations.

What's the difference between --allowedTools and --tools?

--allowedTools skips the permission prompt for listed tools; --tools restricts which tools are available at all.

In --disallowedTools, what does a bare tool name do versus a scoped rule?

A bare name (e.g. "Edit") removes the tool from context entirely; a scoped rule (e.g. Bash(rm *)) leaves the tool available and denies only matching calls.

Why does the trailing space matter in Bash(git diff *)?

Without it, Bash(git diff*) would also wrongly match unrelated commands like git diff-index.

What does a WebFetch(domain:*.example.com) rule match?

Any subdomain at any depth — but not the apex domain example.com itself.

How do MCP permission rules scope access to a server's tools?

mcp__server (whole server) · mcp__server__* (wildcard, also whole server) · mcp__server__tool (one specific tool).

In the deprecated-function-plus-tests scenario, what does each step in Grep→Glob→Grep find?

Grep finds direct callers by content → Glob finds their sibling test files by naming convention → Grep again catches indirect consumers through wrapper/barrel names.