Troubleshooting Tool Calls
As an AI agent, using tools effectively is a core part of your function. However, you may encounter situations where tool calls fail for non-obvious reasons. This guide provides a framework for troubleshooting these issues.
The Golden Rule: Don't Give Up on First Failure
A failed tool call is not a dead end. It is a valuable piece of information. Your primary goal should be to use the failure as a clue to find the correct way to call the tool.
The Scientific Method for Tool Calls
Treat every tool call as a mini-experiment.
Formulate a Hypothesis: Based on the tool's name, its server, and any known naming conventions, form a hypothesis about the correct function name and parameters.
Run the Experiment: Execute the tool call.
Analyze the Results:
- Success: Your hypothesis was correct.
- Failure: Your hypothesis was incorrect. Analyze the error message carefully. It is your most important clue.
Refine and Repeat: Use the error message and any other available data (e.g., a list of available tools) to formulate a new, more informed hypothesis. Repeat the process.
Common Pitfall: Naming Conventions
A common source of errors is the naming convention for tools, especially in a multi-server environment.
The Disambiguation Prefix
You may have learned a rule for disambiguating tool names that share the same name across different servers, such as prefixing the tool with the server name (e.g., serverName__toolName).
Example: healthcheck is a common tool name. To call it on the github-workflow server, you might use neo_mjs_github_workflow__healthcheck().
The Over-generalization Trap
The most critical mistake is to over-generalize this rule. Do not assume that all tools on a server require a prefix.
Some tools may have names that are unique across all servers. Harnesses can still expose those names differently, so the live tool list—not a remembered prefix rule—is authoritative.
Example:
healthcheck(ambiguous) -> requiresneo_mjs_github_workflow__healthcheck()get_pull_request_diff(unique) -> call the exact name advertised by the current tool surface
If a remembered tool name fails, inspect the current tool surface before retrying; do not synthesize alternate names from stale guidance.
When the error message is the wrong clue: a stale tool schema
The Scientific Method above says the error message is your most important clue. There is one failure where it points the wrong way, and it is worth naming because the wrong conclusion gets published as fact.
Your client caches each server's tool schemas at connect and never revalidates. Every Neo server
declares tools: {listChanged: false}, so no refresh signal will ever arrive. If a capability shipped
after you attached, your client rejects the call before it leaves — and the rejection quotes your own
cached schema as if it were the server's:
MCP error -32602: Invalid arguments for tool manage_wake_subscription: "values": ["bootstrap","subscribe","unsubscribe","update","list","resync"]
Read literally, that says the server does not support the action. It says no such thing. It says your copy does not. Three wrong moves follow: reporting the capability as absent, building a workaround for something that already shipped, or filing a bug against a working server.
Reading your own tool list does not help — it is the same cache.
The comparison
healthcheck carries both halves, and you need no new call beyond the one you were going to make:
| where | what it is |
|---|---|
the healthcheck description you hold |
Advertised-surface digest at attach: <token> — frozen into your cache when you attached |
the healthcheck result |
advertisedSurface.digest — computed by the server on this call |
| tokens | verdict | what to do |
|---|---|---|
| equal | current |
Your schema matches what this server advertises. An absence really is an absence. |
| different | stale |
Reconnect before asserting anything about capability. Do not report a capability as missing. |
| either absent | unknown |
The comparison did not happen. Never read this as current — a server predating the instrument looks exactly like this, and so does a page that did not contain healthcheck. |
Equality claims one thing only: this attachment was provisioned from the same advertised-surface generation the server serves now. It says nothing about host-side truncation or paging, which no server-side value can see.
The digest covers tool names and input schemas for the projection you were served. Descriptions are excluded, so a reworded description does not move it — the axis is whether a capability is reachable, not whether its prose is current.
The rule this exists to enforce: an absence-claim about a capability requires a current verdict.
Without one, the honest statement is "my schema may predate it", not "it does not exist".
Conclusion
Flexibility and a systematic, evidence-based approach are key. Do not rigidly adhere to a rule that has been proven false by an experiment. Use every success and failure to build a more accurate mental model of the tool environment.