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

Annotations already declare readOnly/idempotent/openWorld, and the description adds substantial non-structured context: the detection threshold, sort order (costliest yearly first), the meaning of the `scheduled` field, the sign convention for amounts, an explicit prompt-injection warning about payee names, and the number of upstream requests. This is well beyond what the annotations convey.

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?

Dense but front-loaded, with the core definition given first and edge cases (annual charges, income ordering) trailing. The density is near the limit, with nested clauses in the final sentence, but essentially every sentence carries information.

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 shapes need not be restated. Given that, the description covers the algorithm, ordering, inclusion rules, and a security caveat, leaving no gap an agent would need before calling it.

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 for include_income: income appears after charges, largest first, and yearly_total still sums only charges. That behavioral nuance is not inferable 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?

States a specific verb and resource ('List the subscriptions and other charges paid every month') and even defines the detection heuristic (payee seen in 3 of the last 4 full months within ~20%). This makes it clearly distinguishable from siblings like find_transactions or list_scheduled_transactions.

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 use cases ('what am I subscribed to?', 'what do my subscriptions cost a year?', 'before cutting spending') and names the relevant alternative (list_scheduled_transactions) plus the fallback for annual charges. When-to-use and when-it-won't-see-something 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 already cover read-only and idempotent behavior, but the description goes further: it spells out the projection model (scheduled transactions, 4-month recurrences, 3-month averages), the mid-month deduction rule, and exclusions (transfers between projected accounts, scheduled payees). It also says the assumptions are returned so the user can correct them, which is exactly the kind of behavioral 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 purpose and outcome, then method, then alternatives. It is dense rather than bloated: every clause about assumptions, exclusions, and defaults carries information. A minor deduction for being a single sprawling paragraph that could be split for readability.

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 6 parameters, an output schema, and read-only annotations, the description is complete: it covers methodology, defaults, exclusions, return fields like `lowest`, `first_shortfall`, and `assumptions`, and the boundary against sibling tools. An agent has everything needed to call it correctly and interpret the result.

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: it explains that one_offs are not those already scheduled in YNAB, that monthly_income replaces historical and scheduled income, and that defaults are derived from 3 months of non-recurring inflows. The only small gap is that 'variable_monthly' is described mostly as it is in the schema, without elaborating on its interaction with recurring charges beyond the parenthetical.

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 plus the key outcome: 'Project the balance month by month and say when money would run out.' It also names the sibling tools it is not (get_monthly_summary, get_spending_trends, get_runway), so the agent can separate it from 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?

Explicit routing: past months go to get_monthly_summary, multi-month comparison to get_spending_trends, and no-income survival to get_runway. The phrase 'For a month already gone...' gives a clear when-not condition, and 'Changes nothing' clarifies it is advisory only.

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?

Beyond readOnly/idempotent annotations it discloses the call footprint ('One YNAB request, the list of months; changes nothing'), the null-not-error behavior for months lacking history, the instruction to relay notes with figures, and the truncation behavior when a plan holds fewer months than requested. These are exactly the traits an agent needs and none are in the structured fields.

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 metric definition, then usage, then parameter behavior, then the sibling pointer — a sensible order with no filler. It is on the long side with some clause-heavy sentences, but nearly every sentence carries a distinct fact.

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 shape needn't be spelled out, yet the description still flags the aggregate fields (latest, change, direction) and the null case. Nothing an agent needs to call this correctly or interpret the result 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%, so the baseline is 3, but the description adds real meaning for months_count: it counts back from the current month inclusively (1 = this month alone) and explains what happens when the plan has fewer months of history than requested. plan_id semantics are left entirely to the schema ('last-used'), which is the only shortfall.

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 metric (YNAB's Age of Money), what it measures in days, and that it is returned month by month with a trend. It also names the sibling it is not ('For how long the money would last without income use get_runway'), so an agent can distinguish it from get_runway and get_spending_trends 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 user phrasings that should trigger it ('how old is my money?', 'am I living on last month's income?') and explicitly routes the adjacent case to get_runway. The condition that selects this tool versus the alternative is stated outright.

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 still adds real context beyond them: the month argument is validated and 'any other day is refused', 'current' may be misleading mid-month, and 'One YNAB request; changes nothing' quantifies cost and mutability. It also explains output semantics (utilization_pct > 100 = over budget, carried_over adds to budgeted) so the agent can interpret results, not just call the 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?

