Ranks tools by semantic similarity to a natural-language query, for tool sets large enough
(100-200+) that even a well-tuned static filter (ToolFilterOptions) can't narrow the set down
for one specific user intent.
Generic over the tool shape (default DynamicToolDefinition, this library's own OpenAPI-derived
type) — the ranking only ever reads name/description/tags, so the same index works unmodified
for tools from any other source (an MCP server's tools/list, a hand-written tool registry, ...)
as long as they satisfy SemanticTool. search() returns the exact objects passed to build(), so
callers get back their own tool type, not a stripped-down stand-in.
Deliberately does not call any embedding API itself — EmbeddingProvider is a bring-your-own-X
interface (same pattern as AccessTokenProvider/ResponseProcessor), so this library stays
unopinionated about which embedding model or provider (OpenAI, Cohere, a local model, ...) is
used. This class only owns what's actually hard to get right: building the index once and
ranking many search() queries against it without re-embedding every tool per query.
Ranks tools by semantic similarity to a natural-language query, for tool sets large enough (100-200+) that even a well-tuned static filter (ToolFilterOptions) can't narrow the set down for one specific user intent.
Generic over the tool shape (default DynamicToolDefinition, this library's own OpenAPI-derived type) — the ranking only ever reads name/description/tags, so the same index works unmodified for tools from any other source (an MCP server's tools/list, a hand-written tool registry, ...) as long as they satisfy SemanticTool. search() returns the exact objects passed to build(), so callers get back their own tool type, not a stripped-down stand-in.
Deliberately does not call any embedding API itself — EmbeddingProvider is a bring-your-own-X interface (same pattern as AccessTokenProvider/ResponseProcessor), so this library stays unopinionated about which embedding model or provider (OpenAI, Cohere, a local model, ...) is used. This class only owns what's actually hard to get right: building the index once and ranking many search() queries against it without re-embedding every tool per query.