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

Annotations already cover safety (readOnly, idempotent, non-destructive), and the description goes well beyond them: it discloses the detection methodology (time-weighted median so flash promos only count for the hours they lasted), the minimum tracking window, and the semantics of discount.certainty = 'verified' vs 'none'. That last point is decisive operational context an agent would otherwise get wrong.

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 core definition is front-loaded and nothing in the first two sentences is filler. The certainty paragraph is long and slightly repetitive ('none' significa que não há desconto que se possa afirmar'), but it earns its place because that field drives how results must be reported.

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 one-parameter, no-output-schema tool the description is nearly sufficient — it explains the key returned field (discount.certainty) rather than leaving return values opaque, which is exactly what is needed when no output schema exists. Remaining gaps are the undocumented 'limite' parameter and result ordering/pagination, which are minor but real.

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 0%, so the single parameter 'limite' (default 10, max 50) is undocumented in the schema and the description never mentions it at all. The agent can guess it caps the number of results, but nothing confirms that, states ordering, or explains behaviour when the cap is hit — the description fails to compensate for the coverage gap.

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 opening sentence gives a precise operational definition: products whose price dropped at least 10% against a time-weighted 14-day median, or that hit an all-time low. That is far more specific than a restated title. It never names the siblings buscar_promocoes or historico_de_preco, so the agent must infer the boundary itself, though the line 'O preço "de" que o vendedor escreve no anúncio não sustenta desconto nenhum aqui' implicitly marks it off from promo listings.

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 prerequisite is stated clearly ('Exige 7 dias de acompanhamento'), and the closing sentence says how to report results responsibly ('Citar o percentual sem o certainty ao lado desinforma o leitor'). But there is no explicit when-to-use / when-not-to-use versus buscar_promocoes or historico_de_preco, so selection between the three is left to inference.

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