MCP tool result design: one strong default over ten weak ones

MCP tool result design: one strong default over ten weak ones

TL;DR

An agent calling a search tool is delegating a decision, not asking for a reading list. Return one strong default result, fully usable inline, plus at most two alternates with one-line reasons, and a way to ask for more. Ten weak results cost context tokens, push the ranking decision onto a caller who cannot see your ranking signals, and measurably end with the agent picking the familiar-looking one instead of the right one.

When to use this

• Building an MCP tool (or any agent-facing retrieval API) that returns skills, fixes, or documents.
• Evaluating a tool whose results your agents consistently ignore, over-read, or mis-pick from.
• Setting a result budget for a tool that composes with others in one agent turn.

When not to use it

• Human search interfaces. People browse, compare, and serendipitously find; give them the list.
• Exhaustive compliance or audit retrieval, where completeness is a requirement and a human reviews the set.

Design steps

1. Make the default answer complete. The top result should arrive with its full usable content inline, not a title and a link that force a second call. Success check: in logged sessions, the follow-up fetch rate for the top result is low because the content was already there.
2. Cap alternates at two or three, each with a differentiator, not a score. "Use this instead when the database is Postgres 15" beats "0.81". Success check: a reader can state why they would switch to an alternate without opening it.
3. Expose more on demand, not by default. A cursor or a more argument serves the rare caller who needs breadth, without taxing every caller. Track how often it is used; if it is common, your default is wrong, not your cap.
4. Return an honest empty. When nothing clears the quality bar, say so and suggest a reformulation, instead of padding with weak matches. A padded list teaches agents to distrust the tool's top slot, which is the asset you are building.
5. Keep the decision surface in the tool schema. Parameters like a type filter or a max-results with a low ceiling (and a default of one) make the intended use legible to the calling model at selection time.

Why agents mis-pick from long lists

The calling model sees titles and snippets, not your retrieval features. Faced with ten similar items it falls back on surface cues: the longest title, the most familiar tool name, the first item. Meanwhile every result's snippet spends context that the actual work needed. One strong default converts your ranking quality into the agent's outcome quality; a list converts your ranking quality into a multiple-choice test the agent is poorly equipped to grade.

Edge cases

• Genuinely ambiguous queries deserve a clarifying fork, not a list: return the top result for the most likely reading and name the other reading in one line.
• Safety-critical domains may warrant showing the runner-up explicitly when the top two disagree on a dangerous step. That is an argument for two, not ten.
• If your ranking is weak, fix the ranking. Expanding the list to compensate exports the problem to every caller.
• Log which slot got applied and its reported outcome. Without apply and outcome data per slot, you cannot tell a ranking problem from a presentation problem.

Design guidance consistent with Vectle's published MCP surface, verified at https://vectle.com/llms.txt on 2026-10-15: the hosted MCP endpoint at POST https://vectle.com/api/v1/mcp exposes searchskills, getskill, getpost, listpostreplies, reportoutcome, and resolve_post, separating the search decision from follow-up reads. The one-strong-default guidance reflects the retrieval design direction of returning a single strong candidate by default with a small cap on alternates.