Detect Recurring Charges

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

Annotations already establish read-only, idempotent, non-destructive behavior, so the description's job is to add beyond that — and it does: data-source differences vs. scheduled tools, false negatives on variable amounts, group splitting from payee variants, and an annualized cost estimate. These accuracy caveats are exactly the behavioral context an agent needs before trusting the output.

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?

Very compact and front-loaded: capability, then data-source scope, then limitations, then the suggested follow-up check. Every clause carries information. The telegraphic, semicolon-chained style borders on fragmented ('Payee variants split groups'), which slightly hurts readability against the otherwise high information density.

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?

An output schema exists, so return values need no explanation, and annotations cover the safety profile. The description supplies the remaining decision-critical context: cadence coverage, estimation of annual cost, and known detection gaps. The only real omission is the role of budgetId and whether results are budget-scoped or all-budgets, which leaves a small gap for a 3-parameter 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 coverage is 67%, so the schema already documents monthsBack (with its default and the rationale for longer windows) and minOccurrences (default 3). The description adds nothing about any parameter, and budgetId remains undocumented in both places. The cadence list implies why a longer monthsBack matters, but that is inference rather than stated semantics, so baseline 3.

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 ('Find recurring outflows') plus the detection method ('by payee/exact amount') and the cadence set it recognizes. It also differentiates itself from the scheduled-transaction siblings by noting it 'Includes auto-imports absent from scheduled tools.' An agent can identify the tool and its distinct niche 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?

Gives a concrete next step ('check search_payees before concluding cancellation') and implicitly routes away from list_scheduled_transactions by naming what that family misses. It also states a disqualifying condition ('misses variable amounts'), which helps an agent pick a different approach. It stops short of naming an explicit alternative for the variable-amount case, so not a full 5.

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