MCP tool call failed: causes and fixes
How to diagnose an MCP tool call that fails: tool discovery, invalid arguments, connection state, permissions, rate limits, provider errors, and re-authentication.
An MCP tool call can fail before it reaches the provider, while the provider is processing it, or after a credential has gone stale. Start by locating the failure layer. A missing tool name needs a different fix from an expired login or a provider rate limit.
1. The tool is not available
The client must discover a server's tools before it can invoke one. Confirm that the MCP server connected successfully and supports tools, then refresh the agent's tool catalog or start a fresh session. Use the exact name returned by the server rather than guessing one.
2. The arguments are invalid
An input can have the wrong type, omit a required field, or contain a placeholder instead of a real identifier. Ask the agent to list or search for the target resource first, then call the tool with the returned ID. For a protocol-level invalid-parameters error, inspect the server's input schema and the supplied JSON.
3. The account is not connected or needs re-authentication
OAuth access can be revoked, a provider can require a new login, or the agent can select the wrong connected account. Reconnect the app, then retry a read-only call before repeating a write action.
4. The account lacks a permission
The tool may exist while the connected account lacks a required scope, workspace role, plan feature, or ownership of the target resource. Test the same action in the provider UI with the same account. If it fails there, the MCP client cannot grant that access.
5. The provider limited or rejected the request
Rate limits, missing resources, and provider outages occur after a valid tool call reaches the upstream app. Respect the provider retry window. Before retrying a write, determine whether the first request may already have succeeded.
What ClawLink production logs show
In a 90-day aggregate of measured ClawLink calls, the most common actionable logged failure classes were tool not found (1,864), rate limit (1,369), no connection (735), resource not found (560), missing scopes (491), provider unavailable (450), and re-authentication required (327). The counts are not a universal MCP failure rate. They show why a diagnostic path needs more than one generic “retry” instruction.
A short debugging order
- Confirm the server is connected and the tool appears in the catalog.
- Confirm the tool name and arguments against the tool schema.
- Confirm the right account is connected and still authenticated.
- Confirm provider permissions, scopes, resource ownership, and plan access.
- Check provider response details and rate limits before retrying.
For server development, the official MCP debugging guide recommends the MCP Inspector, server logs, client logs, and inspection of the initialization exchange.