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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely useful behavioral rules beyond that: a stale or partial curve never triggers a decision, and only HT supply prices are compared against the locked HT supply price. These are real decision-guardrails that an agent could not infer from the schema or annotations.

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 purpose and routing are front-loaded in a single dense sentence, with no filler or repetition. It is information-packed but readable; the semicolon-chained clauses are justified by the amount of routing and guardrail information conveyed.

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?

An output schema exists, so return values need not be described, and the sibling routing and decision guardrails are present. However, for a 12-parameter tool with 8% schema coverage and a complex pricing domain, the near-total absence of parameter semantics leaves the definition short of what an agent needs to populate the inputs 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 description coverage is only 8% across 12 parameters, so the description carries the burden and largely fails to. It hints at a few inputs (préavis, courbe EEX, prix verrouillé HT fourniture, segment C5/C4) but leaves structure, auto_renewal, pricing_type, budget_eur_mwh, ceiling_eur_mwh, evaluation_date, locked_fraction and annual_consumption_mwh undocumented in both schema and prose.

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 gives a specific verb+resource ('Conseille un renouvellement B2B') and, more importantly, explains the composition of the advice (notice period + fresh EEX curve via eex_connector + C5 catalog via pro_catalog). It explicitly differentiates from the sibling analyze_renewal_terms and notes that C4 prices are excluded. The only weakness is that the core action verb remains somewhat generic, but the routing context makes it distinct from siblings.

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?

It names the alternative (analyze_renewal_terms) and the precise condition that selects it: 'pour les seules dates contractuelles sans marché'. It also sets an exclusion boundary ('Les prix C4 restent sur devis'), telling the agent this tool won't price C4. It stops short of stating when NOT to use renewal_advisor itself, so it is clear context rather than a full when/when-not matrix.

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