# Can an MCP tool description change break an agent?

> A tool can accept the same arguments while a rewritten description changes when an agent selects it. Review prose changes alongside schema changes.

**Changing an MCP tool description can change tool selection without changing
the input schema.** The request may still validate, but an agent can choose a
different tool or use it for a different purpose. That makes descriptions part
of the model-visible contract.

This is a reason to review prose and run evaluations, not a claim that every
wording edit breaks every model.

## A schema-compatible change worth reviewing

Before:

```text
Search the issue tracker.
```

After:

```text
Find tickets across every connected workspace.
```

The tool remains named `search` and its arguments stay identical. Its stated
scope changes from one tracker to every connected workspace. MCP Inspect emits
`tool.description.changed` at `POTENTIALLY_BREAKING` for this example.
[See the actual word redline and engine output](/examples#description-rewrite).

Description classification uses a deterministic prose heuristic. The finding
is reproducible from the two captures; it does not measure selection probability
or predict a particular model's response. Small edits can be classified as
`DOCUMENTATION`, and even then your own evaluations remain useful.

## Which model-visible fields matter?

| Field                                      | Review question                                                             |
| ------------------------------------------ | --------------------------------------------------------------------------- |
| Tool description and title                 | Has the stated purpose, scope or preferred use changed?                     |
| Input property descriptions                | Will a model supply a different meaning or unit for the same property?      |
| Server instructions                        | Does guidance change how the server's tools should be combined or selected? |
| Tool annotations                           | Did read-only, destructive or idempotent hints change?                      |
| Prompt descriptions and declared arguments | Did a caller's declared interface or guidance change?                       |

Tool annotations are untrusted hints, not proof of safety. A withdrawn hint can
still change host or agent behavior. Contract review must not substitute for
authorization or approval of the tool's actual effects. The
[MCP tools specification](https://modelcontextprotocol.io/specification/2026-07-28/server/tools)
defines these tool fields; the [rule reference](/docs/rules) documents how MCP
Inspect classifies changes that it captures. A snapshot captures prompt
declarations, not every dynamically rendered prompt result.

## How to evaluate a description rewrite

1. Keep the before and after contracts and identify the intended meaning change.
2. Collect representative tasks, including ambiguous cases involving neighboring
   tools and cases where no tool should be called.
3. Run both versions with the same model, host settings and available tool set.
   Record the selected tool, argument shape and task result. Repeat probabilistic
   runs rather than treating one result as conclusive.
4. Review selection changes against the intended behavior. Keep handler and
   permission tests separate from the selection evaluation.
5. Ship the wording with a reviewed contract change and retain its baseline.

No benchmark score or model behavior is inferred from a diff alone. MCP Inspect
does not run these evaluations for you.

## Track prose changes in your own server

[Capture a public HTTP MCP endpoint](https://app.mcprobe.dev/signup) with email
and password, then capture again after a wording change. Open Changes to review
the old and new values beside schema findings. No telemetry, API key or GitHub
connection is needed for this hosted capture workflow.

For approved-preview CLI/CI workflows, `fail_on: POTENTIALLY_BREAKING` includes
substantial prose and annotation findings in the failure threshold. The default
`BREAKING` threshold still displays those findings but does not fail solely for
them. [Read the severity settings](/docs/severities).

Continue with [input versus output compatibility](/docs/mcp-schema-compatibility)
or [scheduled monitoring](/docs/monitor-mcp-server-changes).