Unknown MCP Tool: Refresh Discovery Before You Change Code
Unknown MCP tool means tools/call reached a server that does not currently advertise the exact requested tool name.
Table of contents
- What unknown tool means
- Unknown tool vs method not found
- Refresh the source of truth
- Why tool lists go stale
- Server-side registration checks
- Verification
- FAQ
What unknown tool means
The tools/call method exists, but the requested application-level tool name is absent from the server’s current registry. The client reached an MCP server, selected the tools operation, and supplied a name that does not match the server’s advertised tools.
This usually indicates a discovery or naming problem, not a transport failure. Record the exact request and response, including the server profile, connection target, requested name, and timestamps. The MCP tools specification defines the relationship between tool listing and tool calls.
Check spelling and casing character by character. Treat read_file, read-file, and ReadFile as different names until the active registry proves otherwise. Once the name is corrected, compare the arguments with the advertised input schema. A valid name with invalid arguments is a separate issue.
Unknown tool vs method not found
Unknown tool is a tools/call parameter problem; -32601 means the protocol method itself is unavailable. Although clients may display similar messages, the errors identify different layers.
An unknown-tool response means the server understood the operation but could not resolve the requested application-level name. JSON-RPC error code -32601 means the requested method is not available at the protocol endpoint. The JSON-RPC 2.0 specification defines this method-level distinction.
Use the response structure to locate the fault:
| Evidence | Likely layer | First check |
|---|---|---|
tools/call reaches the server but the name is unknown | Tool discovery or naming | tools/list on the same connection |
-32601 for the requested method | Protocol method availability | Method support and lifecycle state |
| Tool name is listed, but arguments fail | Input validation | Advertised input schema |
| Different tools appear across clients | Profile, permissions, or server selection | Active connection and configuration |
Do not fix a method problem by changing a tool name, and do not treat an unknown tool as proof that the entire server is offline. The MCP lifecycle specification helps determine whether initialization completed correctly.
Refresh the source of truth
Use tools/list on the same connection and profile, then copy the exact advertised name and schema. The active response—not an old screenshot, cached client panel, README example, or remembered configuration—is the source of truth.
First identify which server instance handled the failed request. Confirm the endpoint, transport, environment or profile, and account context. If the client connects to multiple servers, ensure discovery targets the same server that returned the error.
Compare the current tool list with the failed request:
- Requested name, including spelling and case.
- Tool description, if shown.
- Input schema and required properties.
- Visible permissions or availability indicators.
- Connection and profile associated with the response.
If the intended tool is absent, reconnect the client and repeat discovery. Reconnection clears stale client state but does not change server registration. Capture the new list and compare it with the previous response instead of assuming the catalog is repaired.
The official MCP debugging guide supports this evidence-led workflow: inspect the request, inspect the response, and isolate the failing layer. Preserve the original failure so a later successful call does not erase useful evidence.
Why tool lists go stale
Renames, feature flags, permissions, reconnect failures, and multiple servers can leave a client with an obsolete catalog. A client may display a previously discovered name even though the active server now exposes a different registry.
A rename is the simplest case: the client calls the former name while the server advertises its replacement. Feature flags and environment-dependent registration can make a tool available in one profile but absent in another. Permissions may also restrict the registry for a particular connection.
Reconnect failures create a subtler mismatch. The user may believe discovery was refreshed even though the interface retained its previous catalog or never completed fresh initialization. Multiple servers create a similar problem when the visible list belongs to one server but the failed call is routed to another.
Use the MCP Inspector repository for an independent view of server behavior. The goal is to compare the client’s belief with what the active server actually advertises.
Keep one variable fixed at a time. Refresh the connection first, then recheck the list. Change the requested name only after the registry confirms it. Do not weaken authentication, certificate checks, or authorization to conceal an unknown-tool error.
Server-side registration checks
Verify that the tool registered before startup completed and that environment settings or filters did not remove it. If the exact name is absent from a fresh tools/list response, changing call arguments cannot restore it.
Review startup evidence for the selected profile. Confirm that the intended tool module or handler loaded, registration completed, and no configuration condition excluded it. A healthy process does not prove that every expected tool registered.
Then inspect filters and permissions. A server may expose a reduced registry when a feature flag is disabled, an account lacks access, or a deployment profile selects a narrower tool set. Compare working and failing profiles only when the connection and inputs remain clear.
If the server uses an SDK, verify that its declared name matches the name returned by discovery. The C# SDK tools guidance provides one example of how registration and metadata are represented; apply the same principle to the implementation in use.
A useful boundary is: server logs establish what registered, tools/list establishes what was advertised, and tools/call establishes whether the advertised name can be invoked. When those records disagree, preserve all three and resolve the earliest mismatch.
Verification
Test a known tool, the repaired tool, and an intentionally wrong name. This three-part check separates connection health, repair success, and expected rejection behavior.
Use a known, low-impact tool first. Choose an operation that does not modify data or credentials, and record its result and request identifier. This confirms that the selected connection can discover and call an existing tool.
Next, call the repaired tool with the smallest valid input described by its current schema. Confirm that the name is accepted and that any remaining failure concerns execution or validation rather than discovery. Preserve the response for review.
Finally, use an intentionally incorrect name in a controlled diagnostic request. It should reproduce the expected unknown-tool behavior without changing server state. This negative test confirms that the client and server distinguish a missing application-level name from a general connection failure.
For repeatable checks, document the connection, profile, discovery response, exact name, schema, and result of each test. MCPtrove can support the next step: review the MCP tool glossary, inspect available capabilities, and use the config validator to catch configuration mismatches. For a broader sequence, see how to test an MCP server.
The practical rule is simple: preserve evidence, change one layer at a time, and do not weaken security to hide an error. An unknown tool is easier to fix when the original request, fresh registry, and post-reconnect comparison remain visible.