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

Adds substantial behavior beyond the readOnly and openWorld annotations: exact cross-referencing method, 200m and 10-year matching window, output structure, known limitations, and cost in credits. This gives the agent a clear picture of how results are produced and their caveats.

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 front-loaded with purpose and method, then uses labeled blocks for required/optional, output shape, limitations, and cost. It is slightly long but each element—method detail, output shape, cost—is necessary given no output schema and the analytical complexity.

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 no output schema, the description supplies the output shape, methodology, limitations, and cost, and it states the required input constraint. It covers what an agent needs to invoke and interpret the tool correctly.

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 descriptions cover all three parameters at 100%, but the description adds crucial semantics: one of code_postal or commune is required even though the schema marks no required fields, and department-level analysis is too broad. It also clarifies type_local's role and default.

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 'Analyze' and resource 'price premium or discount of energy performance ratings in a market', and the method paragraph distinguishes it from pure DPE distribution tools. However, it does not explicitly differentiate from the closely named sibling analyze_dpe_price_and_thermal_risk, leaving a possible overlap unaddressed.

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?

Specifies required location inputs (code_postal or commune) and optional type_local, and explains that department-level analysis is too broad for meaningful comparison. It does not name alternative tools or say when to prefer this over analyze_dpe_distribution or analyze_dpe_price_and_thermal_risk.

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