Última versão das tabelas nacionais (REST)

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds behavior beyond them: the returned DTO type (ControleAtualizacaoTabelasDTO), the 404-when-no-control error case, and the runtime prerequisite of the app being active. That is meaningful operational context an agent cannot infer from the 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?

Dense but well front-loaded: the server-side scope and the negative 'does not update' clause come first. Every clause carries information (endpoint, return type, error code, precondition), though the paragraph is packed tightly enough to be slightly hard to scan.

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?

With no output schema, the description compensates by naming the returned DTO and the 404 case, and it flags the app-running dependency. For a zero-parameter read endpoint, there is nothing an agent still needs in order to call it 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?

The tool takes zero parameters, so there is no parameter semantics to explain; schema coverage is 100% by definition. Baseline 4 applies with no gap introduced by the description.

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 and resource ('devolve ... a última versão das tabelas auxiliares nacionais') and identifies the exact endpoint. It explicitly scopes itself as the server-side view ('LADO SERVIDOR do PJe-Calc local'), which separates it from the local/client variants like tabelas_status and rest_tabelas_versao.

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?

Explicitly states what the tool does NOT do ('NÃO atualiza as tabelas deste PJe-Calc') and names the alternative for that job ('para isso use tabelas_atualizar'). It also gives a precondition ('Requer o app em execução'), so an agent knows both when to pick it and when not to.

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