Analysis — Assignment patterns

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

Annotations already declare readOnly/non-destructive/closed-world, but the description goes well beyond them: it quantifies the request cost (one YNAB request per month, 36-month cap, plus one for inflows), explains the false-positive case (deliberately self-funded categories), and clarifies that total_if_unintended is a signal metric, not a verdict. That is rich behavioral context the annotations cannot carry.

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?

It is front-loaded with the [READ] marker and the core definition, then layers caveats and cost. Nearly every sentence earns its place, though the illustrative anecdote ('sixteen months... about $841') is color that a tighter version could drop.

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 not be explained, and the description covers cost, interpretation, filtering, and date formats. The only gaps are the undocumented plan_id and include_hidden parameters, minor for a plan-scoped analysis 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 description coverage is 0%, so the description must compensate, and it does for four of six params: from_month/to_month get explicit accepted formats ('YYYY-MM', ISO date, 'current'), and group_ids/category_ids are explained as narrowing filters. plan_id and include_hidden are left undocumented, so it is not fully complete.

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 names a precise verb and resource: it detects categories whose monthly assignment equals a fixed base plus that month's inflows (interest double-counting). The opening [READ] tag and the concrete mechanism distinguish it immediately from sibling analysis_* tools like analysis_copied_forward_months or analysis_credit_funding.

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 tells the agent how to narrow results (group_ids/category_ids), when to check cost (overview_request_budget before a long range), and how to interpret output ('a signal, not a verdict'). It lacks an explicit statement of when this analysis is preferable to a sibling like analysis_flow_trace, so it's a strong 4 rather than a 5.

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