Front-loaded with the purpose, then use cases, then parameter constraints, then return semantics, then routing to siblings. No sentence is filler; even the short routing block consolidates three alternatives in one place rather than scattering them.

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 the description needn't enumerate fields, yet it still clarifies the two counterintuitive ones (utilization_pct and carried_over, including the 'over budget but still has money left' case). With annotations covering safety, nothing an agent needs to call or interpret this 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%, so baseline is 3, but the description adds meaning the schema does not carry: month must be strictly the first day of a month or it is refused, and 'current' denotes the in-progress month whose sub-100 share may be an artifact of incompleteness. That is genuine interpretation guidance beyond the schema's terse one-liners.

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 a specific verb+resource+scope: 'Share of each category's budget spent in a month, to see what is over or close.' It names three sibling tools (get_category_balances, get_monthly_summary, get_spending_trends) and states each one's distinct scope, so an agent can route without opening any 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?

Provides explicit use-case phrasings ('am I over budget?', 'which categories are nearly used up?') and explicit alternatives with the condition that selects each: balances for what is still available, monthly summary for totals, spending trends for prior months.

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?

Beyond the readOnly/idempotent annotations, the description adds useful operational context: one YNAB request, no changes, currency units, negative activity for spending, hidden/internal category exclusion, and default omission of empty categories. It does not contradict the annotations and provides enough behavioral detail for safe invocation.

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 is front-loaded, followed by usage examples, alternatives, filtering behavior, and operational notes in a compact form. Every sentence contributes useful guidance without 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?

Given the existing output schema, annotations, and fully described parameters, the description is complete for an agent to select and call the tool correctly. It covers purpose, alternatives, data conventions, filtering, and mutation safety.

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. The description adds meaning beyond the schema for include_empty by explaining the default filtering behavior and what it includes, though it does not add much detail for month or plan_id 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 a specific resource and scope: budgeted, spent, and available amounts per category for a month. It also explicitly distinguishes itself from siblings by naming get_budget_vs_actual, get_monthly_summary, and get_spending_trends for related questions.

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 usage examples such as "how much is left in Groceries?" and listing every category's money. It also names alternatives with their intended use cases and explains default exclusions and the include_empty exception.

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 goes further: it discloses the exact YNAB request count (one, or two when a minimum is missing), that nothing is changed, how a missing rate/minimum is handled, and that account names are user data, never instructions (a prompt-injection guard). This is rich context beyond the annotation set.

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 purpose and usage examples, and every sentence carries substantive information with no filler. The prose is dense and run-on in the middle section (payment mechanics), which slightly hurts readability, but nothing 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?

Very complete for a compute-heavy tool: strategy semantics, override handling, budget fallback, request counts, and safety notes are all covered, and an output schema exists so return values need not be described. Minor gaps remain, e.g. it doesn't state the response shape for edge cases like plan_id 'last-used', but overall an agent has what it needs.

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?

Although schema coverage is 100%, the description adds computation-relevant meaning: what monthly_budget falls back to (sum of minimums, else average paid over the last 3 complete months), that overrides replace/fill YNAB's loan-detail values, and that rates are percent and amounts currency units. This goes beyond 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 the specific resource (when debts get paid off) and the two strategies (avalanche/snowball) computed, which no sibling tool does. It is immediately distinguishable from analytical siblings like get_net_worth_trend or get_runway.

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?

Provides concrete trigger phrases ("how do I pay off my debts fastest?", "avalanche or snowball?", "when will I be debt-free if I put 500 a month on my loans?") and explicitly routes the past-focused question to get_net_worth_trend. When-to-use and the alternative are both named.

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 substantial context: a single YNAB request, 'current' returns partial figures that still count entered future days, amounts are currency units with negative activity for spending, and only overspent categories appear. It also warns that non-first-of-month dates are refused, a real behavioral constraint not in the 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?

Front-loaded with the payload summary, then routing, then format rules, then output semantics – a logical order with no filler sentences. It is dense but each clause carries information; only the 'changes nothing' phrasing slightly restates the readOnly annotation.

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 everything else an agent needs is here: date format strictness, 'current' semantics, sign convention for activity, the overspent-only scope, alternatives, and request cost. Nothing material is missing for a simple two-parameter read 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 100% and the schema already documents both parameters, so a baseline 3 applies, but the description adds genuine meaning: the month must be the first day of the month, other days are refused, and 'current' means the in-progress month with partial figures. That goes beyond the schema's terse enum-like hint.

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 plus exactly what the payload contains (income, budgeted, spent, Ready to Assign, overspent categories), and explicitly contrasts with get_category_balances, get_spending_trends and forecast_balance. An agent can pick this out from the sibling list 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?

