Many agent failures are not failures of language understanding. They are failures of tool selection and error handling. A model chooses a plausible capability whose contract is ambiguous, an MCP server returns an unstructured exception, or the application interprets a retryable outage as permission to try another tool with broader access.<\/p>\n
Such systems may appear flexible until one unclear tool request causes an unintended change. For Claude integrations, tool discovery, selection, validation, execution, and failure reporting should be independent and inspectable parts of the workflow.<\/p>\n
Model Context Protocol standardizes connections to external capabilities, but standardization does not decide which operations an agent should be allowed to use. An application still controls visible tools, scope and user authority. A safe MCP tool contract<\/a> separates discoverability from permission and represents denied or failed calls explicitly. The following selection patterns keep ambiguity from turning a tool failure into an unauthorized new action.<\/p>\n A tool name and description are not cosmetic metadata. They help the model decide whether a capability is relevant to the task. If five tools all claim to \u201csearch customer data,\u201d the agent has little information for choosing correctly. Describe the data source, allowed operation, expected output, constraints, and conditions under which each tool is inappropriate. Prefer a narrow Group tools by trust boundary. A read-only order lookup may be broadly available; a refund tool should have stronger identity, monetary, and approval constraints. Tools for searching an internal knowledge base should not accept arbitrary requests to export the entire repository. Curate the visible catalog for each workflow instead of presenting every company integration to every model session.<\/p>\n Discovery and authorization are separate. An MCP server can advertise a tool without granting the caller permission to invoke it. The target service must verify permissions each time, because catalog visibility can change, user roles can expire, and requests can be replayed. A model’s decision to call a tool is an instruction to the client runtime to consider a request, not proof that it is safe.<\/p>\n Consider two ticketing tools: one searches historical tickets and another creates a new escalation. Both might seem relevant to \u201cfind the customer issue.\u201d A precise description explains that the search tool is for diagnosis and returns existing records, while escalation requires a validated issue summary and approval. This helps Claude propose a read-only action first and keeps the application able to reject an inappropriate write.<\/p>\n Descriptions should state important exclusions. If a tool only reads sanitized records from one business unit, say so. If an action cannot be undone or can contact a customer externally, declare that behavior. Tool names should not conceal irreversible side effects behind vague verbs such as \u201cresolve.\u201d Examples in a description can clarify parameter expectations, but avoid packing entire policy manuals into every tool definition. Too many repetitive details can increase context cost and reduce clarity.<\/p>\n After modifying a tool catalog, run tests where the correct response is to choose no tool, request clarification, or report that a capability is unavailable. Selection accuracy cannot be measured only by whether the model picked a valid tool name. It matters whether the selected capability is justified by user intent and policy.<\/p>\n The Claude tool-use interface<\/a> lets applications offer or direct tool calls, but it does not override the application’s allowlist or the user’s permissions. Exposing a tool is a policy decision; model selection merely proposes an action. The application must authorize and validate every request before execution.<\/p>\n Prefer selection constraints that follow the stage of work. During evidence gathering, expose only read operations. When a change has been proposed and reviewed, the application can make a specific mutation capability available to a narrowly authorized execution step. Avoid a single session in which the model has both unrestricted browsing and privileged write access by default. That architecture makes prompt injection far more dangerous because untrusted source text can influence side-effecting actions.<\/p>\n When a task can be answered without a tool call, allowing the model to abstain can reduce cost and unnecessary data access. When the user requests a real external fact, the application should require suitable evidence rather than accept a confident response from memory. The distinction is task-specific, so evaluate both false tool use and failures to use a needed tool.<\/p>\n A tool can fail because its input is invalid, the requested resource is absent, the caller lacks permission, an upstream service is unavailable, or a deadline was exceeded. Returning only \u201cSomething went wrong, try again\u201d hides the action needed to recover. A structured response should identify an error category, provide safe diagnostic context, indicate whether retrying is appropriate, and distinguish unknown outcome from confirmed failure. For MCP integrations, error signaling must match the current specification, including the relevant tool-result error indicator.<\/p>\n For instance, a lookup might report Never expose raw stack traces, secrets, connection strings, or entire database rows in tool errors merely because the model might find them informative. Log sensitive diagnostic detail under approved application controls, then return only what the agent needs to decide safely. A useful model-facing error might say that a lookup failed because the service was temporarily unavailable and that no account update was attempted. It should not reveal implementation secrets.<\/p>\n A failed MCP tool execution<\/em> may be returned inside a tool result with A business rejection such as Both should cause the coordinator to stop or request legitimate approval rather than repeatedly trying broader tools. Log the operation identifier, authorization scope and retryability without exposing secrets, and recheck target-state before replaying a mutating request.<\/p>\n A malformed protocol message or unavailable MCP connection is different from a valid tool invocation that was rejected by business policy. The latter should be reported as a normal application outcome with an explicit denial reason. Treating every denied action as a transport failure may cause the agent runtime to retry, potentially invoking the same prohibited operation repeatedly. Conversely, hiding a true tool failure as a successful empty result may make Claude conclude that no data exists.<\/p>\n Record whether the tool request was never sent, reached the application and was rejected, completed successfully, or reached an unknown result state. This distinction is essential for writes. If a billing operation timed out after a downstream service received it, the correct next step is to check the existing operation ID, not construct a second request with new arguments. Use idempotency keys and durable transaction state rather than hoping the model remembers what it already tried.<\/p>\n Structured failures support better review. A human should be able to see which condition blocked an action without reading a large model transcript. They should also be able to revoke a pending authorization. The system’s credibility comes from being able to say exactly what was and was not done.<\/p>\n Retrying a transient network timeout may be appropriate for a read-only lookup, but use exponential backoff or another bounded policy and stop after a reasonable limit. Validation errors usually need corrected input, not automated repetition. Permission errors need authorization or a different approved route. Ambiguous tool discovery should trigger a clearer request or a deterministic routing rule, not simultaneous calls to all plausible tools.<\/p>\n An agent should never use error recovery as a reason to expand its tool permissions automatically. If an approved read API is unavailable, a privileged database-export tool should not become the fallback without a separate policy decision. If the correct service is unavailable, report the limitation and preserve the task state. Recovery procedures should be part of the task contract, with a maximum step budget and a clear escalation point.<\/p>\nBegin with an accurate inventory of callable capabilities<\/h2>\n
get_order_status<\/code> to a generic customer_ops<\/code> tool with loosely interpreted text arguments.<\/p>\nUse descriptions to disambiguate similar tools<\/h2>\n
Keep tool-choice controls subordinate to application policy<\/h2>\n
Design errors as stable outcomes, not reassuring prose<\/h2>\n
NOT_FOUND<\/code> when an account ID does not exist, FORBIDDEN<\/code> when access is denied, or RETRYABLE_UPSTREAM<\/code> when a temporary dependency is unavailable. These are illustrative application-level categories, not universal MCP protocol constants. Each should have a documented behavior: ask for a corrected identifier, deny and escalate, or retry with limits. Do not encourage the model to seek a different privileged integration after a permission denial.<\/p>\nSeparate protocol errors from business rejections<\/h2>\n
isError: true<\/code>. For example, an internal lookup could return {\"content\":[{\"type\":\"text\",\"text\":\"temporarily_unavailable\"}],\"isError\":true}<\/code> instead of an apparently successful empty result. That differs from a JSON-RPC protocol error for a malformed request or an unknown tool. The MCP tool specification<\/a> distinguishes these outcomes; an outage must not become fabricated evidence that no account exists.<\/p>\nstatus: denied<\/code> can also be a deliberately handled domain outcome: valid transport does not grant permission to modify data. Declare whether that condition is a successful tool result containing a denial status or a tool-level execution error, and keep the implementation consistent.<\/p>\nUse failure categories to drive bounded recovery<\/h2>\n