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

Annotations already declare the safety profile (idempotentHint=true, destructiveHint=false, openWorldHint=true), yet the description adds real behavioral detail the annotations cannot: it refetches and verifies every fingerprint before writing, refuses to auto-apply, and returns a pre-write undo manifest.

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 core action and its precondition, then the constraints, then the return guarantee. 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 mutating tool with no output schema and full schema description coverage, this covers the action, the precondition, the safety guarantees, the dry-run escape hatch, and the return artifact (undo manifest). Nothing an agent needs to invoke it safely 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; the description still adds meaning by explaining that suggestions must carry fingerprints that are verified and by characterizing dry-run as a pre-write validation step. It stops short of clarifying the budgetId/planId alias relationship or the 25-item cap context, which the schema already covers.

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 (applies) plus resource (explicitly supplied category suggestions) and immediately bounds the scope with the fingerprint-refetch precondition. It is clearly distinguishable from siblings like ynab_auto_assign and ynab_update_transaction.

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 negative guidance: it never auto-applies, approves, or calls TypeSafe, and it supports dry-run. It does not name the alternative tool (e.g. ynab_auto_assign) for auto-application, so the routing is implied rather than 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=false, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds one genuinely useful non-annotation fact — that the tool is deprecated — but says nothing about whether existing calls still work, whether behavior matches the bulk tool, or that the singular transactionId is a bulk-semantics wrapper. A 3 reflects real but thin added 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?

A single short sentence with the deprecation and the redirect front-loaded; there is no filler and nothing an agent must scroll past.

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 deprecated alias, the essential information an agent needs — don't use this, use that — is present and the schema is fully documented. It stops short of confirming whether the alias still functions or when it will be removed, which would fully close the loop.

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%, including the deprecated budgetId alias and the approved default/un-approve semantics, so the schema does all the work. The description adds no parameter guidance and notably does not flag the mismatch between a singular transactionId and the bulk target tool. Baseline 3 is correct.

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 identifies the tool as a deprecated alias and names the canonical sibling, ynab_bulk_approve_transactions, which combined with the title 'Approve Transaction (legacy)' makes the resource and action inferable. It does not directly state the verb+resource itself, relying on the title and sibling name to convey 'approve a transaction', but the sibling differentiation is explicit.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives an unambiguous directive: use ynab_bulk_approve_transactions instead. That is the strongest possible when-to-use / when-not-to-use routing signal an agent could get for a deprecated alias.

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 indicate this is a write operation (readOnlyHint=false, idempotentHint=false). The description adds valuable behavioral context: it mutates budget assignments, respects a maxTotal cap, and dryRun prevents changes. It doesn't mention side effects like overwriting existing assignments, but the dryRun disclosure and allocation rule provide solid transparency beyond 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?

Two sentences with no filler. The core behavior is front-loaded, and the dryRun safety note is placed second. Every word 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?

