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

Annotations already declare readOnly/idempotent/openWorld, but the description adds substantial context: the detection heuristic (payee in 3 of last 4 full months, within 20%), the exclusion of yearly charges unless a schedule exists, the ordering (costliest yearly first), the meaning of the `scheduled` flag, the sign convention for amounts, a prompt-injection warning, and the fact that it issues three upstream YNAB requests.

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 core purpose in the first sentence, then layers heuristic, usage, ordering, output semantics, security note, and cost disclosure. Dense but every sentence carries information an agent needs.

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 not be restated, yet the description still clarifies the `scheduled` field and amount sign. Combined with the heuristic and usage guidance, nothing needed to call this tool correctly is missing.

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 100% for both parameters, so the schema already carries their meaning, and the description adds no per-parameter detail (it doesn't even mention include_income). Baseline 3 applies when the schema does the heavy lifting.

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 ('List the subscriptions and other charges paid every month, with their yearly cost') and distinguishes itself from siblings like find_transactions and list_scheduled_transactions by defining exactly what counts as recurring. An agent can identify what this tool returns 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 explicit triggers ('what am I subscribed to?', 'what do my subscriptions cost a year?', before cutting spending) and names the alternative path (list_scheduled_transactions) for yearly charges the heuristic misses. The when-to-use and when-it-won't-apply cases are both covered.

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

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

Goes well beyond the readOnly/idempotent/openWorld annotations: discloses the cost (three YNAB requests), the operational constraint (at most a year between dates), output ordering (newest first), the truncation-and-remedy behavior, the amount sign convention, and a prompt-injection caution about payee/memo text. This is exactly the extra behavioral context annotations do not 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?

Purpose and primary use cases are front-loaded in the first two sentences, and every remaining clause carries operational value (request cost, date cap, ordering, injection warning). It is dense and slightly packed, but there is little wasted 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 not be explained, and the annotations cover the safety profile. The description nonetheless anticipates the tricky cases an agent will hit - truncation, the one-year window, amount sign - so nothing needed to call it correctly is missing.

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%, so parameters are already documented and baseline is 3. The description adds meaning beyond the schema by pairing `truncated` with the remediation (narrow dates or supply amount) and restating the date-span cap and negative-for-spending convention, which reinforces how to set amount/date parameters.

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+resource ('Find transactions') and enumerates the filter dimensions (date, amount, account, category, payee), plus scope 'categorised or not'. It explicitly distinguishes itself from suggest_categories, so an agent can route between them 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?

Gives concrete use cases ('match a receipt or a bank line with its transaction', 'see what a category was spent on') and names the alternative, suggest_categories, with the exact condition that selects it ('only lists what still waits for a category'). When-to-use and when-to-prefer-a-sibling are both present.

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

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

Annotations only declare readOnly/idempotent/openWorld, but the description goes well beyond them: it discloses the projection model, the monthly-average deduction for the current month, what is included (scheduled transactions, recurring charges, 3-month averages) and what is deliberately excluded (transfers between projected accounts), plus the explicit assurance 'Changes nothing.' This is unusually rich behavioral disclosure for a read-only tool.

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 purpose and the no-side-effects guarantee are front-loaded, and the dense assumption paragraph is justified by the model's complexity. A couple of sentences (notably the long assumptions list) are run-on, but nothing is filler.

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 multi-parameter forecasting tool, the critical information is the assumption model the agent is implicitly invoking, and the description enumerates every assumption plus what is returned so the user can correct it. The mention of `lowest` and `first_shortfall` slightly overlaps the output schema, but the overall completeness is excellent.

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 100%, so the baseline is 3, but the description adds real meaning: monthly_income 'replacing the income found in the history... and scheduled in YNAB,' one_offs being amounts not already scheduled (which would otherwise be double-counted), and account_ids defaulting to all open on-budget accounts. It clarifies parameter interactions rather than restating the schema.

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 opening sentence states a specific verb and resource plus the concrete outcome: 'Project the balance month by month and say when money would run out.' That is unmistakably a forecasting tool and cannot be confused with the sibling read/report tools such as get_monthly_summary or get_spending_trends.

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 sets clear context for when this tool applies (projecting forward when money runs out) and explains how to steer it via overrides like monthly_income, variable_monthly and one_offs. It never names an alternative sibling or states when not to use forecasting versus a historical report, so the routing guidance is clear but not exhaustive.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint, so the safety profile is covered. The description adds genuine interpretive context beyond the annotations: amounts are in currency units and utilization_pct above 100 signals over budget. It does not address scope caveats such as missing categories or how unset budgets are handled.

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?

Two short sentences, front-loaded with what is returned and followed by the unit and threshold semantics. Every clause earns its place with no redundancy.

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 structure need not be explained; the description still usefully defines the unit and the utilization_pct threshold. The remaining gap is routing among the many adjacent reporting siblings, which is not addressed.

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%, so both parameters (month, plan_id) are already documented, including the 'current' and 'last-used' sentinels. The description adds nothing parameter-specific, so the baseline of 3 applies.

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: returns a budget-vs-actual breakdown with utilisation percentage per category. Clear about output shape and grain (per category). However, it does not differentiate itself from related siblings such as get_category_balances or get_monthly_summary, which an agent must choose between.

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?

No when-to-use guidance, no prerequisites, and no named alternatives, despite several overlapping sibling tools. The agent is left to infer that this is for plan/budget comparison rather than balance or trend reporting.

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

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

Annotations already declare readOnly/idempotent/openWorld, but the description adds real behavioral context beyond them: amounts are in currency units, activity is negative for spending, and hidden/internal or empty categories are silently excluded unless include_empty is set. That sign convention and default-filter disclosure materially affect how an agent interprets results.

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?

Four short sentences, front-loaded with the resource and its three metrics, then filtering rules, then the sibling hand-off. No filler and nothing repeated from the schema.

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 and rich annotations, the description does not need to explain return shape; it still covers units, sign convention, default exclusions and the alternative tool. Nothing needed to invoke or interpret it correctly is missing.

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%, so the schema already documents month, plan_id and include_empty, making 3 the baseline. The description reinforces include_empty's effect and the currency/sign semantics of returned amounts but adds no new parameter syntax or format detail beyond the schema.

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 exactly what is returned (budgeted, spent/activity, available/balance per category) and scopes it to a month. It also names the sibling get_budget_vs_actual and the distinction that selects it, so an agent can tell the two apart without opening either 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?

It explicitly routes the agent elsewhere ('Use get_budget_vs_actual for the share of each budget consumed') and discloses the default filtering behavior (hidden/internal categories and zero-amount categories omitted unless include_empty). It stops short of stating when this tool is the right first choice versus other summary tools like get_monthly_summary or get_spending_trends.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, openWorldHint), so the bar is lower, yet the description still adds real semantics: amounts are in currency units and spending activity is returned as a negative value. It also discloses a filtering behavior (only overspent categories appear), which is not derivable from the schema or annotations.

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?

