MCP and Tool Design

Situation

A custom MCP server exposes MCP prompts (like a deploy checklist and an incident-response template) plus tools. How do those prompts become usable inside Claude Code?

Recommended approach

They appear as slash commands in the form /mcp__servername__promptname, with arguments passed after the command name.

Why it works

MCP prompts are user-invoked templates. Surfacing them as slash commands keeps them explicit and user-triggered — distinct from tools, which the model calls on its own, and resources, which are attached via @-mention.

Weaker approaches people try — and why they fall short

• Added to the tool registry and invoked automatically by the model.That describes MCP tools, not prompts — prompts are invoked by the user, not auto-called by the model.
• Auto-prepended to every conversation as system context.Prompts aren't silently injected into every conversation.
• Surfaced as @-mentionable resources attached when referenced.That describes MCP resources, not prompts.

Situation

An MCP tool for analyzing code dependencies exists and works fine, but the agent keeps using a general search tool instead for 'code dependencies' questions — because the MCP tool's description is terse while the search tool's description is detailed.

Recommended approach

Expand the MCP tool's description to spell out its capabilities and outputs in detail.

Why it works

The model chooses tools largely from their descriptions. A detailed competing description makes that tool look more capable than a vague one. Rewriting the description to state exactly what it returns (direct imports, transitive dependencies, cycles) makes it the obviously better match — fix the description, fix the selection.

Weaker approaches people try — and why they fall short

• Split the dependency-analysis tool into three more granular tools.Adds more surface area and new overlap without addressing the underlying vague description.
• Add routing instructions in the system prompt to send dependency questions to the MCP tool.System-prompt routing is a brittle patch layered on top of the real cause.
• Remove the general search tool whenever the MCP server is connected.Cripples a generally useful tool just to mask a description problem.

Situation

A support agent receives uniform errors from its tools — just 'isError: true, Operation failed' — so it can't tell a temporary glitch from a validation problem from a permissions issue, leading to over-retrying, escalating too soon, or asking the wrong clarifying question.

Recommended approach

Enhance error responses with structured metadata: an error category (transient, validation, or permission), a retryable boolean flag, and a short cause description.

Why it works

The agent behaves inconsistently because the errors are opaque. Structured metadata gives the agent exactly what it needs to choose the right action — retry transient errors, don't retry validation or permission errors, and escalate appropriately. Fixing the information fixes the behavior.

Weaker approaches people try — and why they fall short

• Add a separate error-analysis tool the agent calls after any failure.An extra round-trip to derive information the failing tool could simply return directly.
• Add few-shot examples showing how to interpret error message patterns.Parsing free-text error patterns is brittle and still guesses at categories the tool already knows internally.
• Retry every error with exponential backoff at the server level.Wastes time retrying permanent errors, like a non-existent order, that will never succeed no matter how many times they're retried.

Situation

As a tool set grew from 4 tools to 10, tool-selection accuracy dropped noticeably. The errors cluster around semantically overlapping tools — one tool for issuing a credit and a separate one for processing a refund, and a delivery-status tool that duplicates data another lookup tool already returns.

Recommended approach

Merge the overlapping tools: combine the credit and refund tools into one tool with an action parameter, and fold the delivery-status tool into the existing lookup tool behind an include-tracking flag.

Why it works

Merging semantically overlapping tools into one tool with a parameter (and folding a redundant tool into an existing one) removes the ambiguous choice entirely — there's no longer a 'wrong' overlapping tool to pick, because there's only one right tool for the job. Removing the fork beats teaching the agent to navigate it.

Weaker approaches people try — and why they fall short

• Split the tools across two sub-agents with a coordinator.Relocates the ambiguity behind a coordinator without removing the overlapping tool definitions themselves.
• Enable deferred/lazy loading for the newer tools.Manages how many tools are visible at once, but the overlapping semantics remain once they're loaded.
• Add few-shot examples for each ambiguous tool pair.Helps the agent choose more often, but doesn't structurally eliminate the overlap itself.

Situation

A refund tool returns both transient technical errors (like a timeout, about 5% of calls) and permanent business errors (like 'exceeds the 30-day window', about 12% of calls) — both as plain text, so the agent wastes several turns retrying the permanent business errors that will never succeed.

Recommended approach

Return structured errors with an explicit is_retryable:false flag for business errors, plus a customer-friendly explanation the agent can use directly in its reply.

Why it works

This solves two problems at once: the explicit retryable flag stops the agent wasting turns on permanent business errors, and the customer-friendly explanation improves what the customer actually sees — marking retryability explicitly rather than making the model guess at it.

Weaker approaches people try — and why they fall short

• Auto-retry technical errors at the tool level, and pass business errors through untouched.Helps reliability for the technical errors, but leaves the customer-facing message quality completely unaddressed.
• Add a mandatory eligibility-check tool that must run before the refund tool.Adds an extra round-trip, and still needs structured results itself to actually be useful.
• Add few-shot examples teaching the model to distinguish retryable from non-retryable errors by parsing the text.Parsing error text is brittle, and doesn't improve the customer-facing explanation either.

Situation

For a request like 'refund for my recent purchase,' the agent calls the refund tool immediately with a fabricated order ID instead of first looking the order up — and the refund fails on the fake ID.

Recommended approach

Update the refund tool's description to state explicitly that its order ID parameter must come from a prior lookup call, and must never be assumed or invented.

Why it works

The root cause is that the tool's description never told the model where that ID actually has to come from, so it invented one. Stating the dependency directly in the description instructs the model to call the lookup tool first — fixing the tool's contract fixes the behavior at its source.

Weaker approaches people try — and why they fall short

• Pre-parse incoming messages for order IDs and inject any found into context.Only helps when an ID happens to be present in the message — here there isn't one to extract.
• Switch tool_choice from 'auto' to 'any' so some tool call is always forced.Just forces some tool call — it wouldn't stop the model from fabricating the parameter itself.
• Add server-side validation that the order ID exists, returning an error if it doesn't.Catches the bad ID after the fact, but doesn't stop the agent from fabricating and failing repeatedly.

Situation

An order-lookup tool catches every exception and returns the same flat message: 'Tool execution failed.' The agent either retries identically until it hits the turn limit, or escalates immediately — neither of which fits every situation.

Recommended approach

Return error-type-specific messages, such as 'Order not found — try looking up by customer or searching by phone' versus 'Database query timeout (transient) — retry should succeed.'

Why it works

The documented recommendation is to write instructive error messages that say what went wrong and what to try next. Type-specific messages — a 'not found' error suggesting an alternative path, versus a 'transient timeout' error indicating a retry will likely work — give the model the exact cues needed to choose the right recovery.

Weaker approaches people try — and why they fall short

• Remove the error flag and return the message as normal content instead.Hides the fact that a failure actually occurred, which can confuse how the loop handles it.
• Add a loop step that intercepts errors, classifies them into categories, and appends a recommendation.Works, but isn't what the documentation actually prescribes, and moves judgment out of the message the model directly reads.
• Retry with exponential backoff inside the tool itself, surfacing only the final failure.Handles transient errors fine, but leaves an 'order not found' case with no actionable guidance for the model at all.