For a write tool with no output schema, the description explains the core behavior, the dryRun preview option, and the stopping condition. It doesn't describe the return value shape, but the absence of an output schema and the presence of dryRun make the behavior sufficiently clear for an agent to invoke it 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 the schema already documents all five parameters. The description adds context for dryRun ('see the plan without changing anything') and implies maxTotal's role, but doesn't add meaning beyond what the schema provides. 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 ('Distributes'), a clear resource ('Ready to Assign'), and a precise algorithm (largest shortfall first, until money runs out). It distinguishes itself from siblings like ynab_move_money and ynab_update_category_budget by describing an automated allocation behavior rather than a manual transfer or single-category update.

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 clearly explains what the tool does and when it applies (categories with monthly goals not fully funded), and mentions dryRun for previewing. It doesn't explicitly name alternative tools or state when not to use it, but the algorithm description makes the use case clear enough.

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 read-only, open-world, non-destructive behavior, but the description goes well beyond them: overdue occurrences are placed on day one and marked, twice-a-month schedules without a second date are approximated at +15 days, split schedules are counted leg by leg, and transfers net to zero or count as inflow/outflow depending on inclusion. It also discloses that limits cap event rows while balances always cover every day.

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 front-loaded with what is projected and what it returns, then proceeds through the accounting rules and alternatives. Every sentence carries behavioral information, though the single dense paragraph could be made easier to scan for such a rule-heavy tool.

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 forecasting tool with no output schema, it covers outputs, inclusion rules, overdue handling, approximation rules, transfer netting, limit behavior, and routing to alternatives. An agent has enough to call it correctly and interpret results without further questions.

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 already documents days, limit, planId, budgetId, and accountIds. The description adds genuine meaning beyond the schema for accountIds by explaining how included versus excluded accounts affect transfer accounting, and clarifies that the projection starts today in UTC. This is above the baseline 3 but not maximally additive since most parameter definitions are already well covered.

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: projects the combined account balance over the next N days from scheduled transactions, and enumerates the outputs (starting balance, scheduled events, end-of-day running balance, lowest point). An agent can distinguish this immediately from the sibling listing and cash-flow tools.

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 scopes the tool to scheduled transactions only and warns that unscheduled income/spending will not appear. It names two alternatives with their selecting conditions: ynab_cash_flow for past income versus spending, and ynab_list_scheduled_transactions to list the schedules themselves.

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=true, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds the one trait annotations cannot express: deprecation status. It stops short of saying whether calls still succeed and return the same payload, which would have made it 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?

A single clause with zero waste, and the deprecation verdict plus the redirect are both front-loaded. Nothing could be removed without losing the routing signal.

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 deprecated alias with no output schema, the description gives everything needed to avoid calling it. It could add one clause confirming the tool still works and mirrors ynab_plan_summary's parameters, but no critical decision is blocked.

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 every parameter (month, planId, budgetId, budgetVsActuals) is documented inline, including the deprecated budgetId alias. The description adds no parameter guidance, which is acceptable given the schema already carries it.

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 identifies the tool as a deprecated alias of ynab_plan_summary, which fully determines its behavior for an agent that knows the sibling. It doesn't restate the underlying verb/resource (budget summary for a month), relying on the name and title for that, so it is clear but not self-contained.

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 that instead' is an explicit exclusion plus a named alternative, exactly the routing decision an agent needs. There is no ambiguity about whether to call this tool or the successor.

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

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

Annotations already cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=true, openWorldHint=true), so the description only needs to add context. It usefully discloses that approvals are reversible via approved: false, but says nothing about partial failures in a bulk call, the 500-item cap, or the API/rate-limit cost of a single batched request.

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?

One sentence, zero filler, and the most decision-relevant bit (the un-approve capability) is parenthetically front-loaded.

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?

No output schema exists, so the description should ideally say what a bulk call returns on success or partial failure. With annotations and full schema coverage the core call is answerable, but an agent writing a mutation over up to 500 IDs is left guessing about error semantics.

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 every parameter (planId, budgetId alias, approved, transactionIds) is documented in the schema itself. The description only restates the approved:false behavior, adding no syntax or ordering information beyond the schema, which is the baseline-3 case.

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 (Approves / un-approves) and resource (one or more transactions) plus the key batching trait 'in a single API call'. That implicitly distinguishes it from the singular ynab_approve_transaction sibling, but it never names that sibling, so the differentiation is left to inference.

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?

There is no explicit 'use this when... use X instead when...' guidance. The bulk phrasing implies it should be preferred over ynab_approve_transaction for multiple IDs, but the agent has to derive that from 'one or more' rather than being told.

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=true and destructiveHint=false, so the safety profile is covered. The description adds a genuinely useful behavioral fact — totals come from YNAB's own monthly aggregates rather than recomputed transactions — but says nothing about return shape, currency units, or how months are bucketed when sinceDate and months overlap.

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 short sentences, front-loaded with the core purpose, then a provenance note, then the alt-tool routing hint. 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 no output schema, the description should hint at the shape of the result (a monthly series of income/spending totals). It conveys the concept of monthly aggregates but not the structure, and it does not explain how optional planId/budgetId aliasing affects the call in practice.

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 months, planId, budgetId, and sinceDate are already documented, including the default of 6 months and the sinceDate-overrides-months precedence. The description adds nothing beyond that; 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 resource and comparison (income versus spending, month by month) with the derived outcome (surplus). It also differentiates from the sibling ynab_balance_forecast, which covers projection, so an agent can route correctly 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?

