Implementing Resilient AI-Agent Tooling: Handling MCP Tool Errors

When building AI-powered workflows using the Model Context Protocol (MCP), your assistant is only as reliable as the tools it calls. Whether you are performing a single-number check or processing a batch of 100 identifiers, real-world constraints like concurrency limits or network timeouts are inevitable.

Rather than letting your AI agent fail silently or hallucinate a result when a tool call encounters an issue, you must implement a robust error-handling contract. This guide walks through how to interpret MCP tool errors to ensure your AI assistant remains helpful and transparent.

Understanding the MCP Error Contract

The MCP server for WA Lookup communicates failures using a standardized structure. When a tool call fails, the response includes isError: true. This is a critical signal for your AI client to stop attempting to parse result data and instead pivot to explaining the situation to the user.

Common Failure Scenarios

• Concurrency Limits (42901): This occurs if your account has reached its limit of concurrent in-flight requests. Since the API is synchronous, this is a temporary state. Your AI agent should inform the user that the system is busy and suggest a brief pause.
• Timeouts (50400): If a batch request takes too long, the operation fails as a whole. Crucially, these failed or undetermined checks are automatically refunded, so your agent can safely inform the user that no balance was consumed for the failed attempt.
• Invalid Inputs (40002): If a user provides a number not in E.164 format, the tool returns a validation error. Your agent should use this feedback to prompt the user to correct the number format.

Implementation Pattern: Graceful Recovery

When integrating these tools into an AI agent, use a wrapper to inspect the response envelope. Do not assume a successful JSON-RPC response implies a successful data retrieval.

Conceptual Error Handling Logic

// Conceptual: Parsing an MCP tool response
async function executeTool(toolName, params) {
 const response = await mcpClient.callTool(toolName, params);

 if (response.isError) {
 // Extract the code and message to provide context to the LLM
 const { code, msg } = response;
 return `Error ${code}: ${msg}. Please try again or check your input.`;
 }

 return response.result;
}

Best Practices for AI-Agent Tooling

1. Map Codes to User-Friendly Language: Instead of passing raw error codes like 50303 to the user, instruct your system prompt to map these to human-readable explanations (e.g., "The service is currently at capacity, please try again in a few moments.").
2. Handle Batch Partiality: When using check_numbers, remember that each number is evaluated independently. Even if the overall request succeeds, your logic should account for individual results within the batch.
3. Leverage Refund Semantics: Since failed or undetermined checks are refunded, ensure your agent communicates this to the user to maintain trust. If a batch fails due to a 50400 timeout, the user hasn't lost their balance, which is a vital piece of context for the conversation.

Conclusion

By treating tool errors as first-class citizens in your AI architecture, you transform potential points of failure into opportunities for better user experience. Always check for the isError flag before processing data, and use the provided error codes to guide your agent's recovery strategy. For a full list of status codes and tool definitions, refer to the official documentation.

This article was drafted with AI assistance and reviewed before publishing.