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

Annotations already indicate readOnlyHint=false, so the agent knows it's a mutation. The description adds context by specifying the types of entries it creates and the structure of the data payload. It doesn't discuss potential side effects, reversibility, or error behavior, but given the annotations cover the basic mutation nature, the description adds sufficient value beyond the schema.

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 dense and efficient; every sentence provides actionable information. It opens with the purpose, quickly lists what it's not, then dives into the data structure, and closes with a pointer for the account code. No wasted words, and the structure logically flows from purpose to usage to details.

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?

The tool has no output schema, so the description should cover return values, but it doesn't. However, it thoroughly explains the input structure, clarifies the distinction from related tools, and references how to obtain the required account code. The only significant gap is the unexplained optional 'account' parameter and the lack of return value details. With no output schema, a note on what the tool returns would improve completeness, but the description is still quite comprehensive for a creation tool.

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 schema provides no descriptions (coverage 0%), so the description must compensate. It thoroughly documents the required 'data' parameter, breaking down the JSON structure into cabecalho and detalhes blocks with field-level detail, including date format. However, it does not explain the optional 'account' parameter, leaving a gap. Given the core parameter is well-explained, this is a significant but not complete compensation.

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 clearly states the tool creates a specific type of checking account entry (LANÇAMENTO avulso) and lists the types it supports (tarifa, rendimento, aplicação, resgate, ajuste). It also explicitly distinguishes it from check/payable tools (omie_lancar) and transfers (omie_transfer_between_accounts), making the purpose unambiguous and differentiating it from siblings.

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 explicitly states what this tool is NOT (conta a pagar/receber and transferência) and names the correct alternatives for those cases (omie_lancar and omie_transfer_between_accounts). It also provides guidance on obtaining the required account code (omie_list_checking_accounts), giving the agent clear direction on when and how to use the tool.

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