# `MCP011` Search and filter tests
{bdg-ref-info}`mcp | tools <mcp:tools>`
{bdg-ref-info}`mcp | query <mcp:query>`
{bdg-ref-info}`mcp | discovery <mcp:discovery>`
{bdg-ref-info}`mcp | traceability <mcp:traceability>`
> I would like to discover what tests exist by searching with filters like category
> or the requirement they validate. For example, "show me all non-functional tests"
> or "which functional tests validate RF03" helps me explore the test suite and
> prepare targeted test campaigns.
> 

The user shall be able to search for tests using optional filter criteria.

The MCP server shall expose a tool named `search_tests` that accepts
optional filter parameters and returns matching tests.

Filter parameters:
- `category`: Filter by category (exact match, e.g., "functional"). If the
  category does not exist in the loaded specifications, an error shall be returned.
- `tester_of`: Filter by requirement ID — returns only tests that reference
  that requirement in their `ref` field. If the requirement ID does not
  exist, an error shall be returned.

If no filters are provided, all tests shall be returned.
Filters can be combined.

The response shall be a list of test summaries, each containing:
- `id`: The unique identifier
- `short`: The short description (if present)
- `category`: The test category

The list shall be sorted alphabetically by ID.


:::{dropdown} Properties
:icon: note
:color: primary

__author__: Claude

__since__: `0.2.0`

:::
:::{dropdown} Tested by
:open: 
:icon: check-circle-fill
:color: success

- [`TMCP036` search_tests returns all tests when unfiltered](/tests/TMCP036)
- [`TMCP037` search_tests filtered by category](/tests/TMCP037)
- [`TMCP038` search_tests filtered by tester_of](/tests/TMCP038)
- [`TMCP039` search_tests filtered by category and tester_of](/tests/TMCP039)
- [`TMCP040` search_tests returns empty list when tester_of has no tests](/tests/TMCP040)
- [`TMCP041` search_tests errors on unknown category](/tests/TMCP041)
- [`TMCP042` search_tests errors on unknown tester_of](/tests/TMCP042)
:::

:::{dropdown} References
:icon: link
:color: secondary

__Relates to:__
[`MCP005` Search and filter requirements](/requirements/MCP005)

:::

:::{dropdown} Source
:icon: file-code
:color: info

__Source file__: [`specs/mcp/discovery.yaml`](https://github.com/agagniere/speky/blob/master/specs/mcp/discovery.yaml)

__Loaded from__: [`speky_mcp`](https://github.com/agagniere/speky/blob/master/specs/mcp/mcp.toml)

__Implemented in:__
{fab}`python` [`handle_search_tests`](https://github.com/agagniere/speky/blob/master/python/speky_mcp/tools.py#L172)
:::