Explicitly names the alternative (ynab_balance_forecast) and the condition that selects it (projected balance). It does not exclude adjacent siblings like ynab_spending_by_category or ynab_plan_summary, which also surface spending totals, so exclusions are incomplete.

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=false, idempotentHint=false, destructiveHint=false and openWorldHint=true, so the write/non-idempotent profile is covered. The description's additions (fuzzy matching, split sum rule, payee requirement) largely restate schema text and omit genuinely useful behavior such as duplicate re-submission risk or the account/category resolution failure mode, so it adds modest 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?

Four sentences, front-loaded with the purpose and then the mutually-exclusive parameter rules; each sentence carries information. Slightly dense with parenthetical-style alternatives but 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 15-parameter, mutation-heavy tool with no output schema, the description covers creation semantics, the id/name alternatives, payee requirement and split mechanics. It does not cover return shape or resolution failures for unmatched names, but annotations carry the safety profile so this is largely sufficient.

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 genuinely adds a cross-field constraint not captured by the schema: that either payeeId or payeeName must be provided, and that subtransactions replace (not supplement) categoryId/categoryName. This goes beyond per-parameter schema text.

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+resource ('Creates a new transaction in your YNAB plan'), making the operation unambiguous. It is implicitly distinguishable from ynab_update_transaction and ynab_delete_transaction by the verb, but never names or contrasts an alternative explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives clear conditional usage rules: account via accountId OR accountName, category via categoryId OR categoryName, payee required via payeeId OR payeeName, and subtransactions instead of a category when splitting. However, it offers no guidance on when to choose this over siblings like ynab_import_transactions or ynab_update_transaction.

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 annotation destructiveHint=true already signals destruction, but the description adds the important context that the action cannot be undone. However, it does not elaborate on downstream effects, such as impact on account balances or related scheduled transactions, so it adds only modest value beyond 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?

Two short sentences with no filler: the first states the action and target, the second warns about irreversibility. Every word earns its place, and the most important information is front-loaded.

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

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

For a simple destructive operation with one required parameter and annotations already declaring destructive/read-only behavior, the description is largely sufficient. It could mention what happens after deletion or what response to expect, but that is not essential for invoking the tool 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%, and the schema already documents transactionId as the target ID plus planId/budgetId fallback behavior. The description adds no parameter-level meaning beyond what the schema provides, so the baseline score of 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?

States a specific verb ('Deletes'), a specific resource ('a transaction'), and the scope ('from the plan'). This clearly distinguishes it from sibling tools like ynab_update_transaction or ynab_create_transaction. The purpose is immediately 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?

No guidance is given about when to choose this tool over alternatives, nor any conditions or prerequisites for deletion. The agent is left to infer that this is the destructive counterpart to update/create tools.

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/destructive, but the description adds substantial context beyond them: the result is heuristic, splits are counted through subtransactions, transfers and inflows are excluded, refunds are not netted, and already_scheduled only matches on payee name without comparing amounts. It also discloses a real performance trait ('reads the whole window from YNAB in one request, which is slow for a long sinceDate on a busy plan'), which an agent needs to pick sane arguments.

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 the sibling alternative are front-loaded, then return fields, then caveats and performance. Nearly every sentence carries actionable information, though the exclusion/refund/netting sentences could be tightened into one clause without losing content.

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?

There is no output schema, and the description fully enumerates the return fields (cadence, typical amount, yearly cost at latest amount, next expected date, stopped flag, already_scheduled). Combined with the heuristic warning, exclusion rules, and cost-of-call note, an agent has everything needed to call and interpret 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 genuine meaning by tying sinceDate to minOccurrences ('Yearly charges need a sinceDate far enough back to show minOccurrences of them') and explaining the exclusion filter that determines what the scan sees. It does not, however, add anything about amountTolerancePct's grouping semantics 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?

