Skip to content

tooldiscovery User Journey

Overview

This guide walks through the progressive disclosure pattern that tooldiscovery enables: discover cheaply, inspect on-demand, then execute.

1. Installation

go get github.com/jonwraymond/tooldiscovery@latest

2. Set Up the Index

import "github.com/jonwraymond/tooldiscovery/index"

// Create an in-memory index
idx := index.NewInMemoryIndex()

3. Register Tools

import "github.com/jonwraymond/toolfoundation/model"

// Create and validate a tool
tool := model.Tool{
  Namespace: "github",
  Tool: mcp.Tool{
    Name:        "create_issue",
    Description: "Create a new GitHub issue",
    InputSchema: map[string]any{...},
  },
}

// Define the backend
backend := model.ToolBackend{
  Kind:       model.BackendKindMCP,
  ServerName: "github-mcp",
}

// Register
err := idx.RegisterTool(tool, backend)

4. Search for Tools (Token-Cheap)

// Search returns summaries without schemas
summaries, err := idx.Search("create issue", 5)
if err != nil {
  log.Fatal(err)
}

for _, s := range summaries {
  fmt.Printf("Found: %s - %s\n", s.ID, s.Summary)
}

5. Get Full Documentation (On-Demand)

import "github.com/jonwraymond/tooldiscovery/tooldoc"

store := tooldoc.NewInMemoryStore(tooldoc.StoreOptions{Index: idx})

// Progressive detail levels
doc, _ := store.GetDoc("github:create_issue", tooldoc.DetailSummary)
fmt.Println(doc.Summary)

doc, _ = store.GetDoc("github:create_issue", tooldoc.DetailSchema)
fmt.Printf("Input Schema: %v\n", doc.Tool.InputSchema)

Detail Level Guidance

  • Summary: listing/search results (token-cheap)
  • Schema: just-in-time execution
  • Full: documentation view or export

6. Enable BM25 Search (Optional)

import "github.com/jonwraymond/tooldiscovery/search"

// Create BM25 searcher with custom config
config := search.Config{
  NameBoost:      4.0,
  NamespaceBoost: 2.0,
  TagBoost:       1.0,
}

searcher, err := search.NewBM25Searcher(config)
if err != nil {
  log.Fatal(err)
}
defer searcher.Close()

// Create index with BM25 strategy
idx := index.NewInMemoryIndex(index.WithSearchStrategy(searcher))

7. List Namespaces

namespaces := idx.ListNamespaces()
// ["github", "slack", "jira", ...]

// Filter tools by namespace
tools := idx.ListToolsInNamespace("github")

Progressive Disclosure Flow

Agent                    MCP Server              tooldiscovery
  |                          |                        |
  |-- search_tools("issue") -|                        |
  |                          |-- idx.Search() --------|
  |                          |<-- []Summary ----------|
  |<- summaries (no schema) -|                        |
  |                          |                        |
  |-- describe_tool(id) -----|                        |
  |                          |-- store.GetDoc() -----|
  |                          |<-- ToolDoc w/schema ---|
  |<-- full schema ----------|                        |
  |                          |                        |
  |-- run_tool(id, args) ----|                        |
  |                          |      (to toolexec)     |

Next Steps