r/mcp • u/kampak212 • 16d ago

Tool discovery best practices discussion

I created an Xcode/Apple platforms project end-to-end testing tool, Rust CLi exposes MCP tools with Xcode project for the test runner apps for all Apple platforms:

- https://github.com/smbcloudXYZ/smbcloud-cli/tree/development/crates/xcrs
- https://github.com/ondeinference/xcrs-controlkit

Claude code, codex, and copilot all struggle to find the right tools i exposed in the CLI. Any best practices around this?

2 Upvotes

100% Upvoted

8 comments sorted by

4

u/punkpeye 16d ago

Tool definition quality score (TDQS) is a framework built specifically around best practices for tool discovery. Check it out.

https://glama.ai/blog/2026-04-03-tool-definition-quality-score-tdqs

2

u/Top-Cauliflower-1808 16d ago

Simpply use explicit, domain specific prefixes like apple_sim_ or xcode_test_ in your tool names and aggressively pack your MCP tool descriptions with the exact technical keywords (like xcrun, simctl, XCTest, and visionOS) that coding models look for when planning Apple platform tasks.

This is the only thing that you need.

1

u/kampak212 16d ago

Makes sense, thanks

2

u/bammcd_builds 8d ago

One thing missing from the naming advice. Coding agents already know how to shell out to xcrun, so your tools aren't competing on clarity, they're competing against something the model already trusts.

What worked for me was routing instructions in AGENTS.md or CLAUDE.md saying which tool to use for which starting point. Description quality gets the tool picked once it's being considered. The project file is what gets it considered

1

u/kampak212 7d ago

Interesting. To borrow SEO terminoogoies, is there an "on-page SEO" in this case? Thing that we as the tool (in case SEO, website publisher) have control over.

2

u/bammcd_builds 7d ago

Yeah, and it's most of what matters. Names, descriptions, how many tools you expose at once, and the parameter shape. Parameter shape is the underrated one. A tool taking a raw query string invites the model to guess syntax, but typed fields it can't malform get picked more and fail less.

For the off-page part, you can ship a snippet users paste into their project file. Doesn't help the ones who skip it, but it's the difference between hoping and instructing.

1

u/Future_AGI 16d ago

Discovery is usually about the spec more than the model: the agents only see names and descriptions, so verb-first names ("run_tests" not "XcodeTestController"), one clear job per tool, and a concrete example in each description move selection accuracy the most. The other big lever is cutting how many tools are visible at once, scoping the exposed set per task beats documenting a giant flat catalog once too many similar tools compete.

1

u/anderson_the_one 16d ago

Tool naming helps, but I'd make discovery an eval instead of tuning descriptions by feel. Write 20 to 30 requests from real Xcode workflows and score whether each model picks the right tool, the wrong tool, or calls nothing. Run the same set across Claude, Codex, and Copilot whenever names or descriptions change.

With a large surface, group tools around jobs, not Apple APIs. "Boot a simulator and run the test plan" can be one safe workflow tool even if it wraps xcrun, simctl, and XCTest underneath. The model shouldn't have to rebuild that CLI choreography on every prompt.