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

Annotations only declare readOnlyHint=true, but the description adds critical behavior: returns null only when no certificate is lodged, and raises an error if the service is unreachable, explicitly warning not to treat errors as absence of a certificate. This is beyond the annotation and essential for correct interpretation.

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 focused and efficiently organized: purpose first, then usage context, then parameter explanation, then behavior. Every sentence adds value without redundancy or fluff, making it easy to parse quickly.

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?

Given the tool has a single straightforward parameter and an output schema (which the description complements by explaining null vs error), the description fully covers what an agent needs to know to call it correctly and interpret results. No gaps remain.

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?

Despite 0% schema description coverage, the description fully explains the parameter: lmk_key is a compatibility alias for the certificate number, and it tells the agent that the value is available in every property_epc_summaries row. This compensates entirely for the schema's lack of description.

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 clearly states a specific verb ('Fetch') and resource ('a single EPC certificate by its GOV.UK certificate number'). It also distinguishes itself from siblings like property_epc by explicitly noting the lookup avoids address matching and postcode re-fetch, making its niche obvious.

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?

Provides explicit guidance: use after property_epc_summaries, faster than property_epc(postcode, address), and warns that property_epc_search is deprecated and raises. This gives an agent clear when-to-use and when-not-to-use instructions with alternatives named.

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