States a specific verb and resource ('Finds recurring outflows ... in transaction history') plus the matching criteria (payee, similar amount, regular spacing) and scope (whether or not they are scheduled in YNAB). It explicitly distinguishes itself from the nearest sibling, ynab_list_scheduled_transactions, so an agent can choose without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Names the alternative and the condition that selects it ('For the scheduled transactions set up in YNAB, use ynab_list_scheduled_transactions'), and adds a when-not caveat ('This is a heuristic: check the results before acting on them'). It also gives a concrete usage precondition: a sinceDate far enough back for yearly charges to reach minOccurrences.

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 safety (readOnly, non-destructive), and the description adds substantial non-obvious behavior on top: totals always cover every match regardless of limit, totals include inter-account transfers like credit card payments, and split transactions match leg-by-leg without categoryId/payeeId but as a full parent row with them. This is exactly the context annotations cannot express.

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 is front-loaded in the first sentence and every subsequent sentence carries real information about filters, totals or splits. It is a dense run-on paragraph, though, with the split-transaction caveat trailing at the end where it is easy to miss.

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 15-parameter read tool with no output schema, the definition covers the filter precedence, the date/type defaults, search-triggered aggregate behavior and the split-matching edge case. An agent can call this correctly and predict what the totals contain without further documentation.

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 field-level meaning is already documented; the description adds genuine cross-parameter semantics the schema cannot encode, namely the mutual exclusion and precedence order among accountId, categoryId and payeeId, and how categoryId/payeeId change split-row matching. Those additions push it above 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 with scope: gets transactions from a plan, with date, type and filter scope spelled out. It never names a sibling to use instead, so an agent facing ynab_get_unapproved_transactions or ynab_spending_by_category has to infer the boundary, which keeps it out of the top band.

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 usage rules: at most one of account/category/payee may be used, and if several are supplied only the first in that order applies. It also explains what triggers totals and when totalsOnly is appropriate (categoryId plus a year of dates). No explicit when-not-use or sibling routing, 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 safety (readOnlyHint=true, destructiveHint=false, idempotentHint=false), so the bar is lower; the description adds the deprecation status, which is not in annotations and is genuinely useful. However, it does not state whether the alias still resolves, whether it forwards the same filters, or whether behavior differs from the canonical 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?

One short sentence, front-loaded with the deprecation status and followed immediately by the actionable redirect. Nothing superfluous for a stub of this kind.

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 deprecated alias with a fully documented schema and annotations carrying the safety profile, the description gives the one fact an agent needs: don't call this, call ynab_get_transactions. The only gap is whether invoking it still produces results and whether those results are filtered to unapproved transactions.

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 all three parameters are optional, with the schema already explaining planId defaults, the budgetId alias, and the ISO date format. The description adds nothing about parameters, 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?

The description states plainly that this is a deprecated alias and names the replacement, ynab_get_transactions, which distinguishes it from the sibling tool it shadows. It does not say what the tool actually returns if invoked (unapproved-only, as the name implies, versus the full list the alias points to), so the purpose is clarified only at the deprecation level.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives an unambiguous directive: use ynab_get_transactions instead. That is an explicit when-not-to-use plus the correct alternative, which is exactly what usage guidance should do for a deprecated stub.

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 mark this as non-read-only and non-idempotent; the description adds that it triggers an import from connected financial institutions, which is useful. However, it does not disclose potential side effects beyond the import (e.g., rate limits, network delays, or whether existing pending transactions are overwritten), so the added transparency is modest.

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 two sentences with no filler. The first sentence front-loads the core action and scope; the second adds a clarifying analogy to the YNAB app. Every word 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?

