toolsearch

package
v0.7.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 5, 2026 License: MIT Imports: 14 Imported by: 0

Documentation

Overview

Package toolsearch is the built-in `tool_search` extension: tool discovery with a BM25 ranker over tool metadata, shared by `searchTools()` in codemode scripts and the optional `tool_search` tool.

`tool_search` searches tools that are not declared to the model (`codemode` and `deferred` exposure) and loads the matches, so they are declared for the next model call. Loading goes through the active tool set, so it is recorded in the transcript like any other tool change.

Ports packages/coding-agent/src/extensions/tool-search/tool.ts.

Index

Constants

View Source
const DefaultLimit = 8

DefaultLimit is the number of tools a search returns unless the caller passes a limit.

View Source
const ToolName = "tool_search"

ToolName is the name of the tool.

View Source
const ToolSearchDescription = "# Tool discovery\n\nSearches over deferred tool metadata with BM25 and exposes matching tools for the next model call.\n\nSome of the tools, such as tools of MCP servers, may not have been provided to you upfront, and you should use this tool (`" + ToolName + "`) to search for the required tools. For MCP tool discovery, always use `" + ToolName + "`."

ToolSearchDescription is the `tool_search` description. It does not list the searchable tools or their namespaces, so it stays the same while tools are registered, for example when MCP servers connect.

Ports packages/coding-agent/src/extensions/tool-search/tool.ts (TOOL_SEARCH_DESCRIPTION).

Variables

This section is empty.

Functions

func CreateToolSearchExtension

func CreateToolSearchExtension() extension.ExtensionFactory

CreateToolSearchExtension is the factory of the `builtin:tool-search` extension: it registers the tool inactive. Activate it with `--tools`, the `defaultTools` setting or `setActiveTools()`.

Ports packages/coding-agent/src/extensions/tool-search/index.ts (createToolSearchExtension).

func Definition

func Definition() extension.ToolDefinition

Definition is the tool definition of `tool_search`, without the registration flag: Extension registers it inactive.

Ports packages/coding-agent/src/extensions/tool-search/tool.ts (createToolSearchToolDefinition).

func LimitOf

func LimitOf(limit float64) int

LimitOf converts a validated positive integer limit to an int. JavaScript's slice(0, limit) accepts any number, so a limit beyond the int range keeps every match instead of wrapping around to a negative int.

func Tokenize

func Tokenize(text string) []string

Tokenize is Pi's tokenize: Unicode word segmentation of the NFC-normalized text with identifier boundaries, without English stop words and with singular forms (searchtext.Tokenize).

Types

type Bm25Ranker

type Bm25Ranker struct{ K1, B float64 }

Bm25Ranker is Okapi BM25 over the description, with the name and the namespace as separate fields:

  • a tool that matches more of the query's terms, in any field, ranks above one that matches fewer, whatever their scores: for `screenshot window`, a tool whose description has both words beats `window`, whose name has one;
  • a query term in the name scores more than any number of mentions in the description;
  • a tool whose whole local name is in the query (`app` in `peekaboo app` for `mcp__peekaboo__app`) gets a bonus worth one more match of every query term, so among tools matching as many terms it mostly wins over tools that only mention the words;
  • a query that is exactly a tool's name ranks that tool first, before coverage.

The description alone is length-normalized, so a long name or long namespace instructions do not lower a tool's score. Ties keep document order.

func NewBm25Ranker

func NewBm25Ranker() *Bm25Ranker

NewBm25Ranker returns a ranker with k1 1.2 and b 0.75.

func (*Bm25Ranker) Rank

func (r *Bm25Ranker) Rank(query string, documents []Document, limit int) []Match

Rank returns at most limit matches with a positive score, best first.

type Details

type Details struct {
	// Loaded lists the tools this call loaded.
	Loaded []string `json:"loaded"`
}

Details are the details of a tool_search result.

type Document

type Document struct {
	Name string
	// Text is the description, schema descriptions and property names.
	Text string
	// NamespaceText is the name, description and instructions of the tool's namespace.
	NamespaceText string
}

Document is a tool as the ranker sees it: its name and the texts built by CreateDocument.

func CreateDocument

func CreateDocument(tool extension.ToolInfo, namespace *extension.ToolNamespace) Document

CreateDocument builds the search texts of a tool: the description with the schema descriptions and property names, and separately the namespace name, description and instructions. The ranker reads the name from Name. BM25 counts terms, so the order of the parts does not matter.

type Match

type Match struct {
	Name  string
	Score float64
}

Match is one ranked tool.

type Ranker

type Ranker interface {
	Rank(query string, documents []Document, limit int) []Match
}

Ranker ranks tools for a query. BM25 today; a hybrid ranker with embeddings can replace it.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL