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

Annotations already cover safety (readOnly, idempotent, non-destructive), so the description adds value by disclosing return-field composition (nSaldoAtual, nSaldoAnterior, nSaldoDisponivel, nSaldoConciliado, nSaldoProvisorio) and the default-today period behavior. It does not disclose pagination limits on the movement list or maximum period length, which would matter for reconciliation. Still, well above what 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?

Front-loads the core capability, then differentiates from the sibling, then parameter details. Dense but each sentence carries information. The all-caps Portuguese emphasis and parenthetical tool name are slightly noisy but serve scannability.

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 an 8-param, no-annotation-gap read tool whose safety profile is covered elsewhere, the description provides identity, defaults, return field composition, and sibling routing. Missing coverage of account and apenas_nao_conciliados and any pagination guidance keeps it from being complete.

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 coverage is 0%, so the description must compensate: it explains conta (name OR id), nCodCC (Omie id), cCodCCInt (integration key), the date format (AAAA-MM-DD or DD/MM/AAAA), and the incluir_movimentos toggle's effect. This meaningfully covers 5 of 8 params. It does not mention account or apenas_nao_conciliados, leaving two undocumented.

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+resource ('EXTRATO BANCÁRIO e SALDO ATUAL de uma conta corrente') and explicitly differentiates from siblings: contrasts with omie_list_checking_accounts (saldo_inicial at a fixed date vs. real current balance) and clarifies that with incluir_movimentos:true it acts as the movement lister, related to omie_list_checking_account_entries. An agent can select between account-related siblings without opening 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?

Explicit when-to-use branching: default returns balances, set incluir_movimentos:true to get the statement entries for reconciliation. Names the alternative (omie_list_checking_accounts) and the exact condition that selects it (fixed saldo_inicial vs. real current balance). Nothing 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.