Analysis — Unassigned transfers

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

Annotations already cover readOnly/non-destructive/closed-world, but the description adds a genuinely useful behavioral detail beyond them: the request cost ('two requests, plus one per month when group_ids is given'). It does not discuss permissions or failure modes, but the cost disclosure is real added value.

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-loaded with [READ] and the core purpose, and the parameter guidance is actionable. However, the anecdotal backstory ('Seven months of that went unnoticed on the plan this was written for') is not needed for an agent to select or invoke the tool and inflates the text.

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 an output schema present, return values need no explanation, and the description covers the important input semantics plus request cost. The unaddressed plan_id and the unstated optionality/defaults for to_month are the only shortfalls.

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 0%, so the description must carry the load, and it does for most params: group_ids meaning and effect, account_ids narrowing behavior, and from_month/to_month accepted formats ('YYYY-MM', ISO date, 'current'). plan_id and to_month's default/optionality are never mentioned, leaving one clear gap.

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 states a specific verb+resource scope: transfers between two on-budget accounts reviewed month by month against category-group assignments. It explains why the analysis exists (on-budget transfers move no category money while looking like normal transactions). It does not explicitly differentiate itself from siblings like analysis_flow_trace or money_movements_list_by_month, so it stops short of a 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?

It gives concrete conditional guidance: pass group_ids to get flagged months where money moved with no assignment, omit them to get the transfers alone, and it names categories_list as the source of group ids. It also documents accepted date formats. It lacks explicit 'do not use this when...' framing relative to sibling analyses, so 4 rather than 5.

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