Resource

MCP tool-description test cases

Copyable test cases for checking that a tool description makes its purpose, nearest neighbour, inputs, result shape and recovery path clear. Each case is checked against one of this site’s four reference MCP tools.

Download Markdown

These cases cover the reference tools. The server’s fifth tool, the audit_agent_path diagnostic, is described in the five-tool MCP setup.

Use one case at a time

Copy a case into a pull request, an evaluation note, or a documentation review. Check the description and schema against the task before you judge the result. A valid call, an invalid call, and a no-result response are different situations and need different next steps.

Complete one review

Selection: compare “find a guide about tool descriptions” with “define MCP”. Expect search_guides for the first and get_glossary_term for the second. Record what your agent actually selects; these are intended choices, not measured success rates.
Validation: compare the valid search input below with an empty query. Check that your server accepts the former and rejects the latter with actionable error text. A written schema alone is not enforcement.
Recovery: request an unknown guide slug, then use a returned valid slug or search first. Preserve the error and changed retry as the regression case.

Save the catalog version, input, expected outcome, observed output and unresolved gaps. For a selection ambiguity, inspect the neighbouring-tool rule; for closed vocabularies, inspect the enum rule. These are documented review rules; this page does not imply the separate checker package is released.

The catalog-only audit example demonstrates one deterministic schema defect. It does not test whether an agent will choose correctly or whether your tool works at runtime. If you want help reviewing a real path, workflow review services are optional.

The four reference cases

`search_guides`

Target intent: Find the relevant guide when the topic is known but the guide is not.
Nearest tool: Use get_guide after search_guides returns a slug. Use get_glossary_term for a short definition instead.

Valid input

{
  "query": "tool descriptions",
  "limit": 3
}

Invalid input

{
  "query": ""
}

Expected result shape

A JSON object with the original query, a positive matchCount for this example, and results that include the tool-descriptions slug and its Markdown URL.

Error and recovery: A blank query is a tool error. Use a short non-empty set of keywords. A zero-match response is not an error: change the words rather than repeating the same query.

`get_guide`

Target intent: Read one full guide when its URL slug is already known.
Nearest tool: Use search_guides when you do not know the slug. Do not use this to collect the whole library; llms-full.txt is the published whole-library document.

Valid input

{
  "slug": "tool-descriptions"
}

Invalid input

{
  "slug": "not-a-guide"
}

Expected result shape

Markdown text with the guide heading, dates, canonical URL, tags, and body.

Error and recovery: An unknown slug is a tool error that lists valid slugs. Select one of those, or search first; do not retry the same unknown slug.

`get_readiness_rubric`

Target intent: Fetch the published rubric as JSON when a check or the assessment instrument is needed.
Nearest tool: Use get_guide with agent-readiness-rubric when you need the prose explanation, not the JSON instrument.

Valid input

{}

Invalid input

{
  "check": "errors-carry-a-fixed-code"
}

Expected result shape

{
  "tracks": [
    { "id": "FIND", "checks": [{ "id": "…", "role": "core", "stopper": true }] }
  ]
}

Error and recovery: This tool takes no arguments. Fetch the complete instrument once, then inspect the needed check locally rather than calling it repeatedly.

`get_glossary_term`

Target intent: Get a concise definition and glossary anchor for one or more named terms.
Nearest tool: Use search_guides for a how-to question or guide discovery. This tool matches term names, not definition text.

Valid input

{
  "terms": ["AX", "llms.txt"]
}

Invalid input

{
  "terms": []
}

Expected result shape

{
  "requested": ["AX", "llms.txt"],
  "lookups": [{ "matched": true, "entry": { "term": "…", "url": "…#…" } }]
}

Error and recovery: An empty terms array is a tool error. A missing term is a normal lookup result with matched: false and suggestions; distinguish that from a misspelled term before retrying.

What this fixture checks

The stated task points to one tool rather than a plausible neighbour.
The schema accepts the valid input and rejects the invalid input.
The documented result shape tells the caller what to do next.
Error copy distinguishes a malformed request from a valid empty or missing result.
Each recovery step changes the next call instead of repeating the failed one.

Read Write tool descriptions an agent can act on for the writing method and Agent tool catalogues need a pruning strategy for the catalogue boundary.

Sources

The cases are written from the public Agent Experience MCP tool catalogue and checked against the current reference-tool code. The MCP tools specification describes tool names, descriptions, JSON Schema input contracts, annotations and tool execution errors, and notes that annotations are not a security boundary.

Before you copy a case into another system, check it against the live catalogue and its schema; the tools and the site’s content change over time.