For a tool with two optional parameters and no output schema, the description explains the action and scope, but it does not indicate what the caller receives after the import (e.g., transaction details, count, or confirmation status). This is a meaningful gap because the absence of an output schema leaves the agent guessing about the return value.

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 input schema provides 100% description coverage for planId and budgetId, including defaulting and deprecation notes, so the description does not need to compensate. The description adds no parameter-specific semantics, which is appropriate given the schema completeness; 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 description states a specific verb ('imports'), a precise resource ('available transactions on all linked accounts for the plan'), and clarifies the action as equivalent to clicking Import in the YNAB app. This clearly separates it from sibling tools like create_transaction, get_transactions, and approve_transaction.

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 implies the tool is used to synchronize external bank data by comparing it to the app's Import button, but it does not explicitly state when to use it versus alternatives or when not to use it. No exclusions or alternative tool names are mentioned, so usage guidance is only implicit.

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=true and destructiveHint=false, so the main safety profile is covered. The description adds that all accounts in a plan are returned and that IDs are the useful output, but it does not disclose pagination, ordering, or closed-account handling beyond the schema's includeClosedAccounts field.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, no filler, with the action and resource stated first and the use case added as a second sentence. Every sentence earns its place.

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

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

For a simple read-only list operation with optional parameters, the description plus fully-covered schema and annotations provide everything an agent needs to invoke it correctly. No output schema is available, but the stated use case (account IDs) covers the expected return value.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema fully documents planId, budgetId, and includeClosedAccounts. The description itself adds no parameter-level detail, but the baseline of 3 applies because the schema carries the param semantics.

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 uses the specific verb 'lists' with a clear resource ('all accounts in a plan'), and immediately states the practical purpose of finding account IDs for creating transactions. This distinguishes it from sibling tools like ynab_list_payees, ynab_list_categories, and ynab_get_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?

It gives clear context for when to use the tool: before creating transactions to look up account IDs. It does not explicitly name alternative tools or state when not to use it, but the use case is specific enough to guide selection.

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=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds the deprecation status, which is genuinely the most important behavioral fact here, but says nothing about whether calls still succeed, return empty data, or redirect.

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?

A single short sentence that front-loads the deprecation and the remedy. Zero waste.

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 deprecated alias with full schema coverage, routing the agent to the successor is the essential content. Only the runtime behavior of calling the deprecated endpoint (error vs. empty result) is left unstated.

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 explain and the baseline applies. No misleading parameter information is present.

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?

It states the tool's identity precisely as a deprecated alias of ynab_list_plans, which is the only purpose a deprecated stub can have. It doesn't independently describe listing budgets, but the pointer to the live tool covers the intent.

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 directs the agent to use ynab_list_plans instead, naming the alternative in the sibling list. There is no ambiguity about when to call this versus the replacement.

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

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

Annotations already cover the read-only, non-destructive nature via readOnlyHint=true and destructiveHint=false. The description adds meaningful behavior: categories are returned in groups and all categories are included. It does not cover edge cases like archived or hidden categories, but the annotation coverage lowers the burden.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with no filler. The core listing behavior is front-loaded, followed by a practical use case. It does not repeat annotations or schema details unnecessarily.

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

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

For a simple read-only list tool with two optional and fully documented parameters, the description plus annotations are sufficient. The output behavior is described as grouped categories containing IDs, and the safe read-only profile is clear. Nothing critical is missing for correct invocation.

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 planId and budgetId are already fully documented including defaults and the deprecation alias. The description does not add parameter-level meaning beyond the schema, so the baseline score of 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 clearly states it lists all categories in a plan, grouped by category group. This specific verb+resource combination distinguishes it from sibling tools like ynab_list_accounts and ynab_list_payees. The mention of finding category IDs makes the exact output purpose 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 explicit usage context: useful for finding category IDs when creating transactions or updating budgeted amounts. It does not explicitly name alternatives or state when not to use the tool, but the scenario-based guidance is clear enough for 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 readOnly, non-destructive and openWorld, so safety is covered. The description adds real context beyond that: the result covers every month since the plan began and returns raw summary fields rather than aggregates. It does not mention ordering or whether results are paginated, which is the remaining gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, no waste, with the scope-and-fields statement front-loaded ahead of the disambiguation pointer. Every clause carries information an agent needs.

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

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

