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

Annotations are minimal (readOnlyHint=false, idempotentHint=false, destructiveHint=false) and consistent with the description, so there is no contradiction. The description adds substantial behavioral context beyond those hints: the 100-item cap, single-call execution with no interactive confirmation, the mandatory uniqueness/dedupe constraint, and the redirect behavior triggered by attachment fingerprints on canonical imports.

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?

Purpose and scope are front-loaded, and every clause earns its place: batch limit, alternative tool, dedupe rule, exclusion case with error code, naming preference, and execution model. It is dense but contains no filler or repetition.

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 batch tool with no output schema and 0% schema coverage, the description covers the cap, dedupe, exclusions, and execution model — most of what an agent needs to call it. The notable gaps are the unexplained idempotency_key parameter and the lack of any statement about return values or partial-failure behavior for individual rows.

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%, so the description carries the full burden, and it does add real meaning: the uniqueness constraint on description+amount+date+account, the preference for account/category NAMES, and the 100-item array cap. However, it leaves idempotency_key and several item fields (times, periodicity, recurring, observation) without any semantic guidance, so the compensation is strong but incomplete.

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 precise verb-resource-scope statement: 'Cria VÁRIAS transações em lote (máx. 100) a partir de uma lista de objetos' — batch-creating transactions from an object list with a hard cap. It explicitly differentiates from the sibling organizze_create_transaction by instructing the agent to use this instead of repeated single calls, so there is no ambiguity about which sibling to select.

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?

Usage guidance is explicit and bidirectional: use it instead of repeated create_transaction, and do NOT use it for CSV/OFX canonical-snapshot imports, naming the exact redirection path (plan_tabular_import/apply_tabular_import with error_code redirect_to_tabular) and the MCP fallback behavior. It also states a payload precondition (dedupe before sending). No inference is required.

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