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 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 readOnly/idempotent/openWorld, and the description reinforces this with "One YNAB request... changes nothing." It adds genuinely new behavioral context beyond the annotations: null months when history is insufficient, the need to relay notes, and the shape of the answer (per-month figures, latest, change, direction).

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 definition, then usage questions, then the alternative and behavioral notes. Dense but each sentence carries information; slightly long for what is fundamentally a two-parameter read.

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 metric tool with an output schema present, the description covers definition, interpretation, output shape, null handling, and sibling routing. Nothing an agent needs to call or interpret it 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 both plan_id and months_count are already documented. The description references "the list of months" but adds no syntax or format detail beyond the schema, 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 metric, defines it precisely ("how long, on average, money stayed in the budget accounts before being spent, the oldest money spent first"), and explicitly distinguishes it from the sibling get_runway. An agent can identify this tool 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?

Names concrete user intents ("how old is my money?", "am I living on last month's income?", "is my buffer growing?") and routes to the alternative explicitly: "For how long the money would last without income use get_runway." Includes an interpretation threshold (>30 days).

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, openWorldHint, so safety is covered; the description adds the direction convention (spending positive, utilization_pct>100 = over budget), the single-request cost, and 'changes nothing'. That is meaningful operational context beyond the annotations. It stops short of mentioning pagination or freshness of the data, so not a 5.

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 calculation, then answers the question this serves, then the routing alternatives, then the unit conventions. Four short sentences 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?

For a 2-param read-only tool with an output schema and full annotation coverage, the description supplies the orientation (question it answers), the alternative-tool split, and the number conventions. Nothing an agent needs 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% and the schema already documents both month and plan_id formats, so the description adds little parameter-level detail. Baseline 3 applies when structured fields do 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+resource: computes the share of each category's budget spent in a month, with the explicit goal of revealing over/close-to-limit categories. It also names three sibling tools (get_category_balances, get_monthly_summary, get_spending_trends) and the distinct question each answers, so an agent can pick this tool 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?

Explicit when-to-use framing ('am I over budget?', 'which categories are nearly used up?') plus three named alternatives each tied to a different intent. This is textbook routing guidance.

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 the exclusion rules (hidden and internal categories dropped; empty categories omitted unless include_empty is true), the currency-unit and sign convention (activity negative for spending), and the cost profile (one YNAB request, no mutation). This is meaningful behavioral context an agent could not derive from the 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?

Front-loaded with the core purpose, then usage, alternatives, and behavioral constraints in a tight block. The closing "One YNAB request; changes nothing" is mildly redundant with readOnlyHint, but the rest 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?

An output schema exists, so return shape need not be explained. Purpose, usage routing, exclusion semantics, and safety profile are all covered, leaving no gap an agent needs to fill before invoking the 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 schema already documents month, plan_id, and include_empty. The description adds real meaning on top: the default behavior of excluding categories with no budgeted/spent/available amount, and the hidden/internal exclusion rule that is not in the schema. That is more than a restatement.

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-set and resource: budgeted, spent (activity), and available (balance) per category for a month. It is immediately distinguishable from siblings like get_budget_vs_actual and get_monthly_summary, which are named explicitly later.

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 user-intent triggers ("how much is left in Groceries?", "list every category's money") and points to two named alternatives with the condition that selects them. Explicit when-to-use and when-to-use-something-else guidance is 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 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 readOnlyHint and idempotentHint, but the description adds real context beyond them: amounts are in currency units, activity is negative for spending, only overspent categories appear, and it costs a single YNAB request and mutates nothing. Return shape/pagination is left to the 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?

Three compact sentences, front-loaded with the summary contents before the routing list. The sibling-comparison clause is dense but each part maps to a distinct decision, 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?

With an output schema present and annotations covering safety, the description only needs to convey scope and semantics — the sign convention, currency units, and overspent-only listing are exactly the gaps it fills. Nothing an agent needs 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 both plan_id and month (including the 'YYYY-MM-01'/'current' format) are already documented in the schema. The description adds no parameter syntax or defaulting detail beyond that, 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+resource (month summary) and enumerates the exact contents (income, budgeted, spent, Ready to Assign, overspent categories), which lets an agent distinguish it from sibling tools 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?