'Use it first to review a month' gives an explicit entry-point rule, and alternatives are named with their selecting conditions: get_category_balances for every category, get_spending_trends for prior months, forecast_balance for future months. When-to-use and when-not-to-use 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?

Annotations already establish readOnly, idempotent, openWorld, so the safety profile is covered. The description nonetheless adds genuinely non-obvious behavior: which account types count as debts, that closed accounts count while they had a balance, that each month is valued on its last day net of later-dated transactions, and the sign convention. The cost disclosure ('Two YNAB requests: accounts, transactions') is useful operational context.

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 behavior and the usage questions before the detailed accounting rules. It runs long and the clause about the current month's prorated balance is dense, but nearly every sentence carries distinct information rather than 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 two-parameter, read-only analytics tool with an output schema, the description covers everything an agent needs: scope, account inclusion rules, month-end valuation, sign convention and net worth composition. Return-value formatting is correctly left to the output schema.

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 earns more by defining the counting semantics of months_count: it counts back from the current month inclusive, so 1 is this month alone and 12 is a year, regardless of how long the plan has existed. That is interpretation the schema does not supply.

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 a specific verb-and-resource statement: assets, debts and net worth at each month end, for the purpose of watching debt decline. It is immediately distinguishable from list_accounts (today's balances) and forecast_balance (future months), both of which are named 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 questions ('is my debt going down?', 'am I paying off my loans?') plus explicit routing: list_accounts for each account's balance today, forecast_balance for months ahead. Both the when and the when-not are spelled out.

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, and the description usefully corroborates them with 'changes nothing' plus a concrete cost signal (two YNAB requests, three with essential_groups) and a prompt-injection warning about user-authored account/group names. It also discloses null runway_months edge cases and the left_out list, which is real added value. But much of that is returning-value detail the output schema already covers, so against a fully annotated read-only tool the incremental behavioral disclosure is solid rather than exceptional.

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 core definition and the routing alternatives are front-loaded and every clause after that is load-bearing (account scope, transfer rules, null conditions). It is nonetheless a single dense block of roughly a paragraph-and-a-half for a four-parameter read; the transfer-handling and essential-fund phrasing could be tightened without loss.

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 computed-metric tool it covers the full set of things an agent must know: the formula's inclusions/exclusions, the averaging window, null semantics, request cost, side-effect freedom, and explicit hand-offs to forecast_balance and get_monthly_summary. Return shape is left to the output schema, as appropriate.

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 baseline is 3; the description earns above that by explaining what months_count averages over ('last complete months', excluding months before the first transaction), what include_savings implicitly includes (savings-account balances in money available), and that essential_groups produces a *second* runway rather than replacing the all-spending 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?

Opens with a specific metric and a plain-language definition: months the available money would last without income at usual spending. It then enumerates exactly what counts as money available (checking/savings/cash balances minus credit card and line-of-credit debt, tracking accounts excluded) and what counts as spending, which is far more than a verb+resource label.

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 three literal user phrasings the tool answers, then explicitly routes competing intents elsewhere: forecast_balance for month-by-month projection with scheduled income and bills, get_monthly_summary for the current month. It also carves out the negative case ('a question about a stop in income, not about a month').

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?

Beyond the read-only/idempotent annotations, it discloses genuinely load-bearing behavior: how 'income' and 'spending' are defined, that transfers between budget accounts are excluded, that transfers to tracking asset vs loan accounts count as saved vs spent, that months with no income yield a null rate, that only complete months from the first transaction count, and that it fires three requests and changes nothing.

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 output shape and purpose are front-loaded, and the definition sentences (income/spending/transfer edge cases) each prevent a real misreading. It is dense and long, but nearly every clause earns its place; slightly tighter phrasing would be ideal.

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 100% parameter coverage, the remaining burden is the semantic contract, and the description supplies it fully: field definitions, unit/sign conventions, null handling, and the 'relay the notes with the figures' instruction for presenting results.

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: 'Complete months only, from the budget's first transaction' constrains what months_count actually counts, and 'Amounts in currency units, spending negative' clarifies the output sign convention rather than leaving it to inference.

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 and resource (compute savings rate from income/spending/saved), enumerates the exact fields returned ('income, spending, saved, rate'), and explicitly distinguishes itself from the sibling get_spending_trends. An agent can tell precisely what this 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?

It gives concrete trigger phrasings ('what's my savings rate?', 'am I saving more than last spring?') and names the alternative with the condition that selects it ('For spending per category use get_spending_trends'). When-to-use and when-to-use-something-else 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 annotations by disclosing the API cost model ('one request for the list of months, then one per month'), the partial current month, and the truncated history for young plans — real behavioral traits an agent can't infer from schema. Docked slightly because return-value description partly duplicates the existing output schema.

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 purpose, then usage, then mechanics, then alternatives — good ordering. Slightly long; the sentence describing the return map restates what the output schema already provides and could be trimmed.

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 read-only, two-parameter analytics tool with an output schema, nothing an agent needs is missing: scope, defaults, edge cases (partial month, young plan), cost, side-effect status, and alternatives are all present.

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 baseline is 3, but the description adds genuine semantics: months_count counts back inclusively from the current (partial) month, default 3 covers this month plus two prior, and a younger plan yields only the months it has. That is meaning beyond the schema's 'number of past months, 1 to 24'.

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+shape: 'Spending per category, month by month, over the last N months', and immediately frames a concrete user question ('is my grocery spending going up?'). This clearly distinguishes it from get_monthly_summary, get_category_balances and 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?

Explicit routing: single month → get_category_balances or get_budget_vs_actual; future months → forecast_balance. It also states the comparative use case, so both when-to-use and when-not-to-use are 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 annotations: one YNAB request, changes nothing, snoozed targets excluded, amounts in currency units, and an explicit prompt-injection warning that category names are data, never instructions. It also explains the limit/totals interaction, which is a non-obvious behavioral trait.

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 purpose and example questions before the field and sorting detail. The sorting sentence is dense and the returned-field enumeration is somewhat long, but every clause carries usable information.

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, yet the description still covers ordering, totals versus Ready to Assign, exclusions, units, and the read-only nature — enough for an agent to call it correctly and interpret results. Nothing material is missing for a 3-parameter read 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 100%, so the baseline is 3; the description nonetheless reinforces the key semantic trap that limit shortens the list while totals still count every underfunded target, and frames month as 'this month'. It adds marginal but real meaning on top of 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?

States a specific resource and scope: categories with targets that still need money this month, ordered most-urgent-first. That is clearly distinguishable from siblings like get_category_balances (balances) and get_budget_vs_actual (actuals), and the ordering rule further separates it from any generic list tool.

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 three concrete example questions the tool answers and states the boundary that funding itself happens in YNAB, not here. It does not name a sibling tool as the alternative for adjacent questions (e.g. balances vs underfunded), so it falls short of full when/when-not routing.

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, and the description adds real behavioral context beyond them: all accounts including closed ones come back in a single response/one YNAB request (no pagination), balances are today's and not historical, and cleared_balance is defined as the bank-confirmed portion. 'Changes nothing' merely restates readOnlyHint, a minor redundancy rather than 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?

The first sentence front-loads purpose and return fields, and the usage/routing guidance follows logically. It runs slightly long with a few near-redundant clauses ('changes nothing', repeating the YNAB-settings disclaimer), but nearly every sentence carries decision-relevant information.

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?

Single-parameter read tool with an output schema, so return values need no prose, yet the description still clarifies balance semantics, closed-account inclusion and single-request completeness. Nothing an agent needs to select or 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?

With 100% schema coverage the baseline is 3, but the description adds meaning the schema lacks: where plan ids come from (list_plans) and what 'last-used' actually resolves to — the plan last opened in YNAB — plus the multi-plan condition that makes it necessary.

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 plan's accounts') plus the fields returned (balances, bank link, last reconciliation), which is exactly what distinguishes it from sibling listers like list_plans and list_payees. It further names get_net_worth_trend and forecast_balance as the tools for other time ranges, so an agent can route 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 when-to-use triggers (broken bank link, account unreconciled for months), explicit alternatives for the wrong time horizon ('for the months before use get_net_worth_trend; for the months ahead, forecast_balance'), and an explicit out-of-scope note that comparing against the bank happens in YNAB itself.

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?

Beyond the readOnlyHint/idempotentHint annotations, it discloses the filtering behavior (hidden, deleted and system groups are left out) and the cost profile ("One YNAB request"). "Changes nothing" largely restates readOnlyHint, so the added value is real but not extensive.

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 core scope and the sibling routing come first and every sentence carries information. The definition of a group is valuable for avoiding misuse, though the awkward line breaks and a couple of redundant clauses ("changes nothing") slightly dilute it.

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 prose. With one required, fully documented parameter, an explicit plan-id acquisition route, declared filtering, and a stated request cost, nothing an agent needs to invoke this 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%, so the baseline is 3, but the description adds meaning the schema does not: it explains that 'last-used' follows the plan last opened in YNAB and that the id should come from list_plans, giving the agent an acquisition path for the required value.

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 category groups") and immediately scopes it to those a category can be created in or moved to. The follow-up sentence defines what a group is and explicitly disclaims budget/spend data, which separates it cleanly from get_category_balances and suggest_categories.

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?

Names the alternative tools and the conditions that select them (get_category_balances for money per category, suggest_categories for classifying transactions, list_plans for obtaining a plan id). It also states an exclusion rule (hidden, deleted and system groups omitted) and clarifies that creation/moving happens in YNAB, not here.

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?

Beyond the readOnly/idempotent annotations, it discloses that transfer payees and deleted payees are omitted, how total and shown differ, the 50 default and 200 maximum, and that imported names should be treated as data rather than instructions. These are meaningful behavioral traits an agent would not infer from annotations alone.

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 definition is front-loaded and mostly earns its length, with useful sentences on search, pagination, exclusions, and safety. It is somewhat dense and could be tightened, but there is little redundant repetition.

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 existing output schema and annotations, the description supplies the remaining context an agent needs: exclusions, search behavior, pagination meaning, limits, and a prompt-injection caution. Nothing important for correct invocation appears to be 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 complete, but the description still adds value by explaining that search matches both bank label and normalized merchant case-insensitively, and by giving the total/shown pagination behavior and practical limit advice. plan_id semantics are left mostly to the schema, so it is not quite exhaustive.

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 opens with a specific verb and resource ('List the payees of a plan') and immediately distinguishes itself from find_transactions ('It lists names, not money'). It also scopes coverage by excluding transfer payees and deleted ones, so an agent can tell exactly what this tool returns.

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 usage context: seeing names left behind by a bank import, searching by normalized merchant or raw bank label, and using find_transactions when the goal is transactions rather than payees. It also explicitly says renaming is done in YNAB itself and advises narrowing search instead of raising the limit when total exceeds shown.

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 readOnly/idempotent/openWorld. The description adds real behavioral context beyond them: the 'last-used' alias ambiguity and the fact that this is the sole source of the plan list. It doesn't describe the response shape, but an output schema exists so that's acceptable.

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 purpose, then layered with terminology, id caching, and sibling pointers. Every sentence adds actionable value with no 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 no-param read tool with an output schema and rich annotations, the description supplies everything needed: purpose, id usage, caching advice, and where related data lives (get_monthly_summary, list_accounts).

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?

Zero parameters, so the baseline is 4. There is no input to explain and the description correctly says nothing about 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 ('List all YNAB plans') and explicitly disambiguates terminology (plan = budget). It also distinguishes itself from siblings by noting 'no other tool reads this list.'

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 instructs to use the returned plan id in subsequent calls, warns that 'last-used' is ambiguous when multiple plans exist, and says to call once and cache the id. The when-to-use and how-to-use guidance is fully spelled out.

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?

Annotations already declare readOnly/idempotent, but the description adds substantial context beyond them: the cost profile (three YNAB requests per call), pagination behavior (50 default, 200 max, newest first, pending_count totals, cursor pass-through, categories on first page only), how suggestions are derived, transfer-duplicate detection via possible_transfer_with, sign convention for amounts, and a prompt-injection warning on payee/memo fields. That is far beyond what annotations convey.

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 purpose and usage before edge cases. It is long, but the length is largely earned by the number of behaviors an agent must know (pagination, suggestion logic, transfer detection, safety note); a few clauses could be trimmed 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?

Output schema exists and annotations are rich, and the description fills the remaining gaps an agent needs: pagination contract, suggestion-null fallback behavior, cost expectations, and the 'nothing is changed' expectation-setting. Nothing material for correct invocation 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%, so the schema already defines limit and cursor. The description still adds real semantics: newest-first ordering, that categories only comes with the first page, and that next_cursor must be passed unchanged — information the schema alone does not supply.

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 transactions waiting for a category') plus the added value ('with a suggestion when history allows'). It also distinguishes itself from find_transactions, which an agent could otherwise confuse this with.

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 routing ('Use this first when asked to classify or tidy up transactions') and enumerates what is excluded — off-budget accounts, already-categorized transactions, splits, transfers — with a pointer to find_transactions for the reverse operation. When-to-use and when-not-to-use are both covered.

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