tool-discovery

Tool Discovery Example

This example demonstrates how to use discoverable tools to reduce context window usage while maintaining access to a large tool library.

Overview

When you have many tools, sending all their definitions to an LLM consumes significant tokens from the context window. This example shows how to:

1. Register native tools (RegisterTool) - Essential tools that always appear in tools/list
2. Register discoverable tools (RegisterTool with .Discoverable()) - Specialized tools that are hidden but searchable via tool_search

How It Works

• RegisterTool(tool, handler) - Tool is visible in tools/list and searchable via tool_search
• RegisterTool(tool.Discoverable(keywords...), handler) - Tool is hidden from tools/list but searchable via tool_search
• The server automatically provides tool_search and execute_tool when any discoverable tools are registered
• LLMs can discover tools by keyword and get full schemas before calling them

Running the Example

cd examples/tool-discovery
go run main.go

The server will start on http://localhost:8088/mcp.

Testing

List Visible Tools

curl -X POST http://localhost:8088/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

This returns native tools plus tool_search and execute_tool.

Search for Tools

curl -X POST http://localhost:8088/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0",
    "id":2,
    "method":"tools/call",
    "params":{
      "name":"tool_search",
      "arguments":{"query":"database", "max_results": 5}
    }
  }'

Execute a Discovered Tool

curl -X POST http://localhost:8088/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0",
    "id":3,
    "method":"tools/call",
    "params":{
      "name":"execute_tool",
      "arguments":{
        "name":"sql_query",
        "arguments":{"query":"SELECT * FROM users", "database":"main"}
      }
    }
  }'

Tool Categories

This example registers tools in several categories:

• Database: sql_query, database_backup
• Email: send_email, list_emails
• Documents: create_pdf, convert_document
• DevOps: kubernetes_deploy, docker_build
• Analytics: analyze_data, create_chart
• Automation: run_backup_script, cleanup_logs, system_health_check

API

RegisterTool - Native Tools

Essential tools that always appear in tools/list:

server.RegisterTool(
    mcp.NewTool("help", "Get help and guidance"),
    handler,
)

• Always visible in tools/list
• Directly callable by name
• Searchable via tool_search
• Use for essential tools the LLM should always know about

RegisterTool with Discoverable() - Searchable Tools

Specialized tools hidden from tools/list but discoverable via search:

server.RegisterTool(
    mcp.NewTool("send_email", "Send an email",
        mcp.String("to", "Recipient", mcp.Required()),
        mcp.String("subject", "Subject", mcp.Required()),
    ).Discoverable("email", "notification", "smtp", "message"),
    handler,
)

• Hidden from tools/list
• Discoverable via tool_search
• Callable via execute_tool or directly if you know the name
• Keywords improve search relevance (matches tool name, description, and keywords)
• Use for specialized tools to reduce context window usage