'Use it first to review a month' gives explicit ordering guidance, and it names three alternatives with the conditions that select them: get_category_balances for all categories, get_spending_trends for prior-month comparison, forecast_balance for future 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, it discloses the request footprint ('Two YNAB requests: accounts, transactions; changes nothing'), the computation method ('today's balance less the transactions dated after it'), sign conventions (debts negative, net_worth = assets + debts), and the closed-account edge case. This is rich behavioral context the 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?

It is dense and longer than average, but every sentence earns its place: use cases first, then methodology, sign conventions, edge cases, and alternatives. No filler, though the calculation detail could be tightened.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be described. For a computed trend tool the description still covers methodology, sign conventions, closed accounts, request count, and alternatives — nothing an agent needs 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 plan_id and months_count are already documented in the schema. The description hints at the monthly scope but adds no format or default detail beyond what the schema provides, so 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?

The opening sentence states a specific resource (assets, debts, net worth at each month end) with a clear intent ('to see debts go down'). It explicitly names sibling tools it is not (list_accounts, forecast_balance), so an agent can route correctly 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 concrete triggering questions ('is my debt going down?', 'am I paying off my loans?') and explicit alternatives: 'For each account's balance today use list_accounts; for the months ahead, forecast_balance.' Both when-to-use and when-to-use-something-else 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?

Despite annotations already covering readOnly/idempotent/openWorld, the description adds substantial behavioral detail: exactly which accounts are in scope, what is excluded and surfaced in left_out, the null conditions for runway_months, negative-sign currency convention, the exact request count, an explicit 'changes nothing' guarantee, and a prompt-injection warning about user-text names. This is far beyond 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 core definition and example intents before the dense calculation detail. The single-block format is long, but nearly every clause carries necessary semantics (exclusions, null cases, request count), so little waste despite the length.

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 nuanced derived-metric tool with an output schema, the description still covers edge cases (null results), the secondary essential runway, currency/sign conventions, and asks the agent to relay notes. Nothing an agent needs to call or interpret it 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 already 100%, so the baseline is 3, but the description adds real meaning: it explains that months_count averages only complete months (excluding months before the first transaction), that essential_groups produces a second essential-only runway, and that include_savings toggles savings out of money available.

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 precise, self-contained definition of the metric ('How many months the money available would last without income, at the usual spending') plus worked example phrasings. An agent knows exactly what number this returns and can distinguish it from siblings like get_savings_rate or get_age_of_money 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?

Three concrete user-intent phrasings ('if I lost my income, how long could I last?', 'how many months of expenses do I have saved?', 'is my emergency fund enough?') give clear context for when to reach for it. However, it never names a sibling alternative or states when NOT to use this tool, so there is no explicit routing guidance.

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?

Annotations cover safety (readOnly, idempotent, openWorld), and the description adds genuinely new behavioral context: the exact shape of the result (category name mapped to month-by-month values, oldest first, positive currency units) and the cost profile (one request for the month list, then one per month). 'Changes nothing' reinforces the non-mutating nature.

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 tight sentences, front-loaded with what the tool returns, followed by usage routing and then cost/return semantics. No filler and nothing buried.

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 so return values need not be explained, yet the description still clarifies ordering and sign convention, and it discloses the per-month request cost. Nothing an agent needs to call 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 description coverage is 100% and both parameters (plan_id, months_count with default and 1-24 bounds) are fully documented in the schema. The description's 'last N months' adds no syntax or format detail beyond that, 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+resource ('Spending per category, month by month, over the last N months') with explicit scope, and the naming of sibling alternatives makes it trivially distinguishable from get_category_balances, get_budget_vs_actual, and forecast_balance.

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 motivating questions ('is my grocery spending going up?', comparing months) and then explicitly routes the agent away to alternatives for a single month and 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 cover readOnly/idempotent/openWorld, and the description adds real behavioral detail on top: snoozed targets are omitted, output is ordered by urgency with a stated tie-breaking rule, amounts are currency units, totals compare against Ready to Assign, one request is made, and category names are flagged as data rather than instructions.

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 usage, then output shape and ordering. It is dense and a little long, but nearly every clause carries information an agent would otherwise lack; nothing reads as 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?

An output schema exists and the description still explains the meaning of needed/left, the urgency ordering, the totals comparison and the snooze exclusion, leaving no ambiguity about when to call it or what it returns.

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 limit, month and plan_id are already fully documented in the schema, including that totals count every target regardless of limit. The description adds no per-parameter syntax or format detail beyond that, 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?

Names a specific resource and scope: 'The categories whose target still needs money this month, the most urgent first.' That immediately distinguishes it from siblings like get_category_balances or get_budget_vs_actual, which do not rank by underfunding.

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 user questions it answers ('which targets are behind?', 'can I cover my targets?') and states the boundary of its job: 'To fund them, the user assigns money in YNAB itself,' which steers the agent away from expecting this tool to move money.

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 and openWorld, and the description adds genuinely useful context beyond them: every account returns in a single YNAB request, closed accounts are included, and the call mutates nothing. It does not discuss rate limits or error behavior, keeping it short of a 5.

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 purpose and returned fields are front-loaded, and each following sentence earns its place by adding usage context or behavioral facts. Four sentences is slightly more than strictly necessary 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?

With an output schema present, return values need no explanation, and the description still covers scope, the closed-accounts inclusion, single-request behavior, and cross-tool id linkage. Nothing an agent needs 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% and plan_id is fully documented there, so the baseline is 3. The description adds no syntax or format detail for the parameter itself; its note that the returned ids are the account_ids other tools take is about output, not the input.

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') and enumerates the returned fields (balances, bank link, last reconciliation), which clearly separates it from siblings like get_category_balances or list_plans.

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 conditions: reconciling YNAB with the bank, detecting broken bank links, and flagging accounts unreconciled for months. It stops short of naming an alternative tool or stating when not to use it, so it is clear but not fully 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, so the safety profile is covered. The description adds valuable filtering behavior beyond the annotations by stating that hidden, deleted, and system groups are omitted, which materially affects what the agent can rely on in the 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?

The description is three short, front-loaded sentences with no filler. The final note about categories being created in YNAB is slightly tangential but still earns its place by clarifying that this tool cannot perform creation.

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-value details need not be explained, and the sole parameter is fully described by the schema. Combined with annotations covering the safety profile, the description supplies the remaining essential context: the scope and filtering rules of the list.

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 documented in the schema, including the 'last-used' special value. The description adds no parameter-level detail, so the schema does the heavy lifting and a baseline 3 is appropriate.

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 (list category groups) and narrows the result set to groups where a new category can be created, with explicit exclusions for hidden, deleted, and system groups. This is clear enough to distinguish it from general listing tools, though it does not explicitly contrast with any sibling 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?

Usage is implied: an agent should call this when it needs valid category-group IDs for creating a new category. The note that new categories are created in YNAB itself hints this tool is read-only for lookup, but no explicit when-to-use or alternative-tool guidance is provided.

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 goes well beyond them: it discloses what each entry contains (the normalised merchant label), what is excluded (transfer payees and deleted payees), and where the data originates (banks), ending with an explicit prompt-injection warning to treat names as data. That is material behavioral context an agent cannot get from the annotations or 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?

The definition is front-loaded with what the tool lists before moving into semantics, exclusions and the safety note, and each sentence carries distinct information (definitions, duplication cause, entry shape, exclusions, security). It runs somewhat long for a simple list tool, but there is 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?

With an output schema present, the description need not explain return values, and it instead supplies the domain framing that would otherwise be missing: payee identity, merchant normalisation, exclusions and the untrusted-input caveat. Nothing an agent needs to call this correctly is absent.

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 limit, search and plan_id are already documented, setting the baseline at 3. The description adds only indirect meaning for search by explaining that entries expose both a label and a normalised merchant, but gives no extra syntax, format or defaulting 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 names a specific verb and resource ('List the payees of a plan') and immediately defines what a payee is, so the agent knows exactly what this returns. It differentiates implicitly from sibling tools by staying in the payee domain, but never explicitly names a sibling such as suggest_categories, which is the closest neighbor given the shared merchant/label logic.

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 a concrete use case ('see the names a bank import left behind') and explains why one shop may appear as several payees, which is real selection context. It also carves out a when-not via 'Renaming one is done in YNAB itself,' though it does not route the agent to any alternative tool by name.

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?

Annotations already cover read-only/idempotent safety, and the description adds substantial context beyond them: it reads the whole plan in three YNAB requests, tracking accounts are never pending, `categories` appears only on the first page, amounts are in currency units and negative for spending, and payee/memo are bank text to be treated as data, never instructions (explicit prompt-injection guidance). It also closes with 'Nothing is changed here,' reinforcing the read-only contract.

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 is front-loaded in the first sentence, then each subsequent sentence delivers a distinct operational fact: request cost, tracking-account edge case, suggestion semantics, transfer pairing, pagination caveat, units, and injection safety. Dense but no filler, and the closing safety statement is well placed.

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?

Despite an existing output schema, the description pre-empts the fields an agent must interpret (`suggestion`, `possible_transfer_with`, `categories`) and states the failure mode when `suggestion` is null. Combined with the read-only guarantee and account-scope caveat, an agent has everything needed to call it and act on the result correctly.

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 limit, cursor and plan_id are already fully documented, and the description adds no syntax or format detail for them. The only schema-adjacent nuance ('`categories` comes with the first page only') is about output pagination rather than a parameter, so this remains at the baseline 3.

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 of an embedded suggestion. This distinguishes it from generic siblings like find_transactions and list_scheduled_transactions, which operate on different slices of data.

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 the agent: 'Use this first when asked to classify or tidy up transactions.' That is clear when-to-use guidance, but it never names an alternative tool or a when-not-to-use condition (e.g. for already-categorized transactions, use find_transactions).

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