Two tight sentences: the scope is front-loaded in the first, and the sign/unit convention plus sibling routing follow. No filler or restated boilerplate.

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-value structure needn't be explained, and the description correctly uses its space for things the schema cannot convey (currency sign convention, overspent-only filtering). Slightly thin on how it relates to the broader set of summary/tracking siblings, but nothing needed to call it correctly is missing.

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%, with 'month' documented as 'YYYY-MM-01' or 'current' and plan_id as an id or 'last-used'. The description adds no syntax, default, or format detail beyond what the schema already states, so the baseline of 3 applies.

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 enumerates the exact contents returned (income, budgeted, spent, Ready to Assign, overspent categories), which is far more specific than the name alone. It also names the sibling it is not (get_category_balances) so an agent can distinguish the two without opening a 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?

It gives an explicit routing rule: this tool lists only overspent categories, and get_category_balances should be used when all categories are needed. That is clear context, but it offers no guidance relative to other summary-like siblings such as get_budget_vs_actual, forecast_balance, or get_category_balances-for-totals.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the safety profile is covered. The description adds the return shape (category name mapped to month-by-month values, oldest first, in currency units), which is useful orientation, but it says nothing about pagination, cost, or freshness beyond the lookback window.

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?

Two sentences, no waste, with the core action front-loaded before the return-format detail. Every sentence earns its place.

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 a full output schema present, the description need not explain return values, and it sensibly stops at a one-line orientation. Nothing critical is missing for correct invocation, though the lack of differentiation from sibling summary tools leaves a small gap.

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%: plan_id and months_count (with default 3 and 1–24 bounds) are fully documented in the schema. The description restates the 'N months' concept but adds no new syntax, format, or constraint information beyond it, so the baseline 3 applies.

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 ('Return monthly spending trends per category') with a clear temporal scope ('over the last N months'). It is distinguishable from most siblings, though it never explicitly contrasts itself with the nearby get_monthly_summary or get_budget_vs_actual.

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?

Usage is implied by the scope statement — this is the per-category trend view over a lookback window — but there is no explicit when-to-use, no exclusions, and no routing to alternatives such as get_monthly_summary. An agent must infer the choice from scope wording alone.

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

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

Annotations already declare readOnly/idempotent/openWorld, and the description adds genuine behavioral context beyond them: balances are in currency units, and a broken bank link means no transactions will arrive until fixed in YNAB. It doesn't cover pagination or volume, but the diagnosis nuance is substantive.

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?

