Enrich optimizer tool descriptions for better LLM usage

[aponcedeleonch]

Summary

• Enriched find_tool and call_tool MCP tool descriptions with detailed usage guidance, examples, and return value documentation
• Improved FindToolInput and CallToolInput struct field description tags with examples and clarifications

Motivation

LLMs rely heavily on tool descriptions to decide when and how to invoke tools. The previous descriptions were minimal (e.g. "Call a tool by name with the given parameters"), which did not provide enough context for LLMs to use them effectively. This led to poor tool discovery and incorrect invocations in practice.

The Python mcp-optimizer reference implementation (server.py) already had rich, detailed descriptions that guided LLMs through the correct workflow (discover tools first, then call them). This PR aligns the Go optimizer tool descriptions with that reference, adapted for the vMCP context.

Changes

pkg/vmcp/server/adapter/optimizer_adapter.go — Tool-level descriptions:

• find_tool: Now explains when to use it (discover tools, find the right tool before solving a problem), what it returns (tools with schemas + token metrics), includes an example query, and instructs the LLM to always call this before call_tool
• call_tool: Now explains use cases, instructs to always use find_tool first, and describes the result structure

pkg/vmcp/optimizer/optimizer.go — Input schema field descriptions:

• tool_description: Now includes examples like "web search", "analyze CSV file" and explains semantic matching
• tool_keywords: Now explains BM25 text search with examples like ['list', 'issues', 'github']
• tool_name: Now clarifies to obtain from find_tool results
• parameters: Now clarifies structure must match the tool's input schema from find_tool

Test plan

• go build ./pkg/vmcp/... compiles successfully
• task lint-fix passes with 0 issues
• Verify optimizer tools are usable by LLMs with the new descriptions

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 68.58%. Comparing base (edafa62) to head (d9d4106).
⚠️ Report is 6 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #4031      +/-   ##
==========================================
- Coverage   68.61%   68.58%   -0.04%     
==========================================
  Files         444      444              
  Lines       45187    45242      +55     
==========================================
+ Hits        31007    31027      +20     
- Misses      11780    11816      +36     
+ Partials     2400     2399       -1     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.