Update Transaction Rule

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

Goes well beyond the annotations: explains that Monarch replaces the whole rule on update, so the tool read-modify-writes the rule to preserve untouchable settings (owners, goals, splits), and that apply_to_existing_transactions is 'hard to undo'. It also documents the leave-out-keeps-current and empty-value-clears semantics, which annotations alone cannot convey.

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?

Front-loads the core action and rule_id sourcing, then layers the semantic rules and the destructive caveat. Every sentence earns its place, though the multi-paragraph block is dense and the trailing whitespace/newline is untidy.

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?

Covers the mutation risk, the read-modify-write preservation behavior, clearing syntax, and the validity constraint that a rule must keep at least one action plus a merchant/statement/amount criterion. Output schema exists so return values need not be described. Minor gaps remain around the id-list parameters.

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 0% top-level schema coverage, the description carries much of the burden and does: it defines clear syntax per field ([] for lists, "" for set_category_id/set_merchant_name/review_status, clear_amount_criteria), states list replacement semantics, and defers nested shapes to create_transaction_rule. A few pass-through fields (account_ids, add_tag_ids, hide_from_reports) still lack explanation, so not a full 5.

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+resource ('Edit a rule') and immediately notes the optional side effect ('optionally run it on existing transactions'). It also points to the sibling get_transaction_rules as the source of rule_id, which distinguishes it from create/delete variants. Sibling differentiation is present but not spelled out against create_transaction_rule or delete_transaction_rule by name.

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?

Gives an explicit prerequisite ('Get rule_id from get_transaction_rules') and explains when the dangerous flag matters ('apply_to_existing_transactions=True runs the rule on matching past transactions, even with no other changes'). No explicit when-not guidance, but the undo warning effectively marks the risky path.

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