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

Annotations disclose readOnlyHint=false, destructiveHint=true, idempotentHint=false, openWorldHint=true. The description adds valuable non-obvious behavioral context: it's a prep step (doesn't execute), uses only the connected Gover account and its API permissions, never include credentials as arguments, use gover_ler_resultado for large outputs, and payment data goes only to the Gover portal. This goes beyond annotations. However, it doesn't address the destructive nature or confirmation semantics further.

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?

Front-loads the core purpose, then packs multiple crucial operational constraints efficiently. Every sentence adds value except possibly the payment data note which is slightly tangential but still useful. Not overly verbose, though a bit dense.

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 complex prep tool with no output schema and 15 undocumented parameters, the description covers the critical workflow (prepare, confirm, read results), security constraints, and data handling. It lacks parameter-level guidance but compensates by establishing a clear multi-step interaction model. Complete enough for an agent to use correctly in context.

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% with 15 parameters (including nested assentos array). The description only states that fields follow the API contract, adding no field-level meaning or format details. With high parameter count and zero schema descriptions, this is a significant gap, but the description's indirect guidance ('Os campos seguem o contrato da API') and the pointer to gover_ler_resultado provide minimal compensation, landing at baseline 3.

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?

Specific verb+resource in Portuguese ('Marcar assentos para passageiros') that names exactly the operation. Crucially, it distinguishes itself from siblings by clarifying it is a preparation step ('Prepara a acao, sem executa-la') that must precede gover_confirmar_operacao, differentiating it from execution tools like executar_consulta or confirmar_operacao.

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?

Explicit when-to-use guidance: show parameters to user, then only after explicit confirmation use gover_confirmar_operacao. Also directs to gover_ler_resultado for extensive results, and to the Gover portal for new payment data. Clear workflow context, though it doesn't explicitly state when NOT to use versus siblings like consultar_mapa_assentos or iniciar_selecao_assentos.

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