With no output schema, the description usefully names the returned fields and the time scope, and both optional params are covered by the schema. Only minor behavioral details (ordering, month format, pagination) are unstated.

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 both parameters (planId and its deprecated budgetId alias, with the YNAB_PLAN_ID default) are fully documented in the schema. The description says nothing about parameters, so baseline 3 applies — the schema does all the work.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource (lists every plan month since the plan began) and enumerates the fields returned (income, budgeted, activity, Ready to Assign, age of money, note). It also names the sibling it is not (ynab_cash_flow), so an agent can distinguish it without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit exclusion with the alternative: for income-versus-spending questions over recent months, use ynab_cash_flow instead. What is missing is a positive statement of when this tool is the right pick (e.g. historical month-by-month raw figures), leaving half the routing decision implied.

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=true and destructiveHint=false, covering safety. The description adds that it lists 'all' payees, which is a useful scope note, but it doesn't disclose any behavioral quirks like pagination or performance. The bar is lower due to annotations, so a 3 is appropriate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences with no filler. The core action is front-loaded, and the usage hint is placed second. Every word 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?

For a simple read-only list tool with optional parameters and no output schema, the description adequately covers purpose and usage. It implicitly conveys that payee IDs are returned ('useful for finding payee IDs'), but it could be more explicit about the exact return shape. Still, it's largely complete.

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 schema has 100% description coverage for both parameters (planId and budgetId), and the description adds no additional parameter details. With high schema coverage, the baseline is 3, and no extra value is provided 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 clearly states the tool lists all payees in a plan, which is a specific verb and resource. It also explicitly mentions its utility for finding payee IDs when creating transactions, distinguishing it from sibling tools like ynab_list_accounts or ynab_list_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?

The description provides a concrete usage context: find payee IDs for creating transactions. While it doesn't explicitly mention alternatives or when not to use it, the purpose is clear enough and the sibling set is large but the tool's specific role is obvious.

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=true and destructiveHint=false, so the safety profile is covered. The description adds only that it returns all available plans, which is consistent but does not add meaningful behavioral detail beyond 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?

The description is a single sentence with no wasted words. It front-loads the action and resource immediately, which is ideal for a simple no-parameter tool.

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-only list tool, the description is sufficient: it states the output scope ('all available plans') and source. There is no output schema, but the description's phrasing adequately conveys that the result is a list of plans without requiring deeper return-value explanation.

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 has zero parameters, so the input schema is empty and there is no semantic burden on the description. The baseline of 4 applies because no parameter documentation is needed.

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 uses a specific verb ('Lists') and resource ('all available plans from YNAB API'), clearly identifying the scope. It is distinguishable from siblings like ynab_plan_summary because it explicitly says 'lists all available plans' rather than summarizing a single plan.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided about when to use this tool versus alternatives such as ynab_plan_summary. The description merely states what the tool does, leaving the agent to infer selection criteria without any exclusions or comparisons.

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=true, destructiveHint=false, openWorldHint=true and idempotentHint=false, so the safety profile is covered. The description does not contradict them and adds the conceptual split between scheduled objects and historical recurring charges, but says nothing about pagination, ordering, whether inactive/completed schedules are included, or auth/plan requirements.

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 short sentences, front-loaded with the core action, then two routing pointers. Every sentence earns its place with zero 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?

There is no output schema, so the description is the only place an agent could learn what a scheduled transaction record contains (date, amount, frequency, account, next occurrence) or how results are ordered. For a simple zero-required-param list tool this is adequate, but the return shape remains undocumented.

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 explains planId defaults to YNAB_PLAN_ID and that budgetId is a deprecated alias. The description adds no parameter guidance, so the baseline 3 applies since the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Lists') and resource ('scheduled transactions set up in YNAB'), and immediately distinguishes itself from ynab_detect_recurring (transaction-history recurring charges) and ynab_balance_forecast (projection). An agent can differentiate it from ynab_get_transactions and the recurring sibling 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?

