Skip to content

SEP-1821: Add dynamic tool search support - #1822

Closed
truehazker wants to merge 3 commits into
modelcontextprotocol:mainfrom
truehazker:feature/SEP-1821
Closed

truehazker wants to merge 3 commits into
modelcontextprotocol:mainfrom
truehazker:feature/SEP-1821

Conversation

@truehazker

@truehazker truehazker commented Nov 17, 2025 •

Copy link
Copy Markdown

Add Tool Search Support to tools/list

Add ServerCapabilities.tools.filtering flag and query parameter to ListToolsRequestParams to enable agent-friendly tool search.

This implements the specification proposed in SEP-1821: Dynamic Tool Discovery.

Summary

  • New capability: ServerCapabilities.tools.filtering - indicates server supports tool search
  • New parameter: query (simple search string) on tools/list requests
  • Fully backward compatible: All parameters are optional

Enables agents to search for relevant tools instead of fetching complete catalogs, saving tokens and improving efficiency.

Key Features

  • Agent-optimized: Simple text queries ("database", "filesystem", "read files")
  • Flexible implementation: Servers choose strategy (substring, semantic, tag matching)
  • Efficient: Agents check the capability flag to know when filtering is available
  • Works with notifications: Combines naturally with tools.listChanged for dynamic updates

Types of changes

  • New feature (non-breaking change which adds functionality)
  • Documentation update

Checklist

  • I have read the MCP Documentation
  • My code follows the repository's style guidelines
  • New and existing tests pass locally
  • I have added or updated documentation as needed

AI Disclosure

I consulted Claude Sonnet to understand the codebase, design the feature through iterative refinement, and write the documentation.

Add the ClientCapabilities.dynamic field to indicate that the server supports dynamic tool filtering. Add query and metadata fields to ListToolsRequest.
@truehazker
truehazker requested a review from a team as a code owner November 17, 2025 08:09
Simplify the usage of the query and remove any metadata from it, as it’s uncertain how the agent should fill this metadata. Only use the query field for simple queries that are agent-friendly.

Closes modelcontextprotocol#1821
@dsp-ant dsp-ant added the proposal SEP proposal without a sponsor. label Nov 24, 2025
@localden localden changed the title feat(SEP-1821): 🎨 add dynamic tool search support SEP-1821: Add dynamic tool search support Jan 21, 2026
@localden

Copy link
Copy Markdown
Contributor

@truehazker this SEP does not have an assigned sponsor. Are you looking to continue working on it and find sponsorship?

@truehazker

Copy link
Copy Markdown
Author

Hi, the search and filtering are still a big itch I'd say in the MCP. I continue exploring solutions, but the current approach has ambiguity in terms of the query parameter format and server-side search implementation.

I'm still searching for something clear that can be actually used in a sort of deterministic way by the AI agents and LLMs.

So yeah, sponsoring would help me at least to have a second point of view.

@He-Pin

He-Pin commented Mar 6, 2026

Copy link
Copy Markdown
Contributor

Comment thread schema/draft/schema.ts
/**
* Whether this server supports filtering tools via the query parameter in tools/list requests.
*/
filtering?: boolean;

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

toolSearch

@localden

Copy link
Copy Markdown
Contributor

@truehazker sponsoring in this context is not necessarily for a second point of view - it's more about a sponsor supporting this moving forward, acknowledging that this needs to be done (see SEP guidelines).

If you haven't yet, I would highly recommend engaging with the community on Discord to see if there is interest in helping push this SEP forward.

@cliffhall @chughtapan - this seems like something that overlaps with your past work?

@chughtapan

Copy link
Copy Markdown
Contributor

@truehazker The current position of MCP core maintainers (my understanding atleast) is that such filtering can be done after clients fetch the list instead of doing it in the protocol.

But there is an ongoing effort to work on protocol extensions for such features and then revisit the standardization question later. It might be good to include in upcoming extension. We have a primitive-grouping-ig on discord where we can talk more.

@localden

Copy link
Copy Markdown
Contributor

Closing this proposal as it has not received a sponsor and there is an active recommendation to engage in Discord.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

dormant proposal SEP proposal without a sponsor. SEP

Projects

None yet

Development

Successfully merging this pull request may close these issues.

6 participants