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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false, covering the safety profile. The description adds real value beyond that: the 'Cache 1h' disclosure warns the agent that data may be up to an hour stale, plus explicit return semantics. No contradiction with 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?

Three short sentences, each earning its place: front-loaded purpose, output plus use case, and cache disclosure. No filler, no redundancy, and the key scoping constraint (órgão + ano) leads the text.

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?

Everything an agent needs to safely invoke this tool is present: all four parameters documented in the schema, the output schema covering the return shape, annotations carrying the full safety profile, and the description adding aggregation semantics, use case, endpoint reference, and cache-freshness caveat. There is no meaningful gap.

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 100% — ano, codigo_orgao, pagina, and tamanho_pagina all have descriptions with defaults and bounds (max 500), so the baseline is 3. The description marginally reinforces that codigo_orgao and ano are the aggregation keys ('de um órgão num ano') but adds no new format, constraint, or syntax beyond the schema.

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 opens with a specific verb+resource — 'Resumo agregado do PGC de um órgão num ano (totais por categoria)' — then specifies the output ('contagens e valores totais por categoria/grupo') and names the underlying Dados Abertos endpoint. The aggregation framing ('agregado', 'totais por categoria') inherently distinguishes it from list-style siblings like compras_pgc_listar and compras_pgc_listar_csv without needing to open their schemas.

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?

'útil para diagnóstico rápido do volume planejado pelo órgão' gives a clear, concrete selection context: quick volume diagnosis for an agency. However, it does not name alternatives or state when to prefer the list/CSV/catálogo siblings when row-level detail is needed, so exclusions remain implicit.

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