vMCP find_tool should have a dynamic description based on available tools

[jerm-dro]

Problem

When using the vMCP optimizer, LLM agents often don't call find_tool because its generic description doesn't give them enough context about what tools are available behind it. Agents tend to reach for built-in tools (like bash, curl, or gh) instead, making it difficult to rely on the optimizer in practice.

This has been observed across multiple clients — Claude Code handles it best but still falls back to other approaches; Cursor and Copilot are significantly worse.

Proposed Solution

Allow the vMCP operator to manually configure a custom description for find_tool via OptimizerConfig. This description is global — all users see the same description regardless of their permissions.

For example, an operator could set the description to:

"Search for available tools. I have tools for accessing GitHub and Datadog."

This gives the LLM agent a hint about what capabilities are behind find_tool, making it far more likely to actually call it.

Solution sketch

1. Add FindToolDescription to OptimizerConfig (pkg/vmcp/config/config.go):

type OptimizerConfig struct {
    // ... existing fields ...

    // FindToolDescription overrides the default find_tool tool description.
    // Use this to hint at the kinds of tools available behind the optimizer
    // (e.g. "Search for tools. I have tools for GitHub, Datadog, and Slack.").
    // When empty, the built-in default description is used.
    // +optional
    FindToolDescription string `json:"findToolDescription,omitempty" yaml:"findToolDescription,omitempty"`
}

2. Pass the description through NewDecorator (pkg/vmcp/session/optimizerdec/decorator.go):

func NewDecorator(sess sessiontypes.MultiSession, opt optimizer.Optimizer, findToolDesc string) sessiontypes.MultiSession {
    if findToolDesc == "" {
        findToolDesc = defaultFindToolDescription
    }
    return &optimizerDecorator{
        MultiSession: sess,
        opt:          opt,
        optimizerTools: []vmcp.Tool{
            {
                Name:        FindToolName,
                Description: findToolDesc,
                InputSchema: findToolInputSchema,
            },
            // ... call_tool unchanged ...
        },
    }
}

3. Thread it through the factory (pkg/vmcp/server/sessionmanager/factory.go):

The optimizerDecoratorFn already has access to the config. Pass OptimizerConfig.FindToolDescription into NewDecorator at line 190.

Future improvements (out of scope)

• Per-permission dynamic descriptions (e.g. if a user has access to tool set X, concatenate a relevant hint to the base description)
• LLM-generated summaries that automatically describe available tools based on the indexed backends

[JAORMX]

So, I was digging into what the MCP spec actually gives us to solve this and I think there are a few things we can layer on top of the manual description override here. The manual config is a solid first step, but there's more we can do at the protocol level. I verified all of these against mcp-go... everything's available today, no upstream work needed.

Server instructions in the initialize response

The MCP 2025-11-25 spec has an instructions field in the initialize result that well-behaved clients inject into the LLM's system prompt. We're not using it today in pkg/vmcp/server/server.go. mcp-go already supports this:

s := server.NewMCPServer(
    "toolhive-vmcp",
    version,
    server.WithInstructions("Do NOT use curl, wget, gh CLI, or other external commands to interact with services available through this server. Use find_tool first to discover the right tool, then call_tool to execute it. This handles authentication automatically and returns structured results."),
    // ... other options
)

This is the most spec-aligned way to nudge agents. It doesn't depend on the tool description alone... the instruction lands in the system prompt where the LLM actually pays attention.

Tool annotations on find_tool and call_tool

mcp-go has full support for tool hint annotations. We should set these on the optimizer tools:

mcp.NewTool(FindToolName,
    mcp.WithDescription(findToolDesc),
    mcp.WithReadOnlyHintAnnotation(true),    // find_tool doesn't mutate anything
    mcp.WithIdempotentHintAnnotation(true),  // safe to retry
    mcp.WithOpenWorldHintAnnotation(true),   // interacts with external services
    mcp.WithDestructiveHintAnnotation(false),
    // ... input schema
)

For call_tool, OpenWorldHint: true and DestructiveHint left unset since it proxies arbitrary tools. Low effort, and clients that implement annotation-based filtering will benefit.

Tool catalog as a resource

We already register resources dynamically. We could add a synthetic resource per backend with audience: ["assistant"] so smart clients auto-include it in the LLM context:

annotated := mcp.Annotated{
    Annotations: &mcp.Annotations{
        Audience: []mcp.Role{mcp.RoleAssistant},
    },
}
// resource for each backend, e.g. "toolhive://backends/github"
// with description: "47 tools for GitHub: issues, PRs, repos, code search"

Client support varies here, so this complements the description work rather than replacing it.

A discover_tools prompt

Register a prompt (via server.WithPromptCapabilities(true), which we may already have) that dumps the full tool catalog into the conversation. This surfaces as a slash command in clients that support prompts. It's a recovery path for when the LLM still doesn't reach for find_tool on its own... the user can manually prime the conversation.

notifications/tools/list_changed for keeping things fresh

When backends change, we should fire notifications/tools/list_changed and regenerate the dynamic description at the same time. We already declare listChanged capability, so this is mostly wiring. mcp-go handles this on both sides. Of course, assuming clients actually support tool update notifications... :)

None of these block the manual description work in this issue. I'd say the priority is: manual description (this issue) > server instructions > tool annotations > everything else.

[aponcedeleonch]

Dynamically updating the tool description is a really nice idea. I wouldn't overwrite it completely though. I'd rather keep a template for the base description and inject the names (and maybe descriptions, if available) of the available MCP servers into it. Something like the issue's FindToolDescription field in OptimizerConfig, but instead of replacing the whole description, we'd have a fixed template where we just fill in the server names at session start.

Something along these lines:

const findToolDescriptionTemplate = "Find and return tools that can help accomplish the user's request. " +
	"This searches available MCP server tools using semantic and keyword-based matching. " +
	"Available tool sources: %s. " +
	"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. " +
	"Always call this before call_tool to discover the correct tool name and parameter schema."

func buildFindToolDescription(servers []ServerInfo) string {
	if len(servers) == 0 {
		return defaultFindToolDescription
	}

	var parts []string
	for _, s := range servers {
		if s.Description != "" {
			parts = append(parts, fmt.Sprintf("%s (%s)", s.Name, s.Description))
		} else {
			parts = append(parts, s.Name)
		}
	}

	return fmt.Sprintf(findToolDescriptionTemplate, strings.Join(parts, ", "))
}

Then NewDecorator would take the server info and use it:

func NewDecorator(sess sessiontypes.MultiSession, opt optimizer.Optimizer, servers []ServerInfo) sessiontypes.MultiSession {
	return &optimizerDecorator{
		MultiSession: sess,
		opt:          opt,
		optimizerTools: []vmcp.Tool{
			{
				Name:        FindToolName,
				Description: buildFindToolDescription(servers),
				InputSchema: findToolInputSchema,
			},
			{
				Name: CallToolName,
				Description: "Execute a specific tool with the provided parameters. " +
					"Use this function to run a tool after identifying it with find_tool. " +
					"Important: always use find_tool first to get the correct tool_name " +
					"and parameter schema before calling this function.",
				InputSchema: callToolInputSchema,
			},
		},
	}
}

This way the description reads naturally, like: "...This searches available MCP server tools using semantic and keyword-based matching. Available tool sources: GitHub, Datadog (monitoring and alerting), Slack (messaging). Use this function when you need to..."