Repository navigation
Description
Preamble
Title: Tool Filtering with Groups and Tags
Authors: Pat White ([email protected]), Cliff Hall ([email protected])
Abstract
One of the most frequent concerns raised by the MCP community is LLM context overload when a server has too many tools. When more than about 10 tools are presented to an LLM it can become confused, and quality of tool selection suffers. Our current protocol offers no mitigation for this problem, meanwhile some servers have grown to encompass thousands of tools.
Motivation
MCP server developers are using various methods to combat the problem such as limiting the number of tools at server startup, but that is less than optimal for remote servers that need to be up all the time and for which the available tools may change over the lifetime of connected sessions. Another approach is splitting the tool list over a number of endpoints, but that may not work for clients which are not prepared to manage many endpoints for a server.
For this reason, we feel there should be an in-protocol way to mitigate the issue which does not require a cumbersome or backward-incompatible spec change.
Specification
Overview
We propose to:
- Introduce a new capability for filtering.
- Add two new core primitives:
- Group: a first-class object that defines a collection of tools. Includes a name, title, and description. Groups are for separating the tool list by functional area or use case.
- Tag: a lightweight, user-defined label that may be attached to any number of tools. Includes a name and description. A particular tag may appear on tools across a number of groups. Tags are for cross-cutting concerns, such as whether a tool is destructive.
- Extend the existing
tools/listRPC method, with a newfilterparameter, in a fully backwards compatible way, enabling clients to narrow the response by requesting only tools that match a specific set of groups and tags.
With filtering capabilities, the client / agent can select which subsets of the tool list to interact with based on current context. After fetching the group and tag lists in order to have full description of each for reference and presentation to LLM and/or user, dynamic filtering of tools can be done in two ways:
- Client-side filtering of tools: Agent fetches all the tools with no filtering, organizes them by groups and tags within the host application, then provides the appropriate tools to the LLM when needed via whatever means, e.g., semantic search.
- Server-side filtering of tools: Agent presents a list of groups to the LLM. When the LLM decides it needs a tool but doesn't have an appropriate one in its context, it may request the list of tools in a particular group or set of groups.
In either case, the groups and tags may also be presented to the user for selection. For instance, the user could choose not to allow the use of tools tagged "experimental" or "destructive" or in the group "user" or "admin".
Note: Broader filtering capabilities such as boolean logic operators and applicability of filtering to other lists such as resources and prompts, will be assessed in a future SEP. This proposal is meant to focus narrowly on reducing the tool list dynamically to avoid the pressing issue of overloading the LLM's context, while allowing all tools to be available all the time.
New Capability: filtering
Servers that support filtering MUST declare the filtering capability during initialization, including whether list change notifications are supported. Group and tag lists can change at runtime, and so support for listChanged notifications for each is included.
{
"capabilities": {
"filtering": {
"groups": {
"listChanged": true
},
"tags": {
"listChanged": true
}
}
}
}New Primitive: group
A Group is a named collection of one or more tools. The primary intent of groups is to separate the server's toolspace by functionality or use case.
Note: When grouping tools by functionality, a tool of should only appear in one group. However, if tools are grouped by use case, a tool might appear in multiple groups. For example, a spell_check tool might appear in both compose_email and compose_document groups. Agents should be aware of this when managing the LLM's context so as not to present the same tool more than once.
Discovery method: groups/list
Request:
{
"jsonrpc": "2.0",
"id": 2,
"method": "groups/list"
}Response:
{
"jsonrpc": "2.0",
"id": 2,
"result": {
"groups": [
{
"name": "user",
"title": "User Management Tools",
"description": "Tools used for managing user accounts within the system."
},
{
"name": "mapping",
"title": "Geospatial Mapping Tools",
"description": "Tools used for map rendering, geocoding, and spatial analysis."
}
]
}
}Use Cases for Groups
- Discovery: Client UIs can display groups of tools and selectively load only desired tools into LLM context - "Geospatial Mapping Tools" as a category
- Access control: Access could be granted at the group level, creating a consistent abstraction from security design to RPC layer
- Use Case: A productivity server could expose use case based groups, such as Email or Calendar, and present related tools, e.g. Email: ["Draft Email", "Spell Check"], Calendar: ["Find Open Time", "Create Appointment"]
- Bulk operations: enable, disable, hide, or version all tools in a group
New Primitive: tag
A Tag is a free-form label that can be attached to any tool—similar to Git labels or Kubernetes tags, and appear as part of a tool's definition. In contrast to groups which are intended for functional separation of the toolspace, tags are primarily used to denote cross-cutting concerns such as status (e.g., 'stable') or operational safety (.e.g, 'destructive').
Discovery method: tags/list
Request:
{
"jsonrpc": "2.0",
"id": 2,
"method": "tags/list"
}Response:
{
"jsonrpc": "2.0",
"id": 2,
"result": {
"tags": [
{
"name": "beta",
"description": "Experimental or in-testing tools"
},
{
"name": "stable",
"description": "Production-ready tools."
}
]
}
}Use Cases for Tags
- Ad hoc filtering: server could allow end-users to "tag" favorites (e.g. "my-top-tools").
- Lifecycle: mark tools as "deprecated", "stable", or "experimental."
- Integration: CI pipelines can select all "release-candidate" tools for smoke testing.
New tools/list Parameter: filter
Request:
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/list",
"params": {
"cursor": "...",
"filter": {
"groups": ["pull-requests", "issues"],
"tags": ["stable", "non-destructive"]
}
}
}Arguments:
groups(string array): Only return tools belonging to ANY of these named groups.tags(string array): Of the tools in the specified groups (or of all tools, if no groups were specified), only return tools tagged with ALL of these tags.
Fully backwards compatible - If filter is omitted, behavior is unchanged: all tools are returned (subject to pagination as usual).
Changes to Response Format
Example tool definition from tools/list response with groups and tags:
{
"name": "arithmetic_calculator",
"title": "Arithmetic Calculator",
"description": "Perform mathematical calculations",
"inputSchema": {
"type": "object",
"properties": {
"expression": {
"type": "string",
"description": "Mathematical expression to evaluate (e.g., '2 + 3 * 4')"
}
},
"required": ["expression"]
},
"groups": ["arithmetic"],
"tags": ["stable", "non-destructive"]
}Filter Combinations
By mixing the filter parameter with these primitives, clients can express powerful queries. Assuming the client has asked the server for the available groups and tags, let's explore some use cases.
Simple narrowing of tool list by tag
The client is a dev-ops app, and wishes to work with internal management tools, so it fetches all tools tagged "internal". Access to these tools could require special authentication and would not be contained in a list returned to unauthenticated users not in a particular access control group.
{ "filter": { "tags": ["internal"] } }Simple narrowing of tool list by group
The client currently wants to work with pull requests and issues, so it requests a list of all tools in the "pull_requests", "issues" groups.
{ "filter": { "groups": ["pull_requests", "issues"] } }Narrowing of tool list by group, further filtered by tag
The client currently wants to work with pull requests and issues, but there are beta/experimental tools available which it would like to avoid. So it requests a list of all tools in the "pull_requests", "issues" groups that are tagged "stable".
{
"filter": {
"groups": ["pull_requests", "issues"],
"tags": ["stable"]
}
}Rationale
We have proposed top level groups and tags properties for tool definitions. An alternative would be to make them annotations. This would just require pushing them down one level into an annotations object on the tool definition.
There have been suggestions that groups and tags are the same thing and therefore only one primitive should be considered. When we began discussing this proposal, we too, felt that they could possibly collapse into a single primitive. Further thought led us to believe that tags are sufficiently different from groups to merit inclusion.
The benefit of grouping is obvious; segment a large number of tools into smaller sets by similar functionality or use case. But tags may apply across many groups. The example of the 'destructive' tag is most clear. If a client does not have 'brave' or 'yolo' mode on, it should not request destructive tools, which may appear in all groups.
Alternatively, for communicating the destructiveness of a tool (only one example of a tag), a model hint might be used, but it would not be a way to narrow the tool list, which is the ultimate focus of this proposal.
Backward Compatibility
The proposed changes are fully backward compatible.
Reference Implementation
- Schema and docs are updated in this draft PR.
- A full technical implementation has been added as added as a draft PR in the Typescript SDK. It includes the necessary SDK changes, unit tests, integration tests, and client/server examples.
Server Example
Client Example
Security Implications
No security issues have been identified.
Future Discussion
Our focus with this proposal is on adding a basic tool filtering capability with groups and tags as a way of mitigating the tool overload problem. There were some good ideas that we considered including, but are shelving for the sake of simplicity. Should this proposal be accepted, we would consider them in the future.
- Partial Name Matching - e.g., name_contains or name_begins_with
- Filtering by Annotations - audience, priority, last modified, etc.
- Logical expressions - AND, OR, NOT, greater than, less than, include, exclude, etc.
- Resources and Prompts - adding filter parameter to their list RPCs
- Hierarchical Groups - Groups within groups has often come up in discussions
Activity
patwhite commentedon Aug 4, 2025
This supersedes #993 - just to add some color, this proposal came after a lot of work with various stake holders around MCP clients, servers, and more, and represents a really good balance of protocol changes and filtering capabilities. We're focused very tightly on this problem of scoping DOWN tools to context, hence why we're using additive filters here.
MathiasChristiansen commentedon Aug 5, 2025
[-]Tool Filtering with Groups and Tags[/-][+]SEP-1300: Tool Filtering with Groups and Tags[/+]cliffhall commentedon Aug 5, 2025
MathiasChristiansen commentedon Aug 5, 2025
59 remaining items
bdoyle0182 commentedon Sep 3, 2025
I align with all of that and puts it more concisely than i could have. I'll join the group to see what the more detailed discussion looks like
cliffhall commentedon Sep 11, 2025
Quick catch-up for anyone following this SEP thus far:
scottslewis commentedon Oct 5, 2025
In reading and searching through the discussion about tool filtering above, I didn't see a mention of the possible use/reuse of RFC-1960. It's a general, ietf-standardized filtering syntax for searching through an arbitrary dictionary of name->value pairs. This can and does work for protocol types that are serialized to and from json objects (e.g. Tools, Resources, etc).
I'm not at all sure if it would satisfy all the filtering use cases described above, but it might provide a good starting point.
dgenio commentedon Nov 27, 2025
Really appreciate the work going into SEP-1300 – the motivation around tool overload and more structured discovery resonates a lot with what we’re seeing in practice.
One pattern I keep running into as a host/platform implementer is the need for a hard allowlist of tools (and, by extension, prompts/resources) per agent / tenant / use case.
Today I can implement that entirely on the host side by:
tools/listonce,That solves the “LLM gets 400 tools in context” problem, but it does not solve:
tools/listpayload just to filter it away;Given SEP-1300 already introduces a
filterobject withgroupsandtags, would it make sense to extend it with explicit name-based allow/deny lists, e.g.:{ "method": "tools/list", "params": { "filter": { "names": ["tool_a", "tool_b_v2"], "excludeNames": ["tool_experimental_*"] } } }A few reasons this feels useful:
It composes nicely with other SEPs:
It gives hosts a very simple building block for:
It’s fully backwards compatible (servers that don’t implement
namescan ignore it).In a follow-up SEP, I’d love to see the same pattern mirrored for other discovery RPCs:
prompts/list→filter.namesfor promptsresources/list→filter.urisorfilter.namesfor resourcesThat would make it much easier for hosts to keep “what the LLM sees” tightly scoped across the board, without having to reimplement ad-hoc filtering logic on every client.
Happy to help sketch examples of how this would look end-to-end in host configs and how it might interact with SEP-1766 and scoped discovery work.
scottslewis commentedon Nov 27, 2025
It seems that #1904 is headed in similar directions...i.e. a common filtering api for many types.
duwenji commentedon Nov 30, 2025
Comment on SEP-1300: Tool Filtering with Groups and Tags
Thank you for proposing this important enhancement to address LLM context overload. I'd like to provide some additional considerations based on the current proposal:
1. Extending Beyond Tools
The current SEP-1300 focuses specifically on tool filtering, but the same context overload problem exists for Resources and Prompts as well. As MCP servers grow in complexity, they may expose numerous resources and prompts that can similarly overwhelm LLM context windows.
Suggestion: Consider extending the filtering mechanism to include Resources and Prompts, not just Tools. This would provide a more comprehensive solution to the context management problem across all MCP primitives.
2. User-Centric, Systematic Approach
While the proposed groups and tags approach is valuable, I believe we need a more systematic, user-centric solution. The current proposal puts significant burden on the client/agent to understand and manage the filtering logic.
Proposed Alternative Approach:
Concern-Based Filtering System
Concern Declaration: MCP servers should declare a list of available "Concerns" they support
Concern Configuration: MCP Hosts should be able to:
Dynamic Subset Generation: Based on the configured concerns, the MCP server would return appropriate subsets of:
Benefits of This Approach:
Example Workflow:
This concern-based approach would complement the groups/tags system by providing a higher-level, user-oriented filtering mechanism while still allowing for the technical organization that groups and tags provide.
I believe combining both approaches would give us the best of both worlds: technical organization for developers and intuitive control for users.
bdoyle0182 commentedon Dec 1, 2025
HI @duwenji , this SEP is superseded by the Groups working group, see discussion #1567
Please continue conversation there.
The current drafts of the SEP's are in google docs until they're ready for review. Filtering will not be tackled until groups as a logical abstraction in some form has made it into the protocol or for some reason agreed upon as not needed after review of the SEPs by the core maintainers. See today's meeting notes for current state of things #1920
@cliffhall should we mark this as closed so we don't continued discussion on this now outdated sep?
sauravsingla commentedon Aug 15, 2026
We have been exploring a related problem in AgentWeave: selecting the right tool/API or specialist for a task rather than exposing the full capability set to the model.
One practical observation from our experiments is that tool filtering becomes more useful when the selection layer can incorporate not only static metadata such as groups/tags, but also observed capability evidence.
We evaluated the routing layer using external benchmark task distributions including ToolBench, where AgentWeave performs tool/API selection over a large external tool catalog, as well as AgentBench and AgencyBench for specialist/agent routing.
Repo and evaluation:
https://github.com/sauravsingla/agentweave
This suggests a possible separation of concerns:
MCP groups/tags/capability metadata -> candidate tool set -> external router/evidence layer -> selected tools exposed to the LLM
The MCP protocol would not need to prescribe the ranking algorithm, but richer filtering metadata could make evidence-aware selection more interoperable.
It may also be useful to distinguish declared tool applicability from observed tool performance so that clients can make dynamic filtering decisions based on task context and historical outcomes.
feat: add MCP server "domains" (microsoft#421)