Skip to content

feat(tools): semantic tools/list filter for agent tool discovery #440

@cjimti

Description

@cjimti

Problem

Personas filter the tool catalog by glob patterns on tool names today. The agent still sees every tool the persona allows; for an admin persona that is dozens of tools across kinds. The agent burns context picking among them and frequently picks suboptimally because the names alone do not communicate intent.

The api-gateway already solved the equivalent problem at the endpoint layer: `api_list_endpoints` semantic ranking. The pattern lifts cleanly up one layer to the tool catalog itself.

Proposal

Embed every registered tool's name + description + parameter schema summary at server start. Add an optional `query` argument to `tools/list` (server capability-gated under `ServerCapabilities.tools.filtering` once that MCP SEP advances). When the agent supplies a natural-language query, return the top K tools by cosine similarity instead of the unfiltered list.

Without the protocol-level filter (current SDK state), expose the same capability as an MCP tool: `platform_find_tools(query, limit)` that returns ranked tool descriptors. The agent calls this once at the start of a task instead of looking at every name.

Depends on

#438 (indexing-job framework). Tools are a small corpus (low hundreds at most) and could be embedded in-memory at startup without a queue, but using the framework keeps the indexing path uniform and gives operators one place to inspect index health.

Acceptance criteria

  • Tool descriptors indexed at startup; re-indexed when the tool registry changes (admin tool-visibility flips, etc).
  • `platform_find_tools(query, limit)` ranks tools by description similarity and returns descriptor + score.
  • Persona deny rules still apply: the model sees only tools its persona is permitted to call.
  • Memory: `no_tool_explosion` rule is reinforced; this is the discovery shape that complements `api_list_endpoints`.

Out of scope

  • MCP protocol filter (SEP-1821 is its own tracking item; we ship the app-level tool first).
  • Auto-pick the tool; the agent still chooses. This is discovery, not routing.

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions