toolsearch

package
v0.5.3 Latest Latest
Warning

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

Go to latest
Published: Oct 23, 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 lowercases text into terms, splitting at camelCase boundaries and non-alphanumerics, without stop words. pig divergence (D173): Pi's tokenizer splits on /[^a-z0-9]+/ and so drops every Chinese, Japanese and Korean character (Pi #10816); PiG makes each of those characters a term of its own, so a query in those scripts matches a tool whose metadata holds the same characters. Text without such characters tokenizes as in Pi.

Types

type Bm25Ranker

type Bm25Ranker struct{ K1, B float64 }

Bm25Ranker is Okapi BM25 with the usual parameters. 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 string
}

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

func CreateDocument

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

CreateDocument builds the search text of a tool: the name, the name with `_` as spaces, the description, schema descriptions and property names, and the namespace with its description and instructions. 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