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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety is covered structurally. The description usefully adds that suggestions are non-mutating, the date format, and the offset pagination mechanism. But it is silent on the confirm, dryRun, set, items, and lines parameters, which look like they could apply categorization — a significant behavior the agent needs explained.

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 three modes, then the filters, then date/pagination format, then the full-review shortcut, then the action enum. Every sentence carries information and there is no filler. It is slightly packed and the closing enum sentence could have been merged, but structure is sound.

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?

With 27 parameters, nested objects, no output schema, and near-zero schema description coverage, this definition is far from sufficient. An agent reading it cannot know what confirm, dryRun, set, items, lines, candidate, or suggestion do, and there is no guidance on what list/review/suggest return. It describes the read/search surface well but leaves most of the actual input surface opaque.

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 only 7% across 27 parameters, so the description must carry weight. It does document the filter set (account, category, payee, description, amount, reference, date, state), the YYYY-MM-DD date format, the offset pagination, and the action enum values. It leaves the nested set/items/lines structures, match, candidate, suggestion(s), confirm, dryRun, minAmount/maxAmount, direction, and by completely unexplained, so compensation is partial.

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?

Opens with an explicit verb-plus-resource: search the active company's transactions, summarize bookkeeping activity, or request categorization suggestions. The three action modes (list, review, suggest) are named at the end, so an agent can map intent to mode. It does not explicitly say how it differs from siblings like manage_changes or manage_journal_entries, keeping it at 4 rather than 5.

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 one concrete usage rule — to review the whole company, use state=all without filters — and states that suggestions do not apply changes. However, it never explains which of list/review/suggest to pick for a given goal, nor when to prefer this over manage_changes or manage_reports. Usage is implied by the action enum rather than spelled out.

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