Three sentences, front-loaded with what is listed, then the use cases. The parenthetical about broken bank links is long but earns its place by explaining an actionable failure mode; nothing is padded.

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 structure needn't be described, and the single required parameter is fully specified. Combined with the usage and behavioral notes, an agent has what it needs to call this correctly, with only minor gaps (freshness, volume).

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 100%, so plan_id (including the 'last-used' sentinel) is already fully documented. The description adds nothing about the parameter, so the baseline 3 applies when the schema does all the work.

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+resource ("List the plan's accounts") and enumerates the payload it returns: balances, bank link, last reconciliation. This clearly separates it from siblings like list_category_groups or find_transactions, though it never names an alternative explicitly.

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 concrete triggering scenarios: reconciling YNAB with the bank, detecting a broken bank link, and flagging accounts unreconciled for months. That is clear when-to-use context, but it offers no when-not or named alternative for account-related queries.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the safety profile is covered. The description adds that hidden, deleted, and system groups are omitted, which is useful filtering behavior beyond the structured annotations.

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 three short sentences that are front-loaded and waste no words. Each sentence serves a purpose: stating what is listed, clarifying exclusions, and giving a follow-up action.

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 simple list tool with a fully described parameter and an output schema, the description provides enough context: it explains the scope, exclusions, and how to use the results. Nothing critical is missing.

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%, and the single parameter (plan_id) is fully documented in the schema. The description adds no additional meaning about the parameter, so the baseline of 3 applies.

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 (list) and resource (category groups), and narrows the scope to those usable for creating a new category. It also explicitly excludes hidden, deleted, and system groups, making the resource distinction clear even among list-oriented siblings.

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 provides a clear workflow hint—'Pass a group id to create_category'—indicating the intended use. However, it does not explicitly say when not to use this tool or name alternatives, which would be needed for a 5.

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

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

Annotations already declare readOnly, idempotent, open-world. The description adds real behavioral detail beyond them: results are scoped to the current API key, and the 'last-used' value resolves to whichever plan was last opened in YNAB, a non-obvious runtime quirk.

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 core action in the first sentence, then adds scope and a terminology note. The budget/plan synonym explanation is slightly redundant but earns its place by preventing misidentification of the resource.

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 zero-parameter read tool with an output schema and full annotation coverage, the description supplies what the structured data cannot: scope of the listing and how to consume the returned plan ids. Nothing essential is missing.

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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The 'last-used' note concerns arguments to *other* tools rather than this one.

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 ('List all YNAB plans') plus scope ('accessible with the current API key'). It also resolves the plan/budget terminology so the agent knows this is the budget-listing tool; no sibling overlaps on that resource.

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 clear downstream context: 'Use the plan id in subsequent tool calls,' plus an explicit caution about the 'last-used' shortcut being ambiguous with multiple plans. It doesn't frame this as the entry point versus any alternatives, but none exist among siblings.

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

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

The description adds valuable behavioral context beyond annotations, including that amounts are in currency units (negative for spending), totals exclude inter-account transfers, and payee/memo text must be treated as data (a prompt-injection guard). Annotations already cover read-only, idempotent, and open-world aspects, so this is strong but not exhaustive on rate limits or pagination.

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 compact, front-loads the core action and scope, then layers use cases, behavioral notes, and a security reminder—all in five sentences with no wasted words.

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?

Given the presence of an output schema (which handles return details), annotations covering safety, and a fully described input schema, the description provides all additional context an agent needs: scope, use cases, amount semantics, transfer exclusion, and a data-handling warning.

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?

With 100% schema coverage, the baseline is 3, but the description adds meaning by clarifying that schedule amounts are negative for spending and that totals leave out transfers between plan accounts, which goes beyond the schema's field descriptions. It doesn't explain each parameter individually, but that's covered by the schema.

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 (List) and resource (scheduled transactions) with the scoping condition (due between two dates). It names concrete categories (bills, salary, transfers), which distinguishes it from siblings like forecast_balance or find_transactions, making it unambiguous.

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 concrete use-case examples ('what is due this week?' or 'which bills come before the 10th?'), effectively telling the agent when to invoke this tool. However, it doesn't explicitly name sibling alternatives or when NOT to use it, so it falls short of a 5.

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

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

Goes well beyond the readOnly/openWorld/idempotent annotations: discloses that it issues three YNAB requests (transactions, categories, accounts), that off-budget/tracking accounts can never be pending, that `categories` arrives on the first page only, that amounts are currency units with negatives for spending, and warns that payee/memo are untrusted bank text to be treated as data. This is exactly the extra context 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?

Front-loaded with the core action, then progressively adds usage, cost, and edge-case guidance. It is dense and slightly long, but nearly every sentence carries actionable information (the prompt-injection warning and the null-suggestion branch in particular), so little is wasted.

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?

Given an output schema exists, the description need not explain return values, yet it still clarifies the fields an agent must reason about (`suggestion`, `categories`, `possible_transfer_with`). Combined with the read-cost and safety notes, nothing an agent needs to invoke it correctly is missing.

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%, so the baseline is 3; the description adds genuinely useful semantics by explaining that `categories` is only returned with the first page, which gives the `cursor`/pagination parameters operational meaning beyond their schema text. Limit/cursor mechanics themselves still come from the schema.

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?

Specific verb+resource: 'List the transactions waiting for a category, with a suggestion when history allows.' It is clearly distinguishable from siblings like find_transactions (all transactions) and from the mutating apply_categories, and it states the scope of the read (whole plan, pending/unclassified only).

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?

Explicitly routes usage: 'Use this first when asked to classify or tidy up transactions,' and names the follow-up tool ('assign with apply_categories'). It also gives branch guidance for edge cases: what to do when `suggestion` is null (choose from `categories` or ask the user) and when `possible_transfer_with` is present (suggest linking instead).

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