Names two alternatives with explicit conditions for choosing each ('To find recurring charges in transaction history... use ynab_detect_recurring', 'For a projected balance, use ynab_balance_forecast'). It does not state the positive condition for this tool (e.g., 'use when the user wants upcoming scheduled entries'), but the contrast makes the routing clear.

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 goes well beyond the annotations by disclosing the non-atomic implementation: it reads both categories, rewrites both budgeted amounts, and explains the partial-failure response. This is exactly the kind of behavioral detail an agent needs and that annotations cannot express.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences: the first states the core action and typical use; the second adds only high-value implementation and failure-mode details. There is no filler, repetition, or unnecessary background.

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 mutation tool with six fully documented parameters, the description provides the missing behavioral context: non-atomicity, partial-failure reporting, and the cover-overspending purpose. The only omitted detail is the exact success return shape, but the description's failure-mode disclosure compensates and no output schema is defined.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents month format/default, positive amount, plan/budget IDs, and category IDs. The description adds no new parameter-level semantics beyond restating the transfer direction, so the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and direct object: 'Moves budgeted money from one category to another in a given month.' It also clarifies the motivating use case, covering overspending, and distinguishes itself from a plain category budget update by noting there is no single YNAB move endpoint.

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?

'Typically to cover overspending' gives a concrete triggering context, and the move-vs-set semantics imply when this tool is appropriate rather than a simple budget update. It does not explicitly name alternatives or exclusions, but the intended usage is clear enough.

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 a read-only, non-destructive operation. The description adds useful behavioral context beyond that: it explains the default summary focus and details what appears in the optional budgetVsActuals block, including the fact that overall totals exclude Credit Card Payments.

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 dense but front-loaded and every sentence carries useful information about scope or output. It avoids filler, though the main sentence is long and could be slightly easier to scan.

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 no output schema and annotations covering safety, the description does most of the work by explaining the default summary behavior and the optional budgetVsActuals output structure. It leaves some detail unspecified, such as the exact shape of the default summary, but it is complete enough to call the tool 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 coverage is 100%, so the schema already documents the parameters. The description still adds meaningful semantics for budgetVsActuals, clarifying the fields returned and defining variance as budgeted plus activity, where below zero means overspending.

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: get a plan summary for a month, with emphasis on overspent and positive-balance categories. It is clear what the tool does, but it does not explicitly differentiate itself from siblings such as ynab_budget_summary or ynab_spending_by_category.

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 implies usage by mentioning overspent categories and positive balances, and it gives a condition for enabling budgetVsActuals. However, it does not say when to use this tool versus alternatives or when not to use it.

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 past the readOnly/destructive annotations: it discloses that splits are rolled through subtransactions, that own-account transfers are excluded, and that totals are gross outflows where refunds are not netted — an accounting caveat that will change how an agent interprets the numbers. It also flags that partial and in-progress months are listed but excluded from averages and change_pct.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Four sentences, front-loaded with the core operation before the accounting caveats and the optional monthly mode. Slightly dense — the last sentence restates material already in the months/monthly schema descriptions — but no sentence 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 no output schema, the description usefully names the return concepts (per-category totals, monthly_totals, average_monthly, change_pct) and the exclusion rules that govern them. It stops short of describing the top-level response envelope or how categories with zero spend are represented, which an analytics tool of this shape could reasonably state.

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's own monthly/sinceDate/untilDate descriptions are actually more detailed than the prose here, so the description adds little parameter meaning beyond a restatement of the monthly aggregation semantics. Baseline 3 is correct when the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Names a specific verb and resource (totals spending per category) plus the aggregation window and sort order ('biggest spend first'), which is far more than a restatement of the title. It never names the obvious alternative, ynab_spending_by_payee, so the category-vs-payee split must be inferred from the name rather than stated.

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 rather than stated: the description covers defaults, the limit pairing hint ('With many categories, pair it with limit'), and how months/sinceDate interact, but never says when to pick this tool over ynab_spending_by_payee, ynab_cash_flow, or ynab_budget_summary. An agent must infer the selection from the resource noun.

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 read-only annotations by disclosing key semantics: splits are counted through subtransactions, internal transfers are excluded, totals are gross outflows with refunds/inflows not netted, and monthly mode adds month-by-month figures with specific treatment of partial months. This is exactly the behavioral context an agent needs to interpret results correctly.

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 purpose in the first sentence, then layers in the critical behavioral caveats and the monthly option. Every sentence earns its place; there is no filler or repetition of the schema beyond a concise monthly summary.

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 an aggregation read tool with no output schema, the description covers purpose, exclusions, gross-vs-net semantics, and monthly output behavior well. It still does not describe the base return shape (e.g., payee name and total fields) or pagination/limit behavior, which would fully complete the picture.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all 7 parameters in detail, including monthly, months, sinceDate, untilDate, limit, and planId/budgetId. The description only summarizes the monthly behavior and does not add parameter semantics beyond what the schema provides, so 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?

