update_transactions

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

With no annotations provided, the description carries the full behavioral disclosure burden, and it does well: it explains the empty-cell-UNCHANGED semantics, the abort vs skip on_error behavior, the reconciled-splits rejection rule with force, and that results return a TSV keyed by input guids. It's missing explicit mutation/reversibility notes but covers the critical traps thoroughly.

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 information-dense but appropriately organized with labeled sections (INPUT, clearing note, error handling, force, returns, performance tip). While long, every sentence adds operational value. The TSV format block is necessary given the complex input. Slightly verbose but well-structured.

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?

This is a complex bulk-edit tool with a TSV-format input, error modes, reconciliation edge cases, and an output schema mentioned. The description covers the input format, error behavior, reconciliation constraint, output keying, and performance alternative. It's missing explicit prerequisite states (single open book requirement is stated), but is otherwise remarkably complete for the complexity.

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 must fully explain all 3 parameters. It does: updates gets deep TSV format documentation with a header spec and example rows, on_error gets both 'abort' and 'skip' behaviors, and force gets the reconciled-splits context. This compensates strongly for the zero schema coverage.

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 verb+resource+scope: 'Update MANY transactions with per-row values (bulk edit)'. It explicitly distinguishes from the sibling update_transaction (single-transaction) by contrasting semantics, making the purpose unambiguous and well-differentiated.

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 provides explicit when-to-use guidance: it names the cheaper alternative (update_transaction with guid list for same-value batches), the single-transaction alternative for clearing fields, and replace_splits for splits/memos. It also explains when force=true is needed for reconciled splits. This is model-level guidance.

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