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

Annotations carry readOnlyHint=false and destructiveHint=true, but the description adds genuinely valuable context beyond them: this tool only creates a pending proposal and 'nothing is recorded until confirm_proposal is called.' It also warns there is no UI affordance to click, so the agent must complete the flow itself. The pending-proposal disclosure meaningfully refines the conservative destructiveHint rather than contradicting it.

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 long but proportionate to its job: a 10-parameter two-phase workflow with exclusion rules and an omit/null protocol. Each block carries distinct operational information. There is one redundancy — the closing 'MCP note' repeats the pending-not-recorded point already made in the second sentence — so it is not perfectly lean.

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 tool with no output schema, the description covers the main operational essentials: the proposal/confirm two-step flow, the allowed transaction scope, the exclude cases, and the null-vs-omit semantics. The return value is named ('proposal id') and routed to the confirm tool. Remaining gaps are minor (e.g., no statement about what happens if confirm_proposal is not called, or error behavior).

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 100%, setting the baseline at 3, and the description earns an extra point by disambiguating the critical 'omit vs. null' rule: omit fields the user didn't mention so they keep current values; pass null only for explicit clears. It also clarifies when to use editsProposalId (revising a prior proposal like 'actually make it $60 not $50'), which the schema's property description does not convey.

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–object pair — 'Propose an edit to an existing past income or expense transaction' — defining both the action and the allowed resource. It further distinguishes the tool from siblings by explicitly excluding transfers and asset trades, which map to propose_transfer/propose_asset_trade, and from propose_transaction (new) and propose_delete_transaction (delete). An agent can select it correctly without opening schemas.

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 gives explicit when-to-use (edits to existing income/expense transactions), explicit when-not-to-use (transfers and asset trades → Transactions page), and the exact follow-up step (call confirm_proposal with the returned proposalId since there is no UI button). It also covers the revision scenario via editsProposalId. Nearly nothing is left to inference.

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