mcp-filter-api-design

name	mcp-filter-api-design
description	Design filter/enum parameters for MCP tools consumed by LLM clients, balancing expressiveness with discoverability.
domain	mcp-server-design
confidence	medium
source	earned

Context

Use this when adding or redesigning filter parameters on MCP tools — especially when the underlying data model has multiple orthogonal filtering dimensions (e.g., state vs result vs issues). The goal is a filter API that LLMs can use correctly without domain expertise.

Patterns

Prefer named presets over orthogonal parameters

When the underlying data has N independent axes, do NOT expose N separate parameters if:

• Some axis combinations are invalid (e.g., state=pending + result=failed is contradictory)
• The valid combinations map to a small set of common queries
• The consumer is an LLM that picks from AllowedValues, not a human reading docs

Instead, use a single enum parameter whose values are named presets, each mapping to a documented (axis₁, axis₂, …) predicate.

Make preset names self-describing

Preset names ARE the documentation for LLM consumers. 'running' beats 'in-progress'; 'failed' beats 'non-succeeded'. Match the mental model of the caller, not the API's enum names.

Additive expansion is free; breaking changes are expensive

Adding new enum values to AllowedValues is backward-compatible. Renaming parameters, changing defaults, or splitting one parameter into two is a schema break that forces all callers to update.

Keep defaults stable

If 'failed' is the default and existing callers rely on it, don't change the default even if a new preset would be "better." Add the new preset and let callers opt in.

Extract shared predicate logic

When multiple tools use the same filter axis, extract the predicate into a shared helper (e.g., MatchesFilter(record, filterValue)) rather than duplicating switch logic. The helper becomes the single source of truth for what each preset means.

Parent/context walking follows filtering

If a filter narrows records to a subset, the parent-walk logic (including ancestor records for context) should apply uniformly to all non-'all' presets. Don't make parent walking preset-specific unless there's a strong reason.

Examples

• AzDO timeline records have state (pending/inProgress/completed) and result (succeeded/failed/…). Rather than exposing state and result as two params, use presets: 'failed', 'running', 'pending', 'incomplete', 'issues', 'all'.
• A Helix work item has State (Running/Passed/Failed/…). Rather than a free-text state filter, use presets: 'failed' (default), 'all', 'running'.

Anti-Patterns

• Exposing raw API enum values as two separate filter params and expecting the LLM to know which combinations are valid
• Using a single filter param that conflates orthogonal concepts without documenting the predicate mapping (the original 'failed' | 'all' bug)
• Adding a 'strict' or 'advanced' mode that changes how other params are interpreted
• Defaulting to 'all' when most callers want a narrowed view — forces every caller to add a filter