create_scheduled_transaction

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

No annotations are provided, so the description carries the full burden. It discloses several non-obvious behaviors: currency is 'Not updatable after creation — delete and recreate to change it', notes are visible in GnuCash's double-line register view, and quantity is required on commodity-mismatch legs. These are meaningful behavioral traits beyond what the schema reveals. Some gaps remain (e.g., no return-value description, no mention of validation errors), but the key constraints are surfaced.

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 thorough but somewhat verbose and repetitive. For instance, split details about quantity/commodity are explained both in the top-level description and echoed in the SplitInput $def. The notes section reads awkwardly ('what the payment is — visible in GnuCash's...'). Front-loading is good (purpose first), but it could be tightened without losing information.

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 9-parameter creation tool with zero schema coverage, the description delivers strong coverage: all params documented, frequency enums listed, currency's edge case articulated, splits format delegated to create_transaction. An output schema exists, partially relieving the need to describe return values. Minor gaps: no mention of duplicate detection, ID return, or error behavior — but the essential usage surface is complete for a complex 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?

Schema description coverage is 0%, so the description must fully compensate. It explains every parameter with format specs (YYYY-MM-DD, decimal strings), enumerates valid frequency values ('weekly', 'biweekly' (2w), 'monthly', 'bimonthly' (2mo), 'quarterly', 'yearly'), clarifies enabled default, and gives a worked example for splits. The currency guidance is especially rich — it explains the exact scenario requiring it and its immutability. This fully compensates for the empty 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+resource ('Create a recurring transaction template'), clearly distinguishing it from the sibling create_transaction (one-off) and create_transaction_from_scheduled (template instantiation). The recurring/template semantics are explicit and unambiguous.

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 states it references create_transaction for splits format ('Same format as create_transaction'), giving the agent a pointer to a sibling for details. It also explains when currency is needed (no leg in book currency, e.g., USD-to-USD card payment in CNY book). However, it doesn't explicitly state 'when NOT to use this vs create_transaction' or mention alternative template-editing tools like update_scheduled_transaction.

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