Enrich optimizer tool descriptions for better LLM usage

pkg/vmcp/optimizer/optimizer.go

@@ -104,10 +104,12 @@ type Optimizer interface {
 // FindToolInput contains the parameters for finding tools.
 type FindToolInput struct {
 	// ToolDescription is a natural language description of the tool to find.
-	ToolDescription string `json:"tool_description" description:"Natural language description of the tool to find"`
+	//nolint:lll // Long description tag provides essential context for LLM tool usage.
+	ToolDescription string `json:"tool_description" description:"Description of the task or capability needed (e.g. 'web search', 'analyze CSV file', 'send an email'). This is used for semantic similarity matching against available tools."`
 
 	// ToolKeywords is an optional list of keywords to narrow the search.
-	ToolKeywords []string `json:"tool_keywords,omitempty" description:"Optional keywords to narrow search"`
+	//nolint:lll // Long description tag provides essential context for LLM tool usage.
+	ToolKeywords []string `json:"tool_keywords,omitempty" description:"Optional keywords for BM25 text search to narrow results (e.g. ['list', 'issues', 'github'] or ['SQL', 'query', 'postgres']). Combined with tool_description for hybrid search."`
 }
 
 // FindToolOutput contains the results of a tool search.
@@ -127,10 +129,12 @@ type TokenMetrics = tokencounter.TokenMetrics
 // CallToolInput contains the parameters for calling a tool.
 type CallToolInput struct {
 	// ToolName is the name of the tool to invoke.
-	ToolName string `json:"tool_name" description:"Name of the tool to call"`
+	//nolint:lll // Long description tag provides essential context for LLM tool usage.
+	ToolName string `json:"tool_name" description:"The name of the tool to execute (obtain this from find_tool results - it is the tool's name field)"`
 
 	// Parameters are the arguments to pass to the tool.
-	Parameters map[string]any `json:"parameters" description:"Parameters to pass to the tool"`
+	//nolint:lll // Long description tag provides essential context for LLM tool usage.
+	Parameters map[string]any `json:"parameters" description:"Dictionary of arguments required by the tool. The structure must match the tool's input schema as returned by find_tool."`
 }
 
 // NewOptimizerFactory creates the embedding client and SQLite tool store from

pkg/vmcp/schema/reflect_test.go

@@ -20,12 +20,12 @@ func TestGenerateSchema_FindToolInput(t *testing.T) {
 		"properties": map[string]any{
 			"tool_description": map[string]any{
 				"type":        "string",
-				"description": "Natural language description of the tool to find",
+				"description": "Description of the task or capability needed (e.g. 'web search', 'analyze CSV file', 'send an email'). This is used for semantic similarity matching against available tools.",
 			},
 			"tool_keywords": map[string]any{
 				"type":        "array",
 				"items":       map[string]any{"type": "string"},
-				"description": "Optional keywords to narrow search",
+				"description": "Optional keywords for BM25 text search to narrow results (e.g. ['list', 'issues', 'github'] or ['SQL', 'query', 'postgres']). Combined with tool_description for hybrid search.",
 			},
 		},
 		"required": []string{"tool_description"},
@@ -45,11 +45,11 @@ func TestGenerateSchema_CallToolInput(t *testing.T) {
 		"properties": map[string]any{
 			"tool_name": map[string]any{
 				"type":        "string",
-				"description": "Name of the tool to call",
+				"description": "The name of the tool to execute (obtain this from find_tool results - it is the tool's name field)",
 			},
 			"parameters": map[string]any{
 				"type":        "object",
-				"description": "Parameters to pass to the tool",
+				"description": "Dictionary of arguments required by the tool. The structure must match the tool's input schema as returned by find_tool.",
 			},
 		},
 		"required": []string{"tool_name", "parameters"},

pkg/vmcp/server/adapter/optimizer_adapter.go

@@ -35,16 +35,36 @@ func CreateOptimizerTools(opt optimizer.Optimizer) []server.ServerTool {
 	return []server.ServerTool{
 		{
 			Tool: mcp.Tool{
-				Name:           FindToolName,
-				Description:    "Search for tools by description. Returns matching tools ranked by relevance.",
+				Name: FindToolName,
+				Description: "Find and return tools that can help accomplish the user's request. " +
+					"This searches available MCP server tools using semantic and keyword-based matching. " +
+					"Use this function when you need to: " +
+					"(1) discover what tools are available for a specific task, " +
+					"(2) find the right tool(s) before attempting to solve a problem, " +
+					"(3) check if required functionality exists in the current environment. " +
+					"Returns matching tools ranked by relevance including their names, descriptions, " +
+					"required parameters and schemas, plus token efficiency metrics showing " +
+					"baseline_tokens, returned_tokens, and savings_percent. " +
+					"Example: for 'Find good restaurants in San Jose', call with " +
+					"tool_description='search the web' and tool_keywords='web search restaurants'. " +
+					"Always call this before call_tool to discover the correct tool name and parameter schema.",
 				RawInputSchema: findToolInputSchema,
 			},
 			Handler: createFindToolHandler(opt),
 		},
 		{
 			Tool: mcp.Tool{
-				Name:           CallToolName,
-				Description:    "Call a tool by name with the given parameters.",
+				Name: CallToolName,
+				Description: "Execute a specific tool with the provided parameters. " +
+					"Use this function to: " +
+					"(1) run a tool after identifying it with find_tool, " +
+					"(2) execute operations that require specific MCP server functionality, " +
+					"(3) perform actions that go beyond your built-in capabilities. " +
+					"Important: always use find_tool first to get the correct tool_name " +
+					"and parameter schema before calling this function. " +
+					"The parameters must match the tool's input schema as returned by find_tool. " +
+					"Returns the tool's execution result which may include success/failure status, " +
+					"result data or content, and error messages if execution failed.",
 				RawInputSchema: callToolInputSchema,
 			},
 			Handler: createCallToolHandler(opt),