Resource
MCP tool-description test cases
A copyable fixture for reviewing whether a tool description makes its purpose, nearest neighbour, inputs, result shape, and recovery path clear. The examples are checked against this site’s four compatible reference MCP tools.
The separate audit_agent_path diagnostic is not covered by this reference-tool fixture. See the complete 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.
This is a fixture for interface review, not a benchmark, certification, score, or prediction of agent behaviour. It uses only public site content and current tool contracts.
The four reference cases
01
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.
02
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.
03
get_readiness_rubric
- Target intent
- Fetch the published rubric as JSON when a criterion or scoring 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
{
"criterion": "DIS-01"
}Expected result shape
{
"dimensions": [
{ "weight": 20, "criteria": [{ "id": "DIS-01" }] }
]
}Error and recovery: This tool takes no arguments. Fetch the complete instrument once, then inspect the needed criterion locally rather than calling it repeatedly.
04
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 Tool descriptions are product surfaces for the writing method and An agent’s tool catalog needs a pruning strategy for the catalog boundary.
Source and limits
The cases are an original editorial fixture derived from the public Agent Experience MCP tool catalog, checked against the current reference-tool implementation. The MCP tools specification describes tool names, descriptions, JSON Schema input contracts, annotations, and tool execution errors; it also notes that annotations are not a security boundary.
Tool implementations, clients, model versions, and site content can change. Re-check the live catalog and its schema before copying a case into another system. These examples describe this server only; they do not establish how a model, client, search engine, or other tool server will perform.