# 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.

Web version: https://claw-link.dev/learn/mcp-tool-call-failed

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

1. Confirm the server is connected and the tool appears in the catalog.
2. Confirm the tool name and arguments against the tool schema.
3. Confirm the right account is connected and still authenticated.
4. Confirm provider permissions, scopes, resource ownership, and plan access.
5. Check provider response details and rate limits before retrying.

For server development, the official [MCP debugging guide](https://modelcontextprotocol.io/docs/tools/debugging)
recommends the MCP Inspector, server logs, client logs, and inspection of the
initialization exchange.

## Keep reading