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

Annotations only declare readOnlyHint=true. The description goes far beyond that by disclosing that the tool is deprecated, unsupported, and would be expensive if force-reimplemented. It explains the behavioral trap (silent degradation vs. cost) and the decision to mark it unsupported. This adds significant context not available from annotations, with no contradiction.

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 description is a tight two-sentence paragraph. The critical deprecation notice and replacement are front-loaded in the first sentence. The second sentence explains the historical behavior and reasoning in a compact way. Every word earns its place; no filler or redundancy. Structure is optimal for a deprecated tool.

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 tool, the description is complete: it tells the agent it should not be used, provides the exact alternative sequence, explains why it is unsupported, and states what it used to do. The presence of an output schema is irrelevant because the tool is not meant to be called. There is nothing an agent needs to correctly decide to avoid it.

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?

Schema coverage for the only parameter (postcode) is 0%, and the description does not explicitly describe the parameter. The phrase 'for every certificate at a postcode' implicitly ties the postcode parameter to the tool's purpose, but provides no format, constraints, or examples. Given the low coverage, the description should compensate more, though the deprecation status reduces the practical need. Still, the semantics are not well specified.

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?

The description explicitly opens with 'DEPRECATED — use property_epc_summaries then epc_certificate', clearly identifying the tool's status and directing to the replacement. It then states the original purpose (returned score, floor_area, property_type, habitable_rooms, inspection_date for each certificate at a postcode), which distinguishes it from siblings. This is a clear, specific statement of what the tool does (or did) and how it relates to alternatives.

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?

The description gives explicit when-to-use guidance: it says do not use it, and names the exact sequence to use instead. It further explains the reasoning (the EPC service no longer exposes those fields in a search) and the design choice (unsupported rather than silently degraded or expensive). This is exemplary usage guidance, leaving no ambiguity about whether or when to invoke this tool.

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