delete_transaction

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

Annotations only declare destructive/idempotent/not-read-only; the description goes far beyond them by disclosing no undo through this server, the refusal categories, the shared add_transaction write gating (MONEYLOVER_ALLOW_WRITE, wallet allowlist, hourly limit), the date window, and the meaning of an UNCERTAIN failure with the recommended recovery check.

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 action and the precondition, then moves through alternative, refusals, gating and failure semantics in a tight sequence. Long but every sentence carries distinct operational information; nothing is redundant with the schema or annotations.

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 destructive, gated, non-undoable mutation with an output schema already describing returns, the description covers preconditions, refusals, environment gating and ambiguous-failure handling. Nothing an agent needs before calling it is missing.

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 coverage is 100% so the schema already documents id, date and wallet, but the description adds that those values come from list_transactions and that dry_run returns the entry without deleting it, which is slightly richer than the schema's own wording. Baseline 3 raised to 4 for that added meaning.

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 and resource ('Permanently delete one existing transaction') and immediately distinguishes itself from update_transaction ('To fix a wrong detail...') and add_transaction. An agent can tell exactly what this call does without opening the schema.

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?

Explicit when-to-use ('only when the user asked for the removal in their own words'), the prerequisite identification flow (list_transactions supplies id/wallet/date, then confirm), the dry-run escape hatch, and the alternative tool for corrections. It also states the when-not case: linked transfers, debts, loans and repayments are refused and must be handled in the app.

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