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 ¶
const DefaultLimit = 8
DefaultLimit is the number of tools a search returns unless the caller passes a limit.
const ToolName = "tool_search"
ToolName is the name of the tool.
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).
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.
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.