[BUG] Tool search has broken ranking, causing Claude to fail to find a tool despite exact name match
Preflight Checklist
- [x] I have searched existing issues and this hasn't been reported yet
- [x] This is a single bug report (please file separate reports for different bugs)
- [x] I am using the latest version of Claude Code
What's Wrong?
Observation:
- Claude appears to know that a tool is a deferred tool but repeatedly fails to find it. Claude fails to load & apply tools that its search does not return.
- The ranking algorithm for Claude's tool search often ranks tools higher that are not a good match, e.g. search for
find symbolwith Serena MCP's tool set can fail to surface the tool actually namedfind_symbol. Claude never searches for more than 5 matches on its own and therefore does not find & apply the tool without assistance.
This affects Claude Code and Claude Desktop alike.
Look at this:
<img width="737" height="704" alt="Image" src="https://github.com/user-attachments/assets/fb788296-e803-47d0-aa03-df021d2e303e" />
<img width="751" height="763" alt="Image" src="https://github.com/user-attachments/assets/5d7f485c-92d1-4cff-9aaa-5d93f400351e" />
<img width="731" height="652" alt="Image" src="https://github.com/user-attachments/assets/fb8aa395-906e-4a16-8ba7-45532733622b" />
What Should Happen?
The ranking algorithm should be improved to surface exact name matches immediately. Name match should have more weight than description match (which currently appears to prefer longer descriptions over shorter ones and is not focused on an actual semantic match, unfortunately).
Error Messages/Logs
Steps to Reproduce
- Use Claude with an MCP server like Serena, which has a large number of related tools.
- Make Claude apply tool search and observe its failures to find the relevant tools (even though it knows they exist)
Claude Model
Opus
Is this a regression?
No, this never worked
Last Working Version
_No response_
Claude Code Version
2.1.169
Platform
Anthropic API
Operating System
Windows
Terminal/Shell
Other
Additional Information
_No response_
This issue has 3 comments on GitHub. Read the full discussion on GitHub ↗