Summary
MCP tool definitions (McpToolDefinitions.cs:21-458) describe each tool with a one- to two-sentence purpose and a JSON inputSchema, but never include an example call or example response. An agent reading the tool list has to infer correct argument shapes from the schema alone — fine for trivial tools, costly for impact_analysis / batch_query / find_in_file where the right argument combinations are non-obvious. Concrete examples cut the agent's exploration cost dramatically.
Where
src/CodeIndex/Mcp/McpToolDefinitions.cs:21-458 (tool definitions)
Suggested approach
(1) Extend each tool definition with an examples array under the description (or a sibling x-examples field if the MCP spec disallows custom fields on the standard description) containing 1-3 minimal {request, response_excerpt} pairs that demonstrate the canonical use. (2) For tools with multiple input modes (e.g. search with --lang vs. --kind vs. raw query), include one example per mode. (3) Sync the examples with CLI --help output where applicable so docs cannot drift. (4) Add a regression test that asserts each example, when fed back through the tool handler, produces a response of the documented shape. (5) Surface examples in the tools/list MCP response so MCP clients (Claude Code, Codex, etc.) get them automatically. (6) Cross-link with #1582 (did-you-mean) and #1772 (kind taxonomy) — both reduce the same "agent guesses wrong" failure mode.
Summary
MCP tool definitions (McpToolDefinitions.cs:21-458) describe each tool with a one- to two-sentence purpose and a JSON
inputSchema, but never include an example call or example response. An agent reading the tool list has to infer correct argument shapes from the schema alone — fine for trivial tools, costly forimpact_analysis/batch_query/find_in_filewhere the right argument combinations are non-obvious. Concrete examples cut the agent's exploration cost dramatically.Where
src/CodeIndex/Mcp/McpToolDefinitions.cs:21-458(tool definitions)Suggested approach
(1) Extend each tool definition with an
examplesarray under the description (or a siblingx-examplesfield if the MCP spec disallows custom fields on the standard description) containing 1-3 minimal{request, response_excerpt}pairs that demonstrate the canonical use. (2) For tools with multiple input modes (e.g.searchwith--langvs.--kindvs. raw query), include one example per mode. (3) Sync the examples with CLI--helpoutput where applicable so docs cannot drift. (4) Add a regression test that asserts each example, when fed back through the tool handler, produces a response of the documented shape. (5) Surface examples in thetools/listMCP response so MCP clients (Claude Code, Codex, etc.) get them automatically. (6) Cross-link with #1582 (did-you-mean) and #1772 (kind taxonomy) — both reduce the same "agent guesses wrong" failure mode.