States a specific verb and resource ('Totals spending per payee') plus scope ('over a date range, biggest spend first') and the merchant-spend angle. It contrasts implicitly with category activity but does not name the sibling ynab_spending_by_category, so sibling differentiation is present but not explicit.

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 implies when this tool is useful (merchant/payee-level spending) and notes that totals can differ from a category's activity. However, it gives no explicit when-to-use/when-not-to-use guidance or direct routing to alternatives such as ynab_spending_by_category.

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=false, idempotentHint=true, and destructiveHint=false, so the safety profile is carried structurally. The description adds the most consequential behavioral fact – that this overwrites the total rather than adding to it – which explains the idempotency. It does not cover auth requirements or failure 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?

Two sentences, zero waste, with the highest-risk semantic caveat front-loaded and the alternative routing delegated to sentence two.

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 mutation tool with annotations covering safety, full schema coverage, and no output schema, the description supplies the two facts an agent most needs: absolute-set semantics and sibling routing. Minor omission – no mention of what the write affects or returns – but nothing essential is missing for correct invocation.

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%, including the fact that 'budgeted' sets the total rather than an increment, so the description's '(not an increment)' clause largely restates the schema. Baseline 3 is appropriate since the schema does the heavy lifting on month format, planId defaults, and deprecation.

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 (sets), resource (budgeted amount), and precise scope (one category, one month), and explicitly disambiguates the semantics with '(not an increment)'. An agent can distinguish it from ynab_move_money without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Names the alternative tool (ynab_move_money) and the condition that selects it (moving money between categories). Combined with the explicit 'not an increment' exclusion, both the when-to-use and when-not-to-use cases 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?

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavioral context beyond them: patch semantics for omitted fields and the permanent restriction that YNAB cannot re-split an already-split transaction. It does not mention auth/permission requirements or error behavior on an invalid transactionId.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, no filler, and the most load-bearing fact (only transactionId required; only send what you want changed) is front-loaded ahead of the edge case about splitting.

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 mutation tool whose annotations already carry the safety profile and whose schema is fully documented, this covers the mutation model, the split workflow and its key limitation. Minor gaps remain around permissions and failure modes on a bad transactionId, but nothing essential to invoking it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3 and the schema already documents all 14 parameters including the split sub-shape. The description adds a usage rule the schema does not state plainly - supply only the fields you intend to change, and omit categoryId when passing subtransactions - which meaningfully affects how parameters are passed.

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 ("Updates an existing transaction") and immediately clarifies the patch semantics, so an agent understands this is a partial mutation rather than a replace. It never names the sibling it is distinguished from (ynab_create_transaction, ynab_delete_transaction, ynab_approve_transaction), so it stops short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

"All fields except transactionId are optional - only provide fields you want to change" gives clear when-to-use guidance for a patch tool, and the subtransactions sentence states the condition and the one hard exclusion (cannot re-split an already-split transaction). No explicit routing to alternative siblings (e.g. approve vs update), which keeps it below 5.

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