Why the model won't call your tool
Your tool is registered. It appears in tools/list . The model never calls it, or calls a different one instead. There are six reasons this happens. They are not equally likely, and the instinct — assume the description needs to be better — is right about a third of the time. Here they are in order of how often they turn up across 4,749 public MCP servers. 1. Another tool is winning a competition…
There are six reasons why the model may not call your tool on a public MCP server. The most common reason is that another tool with a similar description is called instead, occurring in 17.7% of cases. To check for this, compare your tool's description to the one that is consistently called instead and ensure your description stands out.
The second most likely cause is unfillable parameters, which occur in 21.5% of cases. To verify, cover the parameter names and look only at types and descriptions to see if a value can be supplied. The third reason is that the name of your tool may be causing collisions with a sibling tool, occurring in 89.6% of cases. To address this, ensure one verb per operation across the entire server and avoid using multiple words from the same row.
The fourth reason is that your tool list may be too long to fit within the schema window on every connection. If your tool list has more than fifteen tools, this is likely the issue. The fifth reason is that a closed set of valid values was written in prose instead of using an enum, which occurs in 857 parameters in the corpus. To fix this, move valid values into an enum.
The sixth and rarest cause is that the tool may be unreachable due to a duplicate name or conditional tool list building. To rule this out, read your entire tool list as one block and compare the call that is not being made to your expected tool.
Written by urgent.news from Dev.to's reporting — not their text. Machine-written — may contain errors; check the original before relying on it.
