propor_dar_baixa

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

Annotations declare readOnlyHint=false but destructiveHint=false and idempotentHint=true; the description reconciles this by explaining the tool only prepares and that the returned text (with saldo antes e depois) is meant to be shown to the client, which is meaningful context beyond the hints. It does not cover what happens to the pending proposal (expiry, one-at-a-time limits) or error behaviour.

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?

Two short sentences, no filler, with the critical non-obvious fact (it does not actually settle) placed immediately after the purpose statement. Front-loading is correct and the negation is emphasised so it cannot be skimmed past.

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 preparatory, non-destructive step in a two-call workflow with no output schema, the description supplies the essential contract: what it returns (client-facing text plus before/after balance) and that confirmar_acao must follow. Gaps remain around the second-step handoff (what to pass to confirmar_acao) and the two undocumented identifiers.

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 60% and the description says nothing about any of the five parameters. id_parcela and id_conta_financeira are documented nowhere, and nothing explains whether valor may be partial or how data_pagamento defaults interact with the balances shown; only the vague parenthetical "paga/recebida" hints at valor.

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 ("Prepara a baixa de uma parcela") plus the clarifying gloss "registrar que foi paga/recebida", and immediately distinguishes itself from the actual settlement by naming confirmar_acao as the follow-up. An agent can tell this apart from consultar_parcela and confirmar_acao without opening any schema.

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 says "NAO da baixa: exige confirmar_acao depois", which is a clear when-to-use / when-not-to-use rule tied to a named sibling. It lacks only an explicit statement of the converse case (e.g. when to skip the proposal and call confirmar_acao directly), but the sequencing constraint is unambiguous.

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