Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly=true, idempotent=true, destructive=false, so safety is covered. The description adds genuinely non-obvious context: a 12-month shutdown window with three emailed notices, a migration mapping URL, and a PECR default that excludes sole traders and ordinary partnerships unless a toggle changes. The legal-basis sentence is somewhat tangential to invocation behavior, which keeps this below a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The deprecation warning and the replacement instruction are front-loaded in the first sentence, which is the right ordering. The final sentence mixes compliance framing (UK GDPR Article 6(1)(f)) with audience-scope behavior, making the description somewhat of a grab bag, though each element is actionable rather than filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a deprecated, zero-parameter tool with an output schema, the agent needs to know: what it does, that it is going away, when, and what to use instead — all present. The migration link closes the remaining gap for callers that must translate arguments.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Zero parameters, so the baseline is 4; the schema itself explains that the old argument shape is preserved and adapted during the deprecation window. The description adds no parameter detail, but none is needed for a no-argument call.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('lists the filter categories') and immediately frames the tool as deprecated, which is the single most important fact about it. It also names the replacement, so an agent can distinguish it from list_filters without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit redirect: 'Use list_filters instead,' and describes what the replacement returns (field names, types, operators, value counts). The migration URL provides a concrete path for existing callers, leaving nothing to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.