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

Annotations are minimal (all flags false), so the description carries the burden — and it delivers: validation failure mode with 400 on insufficient balance/limit, conditional validation gated on isPaid and scheduledDate, side effects (best-effort recalculation of projections/insights, budget push alert), and per-parameter behavioral branching (installments generating future occurrences, Equity create/update with a default fallback, goal progress on TRANSFER). Nothing contradicts 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?

A single dense paragraph of roughly 170 words with zero filler — every clause carries semantic weight, and the core action plus required-field note come first. However, the density hurts scannability: the investment/Equity portion stacks multiple conditionals into one sentence, and bullet structure would make the conditional behaviors easier for an agent to parse.

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 20-parameter tool with an output schema present, the description covers the cross-cutting behaviors that the flat schema cannot convey: validation gates, scheduling semantics, installments, Equity creation/update with default fallback, goal interaction, and post-creation side effects. Only minor edge cases are uncovered (e.g., both accountId and cardId supplied together), and those are marginal given the rich schema and output schema.

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?

With 95% schema coverage, the baseline is 3 and the schema already documents most parameters. The description adds genuinely cross-parameter semantics the flat schema cannot express: the accountId XOR cardId requirement summarized, the isPaid × scheduledDate gate that toggles fund validation, the amount/installments relationship, and the default 'Investimentos Gerais' Equity fallback that appears nowhere in the schema.

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 opens with a specific verb and resource — 'Cria uma transação (EXPENSE/INCOME/TRANSFER)' — and immediately delimits scope: a single transaction of three possible types. It semantically separates from the confirm_* siblings (which confirm rather than create) and from create_recurring_transaction (which creates a recurring pattern rather than a single transaction with installments).

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 names alternatives with conditions: 'para permitir saldo negativo use confirm_new_transaction' and the scheduling flow that later routes to confirm_pending_transaction. However, it gives no guidance about when to prefer create_recurring_transaction — the closest sibling, also a transaction-creating tool — nor about update/delete fallbacks.

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