# MCP tool-description test cases

The separate `audit_agent_path` diagnostic is outside this reference-tool fixture. See the [complete five-tool MCP setup](https://agentexperience.tech/connect/).

A copyable fixture for reviewing whether a tool description makes its purpose, nearest neighbour, inputs, result shape, and recovery path clear. These examples are checked against the four compatible reference tools in the public Agent Experience MCP server at `https://agentexperience.tech/api/mcp`.

Use one case at a time in a pull request, evaluation note, or documentation review. This fixture is not a benchmark, certification, score, or prediction of agent behaviour.

## Case 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**

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

**Invalid input**

```json
{"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.

## Case 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**

```json
{"slug":"tool-descriptions"}
```

**Invalid input**

```json
{"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.

## Case 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**

```json
{}
```

**Invalid input**

```json
{"criterion":"DIS-01"}
```

**Expected result shape**

```json
{"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.

## Case 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**

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

**Invalid input**

```json
{"terms":[]}
```

**Expected result shape**

```json
{"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.

## Review 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.

## 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: <https://modelcontextprotocol.io/specification/2025-11-25/server/tools> describes tool names, descriptions, JSON Schema input contracts, annotations, and tool execution errors.

Tool implementations, clients, model versions, and site content can change. Re-check the live catalog and 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.