New concept guide: tool filtering and overrides for optimizing LLM context

[JAORMX]

Overview

Create a concept guide explaining when and why to use tool filtering and tool overrides in ToolHive. This guide should follow the Diataxis framework as an "explanation" doc, focusing on understanding rather than step-by-step instructions.

Parent issue: #187

Background from ToolHive Codebase Research

The Context Pollution Problem

When LLMs interact with MCP servers, they receive a list of available tools. Each tool adds to the context window:

• Tool name
• Tool description
• Input schema (parameters)

Problems with too many tools:

1. Token consumption: Each tool consumes tokens from the context window
2. Decision fatigue: LLMs may struggle to select the right tool from many options
3. Irrelevant options: Exposing all tools when only a subset is needed creates noise
4. Cost implications: Larger contexts increase API costs

Tool Filtering

What it does: Restricts which tools from an MCP server are exposed to clients using an allow-list approach (no block list).

Technical details (from pkg/mcp/tool_filter.go):

• Applied at the HTTP proxy level via middleware
• Intercepts tool list responses and filters out non-allowed tools
• Intercepts tool call requests and rejects calls to filtered tools (400 Bad Request)
• Empty filter = all tools allowed; non-empty filter = only listed tools exposed

Configuration:

• CLI: --tools tool1,tool2,tool3
• K8s: toolsFilter field in MCPToolConfig CRD

Tool Overrides

What it does: Renames tool names and/or updates descriptions at runtime without modifying the backend server.

Technical details (from pkg/mcp/tool_filter.go):

• Bidirectional mapping maintained: original names ↔ user-facing names
• Tool list responses show overridden names/descriptions
• Tool call requests translate user-facing names back to original names
• At least one of name or description must be provided per override

Configuration:

• CLI: --tools-override /path/to/overrides.json
• K8s: toolsOverride field in MCPToolConfig CRD

Override file format:

{
  "toolsOverride": {
    "original_tool_name": {
      "name": "user_friendly_name",
      "description": "Updated description for users"
    }
  }
}

Combined Usage

Important behavior: When using both filtering and overrides, the filter list uses user-facing names (post-override names), not original names.

Example:

# Override "fetch" to "custom_fetch", then filter by the new name
thv run --tools-override overrides.json --tools custom_fetch my-server

Content Requirements

The concept guide should explain:

1. The Context Pollution Problem

• What happens when LLMs receive too many tools
• Impact on performance, accuracy, and cost
• Why selective tool exposure matters

2. When to Use Tool Filtering

Use filtering when:

• An MCP server exposes more tools than needed for a specific use case
• You want to limit client access to a subset of safe/approved tools
• Different clients need different tool subsets from the same server
• You're optimizing for LLM performance by reducing options

Examples:

• Database server: expose only read operations, not write/delete
• File system server: expose only specific directories
• Multi-purpose server: expose only relevant tools per deployment

3. When to Use Tool Overrides

Use overrides when:

• Tool names don't match organizational naming conventions
• Descriptions are unclear or too technical for end users
• You need to differentiate tools when aggregating multiple servers (Virtual MCP)
• You want friendlier names without modifying the backend

Examples:

• Rename exec_raw_sql to run_database_query
• Update description from technical jargon to user-friendly text
• Prefix tools with server name in aggregation: github_search, jira_search

4. Combined Usage Patterns

Pattern 1: Secure subset with friendly names

• Filter to safe tools + override names for clarity

Pattern 2: Environment-specific configurations

• Development: more tools exposed
• Production: filtered to essential tools only

Pattern 3: Virtual MCP aggregation

• Multiple servers combined
• Overrides prevent name conflicts
• Filters ensure only relevant tools per source

5. Decision Framework

Questions to ask:

1. Does the MCP server expose tools I don't need?
2. Are the tool names/descriptions confusing?
3. Am I combining multiple MCP servers?
4. Do different users/clients need different tool sets?

Trade-offs:

• Filtering reduces flexibility but improves focus
• Overrides add configuration complexity but improve usability
• Combined use is powerful but requires careful name management

6. Best Practices

• Start with minimal tool sets and expand as needed
• Use descriptive override names that indicate purpose
• Document your filtering/override configurations
• Test tool behavior after applying overrides

Related Documentation

Link to but don't duplicate content from:

• CLI run guide - tool filtering section
• CLI run guide - tool overrides section
• UI customize tools guide
• K8s customize tools guide
• MCPToolConfig CRD reference

Style Requirements

• Follow the writing style guide
• Use second person ("you", "your")
• Active voice
• Sentence case in headings
• Focus on explaining concepts, not step-by-step instructions
• Include practical examples that illustrate the "why"

File Location

Create: docs/toolhive/concepts/tool-filtering-overrides.mdx

Update sidebars.ts to include the new page in the Concepts section.

Acceptance Criteria

• Explains the context pollution problem clearly
• Covers tool filtering: what it is, when to use it, examples
• Covers tool overrides: what it is, when to use it, examples
• Explains combined usage and the name precedence behavior
• Provides decision framework for when to use each feature
• Links to related how-to guides
• Follows Diataxis "explanation" framework
• Passes prettier, markdownlint, and eslint checks