atualizar_dados_pr

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

Annotations already indicate read-only, idempotent, non-destructive behavior, and the description adds meaningful context: it ignores local cache, returns a sample with origin and real retrieval time, does not alter TCE-PR, and does not guarantee new data. This clearly sets expectations beyond what the annotations alone provide.

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 short, front-loaded with the core behavior, and uses each sentence for distinct useful information: cache bypass, parameter hint, return contents, safety caveat, and scope exclusion. There is no filler or redundancy.

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 output schema exists and the annotation set already covers safety and read-only semantics, the description provides adequate context: cache behavior, return sample/origin/time, non-guarantee of freshness, and what is excluded. The main missing piece is a direct comparison with sibling consultar_* tools to fully guide routing, but this is not critical for a simple refresh operation.

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 description must compensate. It helps by saying that "ano" should be provided for licitacoes/acordaos, which clarifies the main optional parameter. However, it does not explain what happens when "ano" is null or for other bases, and it does not add meaningful semantics for the "base" choices beyond the schema enum.

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 states a specific action: "Busca novamente catálogo e CSV tradicional, ignorando o cache local." This identifies the resource, the operation, and a distinguishing behavior. However, the name "atualizar_dados_pr" could imply mutation, and "catálogo e CSV tradicional" remain somewhat domain-specific without explaining what those terms mean.

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 description gives parameter-level guidance with "Informe ano para licitacoes/acordaos" and implies that PIT, Mural, pages, and documents do not need this tool because they are already fetched each query. It does not explicitly name sibling alternatives or state the exact condition for choosing this tool over them, so usage guidance is present but mostly implicit.

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