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

Annotations already provide the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=true), and the description consistently identifies the core operation as approving an existing transaction. It adds little beyond that effect, such as noting that setting 'approved' to false would unapprove, but there is no contradiction with 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, front-loaded sentence that states the action and resource with no filler or repetition of the title. Every word earns its place, and the structure is appropriately sized for a simple mutation 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 simple one-transaction approval tool with strong annotations and fully described parameters, the description provides enough basic context to invoke the tool correctly. It does not mention return values or selection guidance against the bulk-approve sibling, but those are minor gaps given the tool's simplicity.

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 covers all 4 parameters with 100% description coverage, including the required transactionId, the default and deprecated alias for planId, and the approved boolean. Since the schema already documents each parameter, the description does not need to compensate.

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 action verb ('Approves') and resource ('existing transaction in your YNAB plan'), making it clear this is an approval mutation rather than a creation, deletion, or listing tool. It does not explicitly name or distinguish the sibling ynab_bulk_approve_transactions, relying on the singular phrasing to signal one-record scope.

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 for approving an existing transaction, but it offers no explicit guidance about when not to use it or when to prefer alternatives such as ynab_bulk_approve_transactions or ynab_update_transaction. There are no clear exclusions or conditions beyond the word 'existing'.

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 declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds no behavioral context beyond the legacy alias, which is already reflected in the title 'legacy'.

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 extremely short, but this is under-specification rather than effective conciseness. A single deprecation note cannot replace a functional tool description.

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?

The schema and annotations provide good invocation details, but the description is missing the core purpose of the tool. An agent cannot reliably decide when to invoke this tool from the given information.

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 each parameter is already documented in the schema. The description contributes nothing extra to parameter understanding, so the baseline score 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 only says 'Former name of ynab_plan_summary'; it never states what the tool does. An agent cannot tell from this description that it summarizes a budget, month, or 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?

The description names ynab_plan_summary as the current counterpart, which implies this is a legacy alias. However, it does not explicitly say when to use this tool versus its siblings or when to prefer 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 carry the safety profile — readOnlyHint=false (mutating), idempotentHint=true, destructiveHint=false — so the bar is lower. The description adds the batch-execution trait ('all in a single API call') but discloses nothing about partial-failure semantics, behavior when some IDs are invalid or already approved, or the response shape. No contradiction with 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 zero filler. The first fronts the core purpose, the second names the required input and the efficiency benefit ('single API call'). 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 batch mutation, the combination is adequate: annotations cover mutation/idempotency/safety, the schema documents all parameters (including min/max items), and the description covers the batching behavior. The residual gaps — unspecified return value and atomicity on partial failure — are minor for this action and 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 planId, budgetId, and transactionIds all already have descriptions in the schema; the baseline of 3 applies. The description's phrase 'array of transaction IDs' merely echoes the schema's own parameter description without adding format detail, limits, or the planId/budgetId relationship.

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 ('Approves') and resource ('multiple transactions'), and immediately scopes the action with 'at once' and 'in a single API call,' which implicitly separates it from the singular sibling ynab_approve_transaction. The purpose is unmistakable, though differentiation is implicit rather than explicit (no sibling is named).

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 bulk framing ('multiple transactions at once,' 'single API call') tells an agent this is the batched path for approving transactions, so usage is implied. However, there is no explicit when-not-to-use guidance and no named alternative, such as pointing to ynab_approve_transaction for a single ID or noting the 500-item ceiling in prose.

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 and non-destructive behavior. The description adds a meaningful detail by saying totals come from YNAB's monthly figures rather than re-adding transactions, but it stops short of describing response format, currency, or any other runtime behavior.

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; the core purpose is front-loaded and the second sentence justifies why the tool exists rather than relying on transaction-level data.

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 optional parameters fully documented and safety covered by annotations, the description supplies enough conceptual output detail (month-by-month income, spending, surplus) to invoke the tool confidently. It does not show explicit response shape, but no output schema exists and the tool is simple.

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?

Input schema descriptions cover all four parameters at 100%, so the description does not need to repeat parameter details. It adds no parameter-specific meaning beyond confirming the monthly framing.

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 identifies the resource as monthly income versus spending and the purpose is to reveal a surplus. It is distinguishable from transaction-listing and category/payee breakdown siblings by its month-level cash-flow framing, though it never names an alternative.

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 phrase 'so you can see whether you are running a surplus' gives a concrete use case. It does not enumerate when-not-to-use conditions or point to a specific sibling, but the context is clear enough for 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=false (mutation), destructiveHint=false, and openWorldHint=true (fuzzy matching). The description's mention of 'fuzzy-matched' is redundant with openWorldHint. It does not add new behavioral context such as side effects (e.g., payee auto-creation is noted only in schema) or operational requirements. Since the bar is lower with annotations present, but the description contributes minimal additional behavioral insight, a score of 2 reflects the low added value beyond already available structured data.

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 redundant words. It front-loads the primary action and then immediately covers the key parameter alternatives and the mandatory payee condition. Every sentence adds critical guidance, and there is zero fluff or repetition of schema details.

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 14 parameters and a thorough schema (100% coverage), the description does not need to enumerate each parameter. It covers the essential decision points: account/category/payee alternatives, the mandatory payee requirement, and the fuzzy matching behavior. The singular 'a new transaction' implies single-record creation, distinguishing it from bulk import. No output schema exists, so return values are not required. The description is complete for the core usage, though it omits edge cases like resolution of ambiguous fuzzy matches.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful value by clarifying the alternative ways to specify account (accountId/accountName) and category (categoryId/categoryName), and by declaring that payeeId or payeeName must be provided – a requirement not present in the schema's required list. This helps the agent understand the mutually exclusive parameter groups and the hidden mandatory field, pushing the score above baseline.

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 action ('Creates a new transaction') and the resource ('your YNAB plan'), making the tool's purpose unambiguous. It also highlights the flexibility of using IDs or names for account/category, which distinguishes it from bulk import or update tools. The verb and resource are specific enough to differentiate from siblings like ynab_import_transactions or ynab_update_transaction without needing to inspect 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?

The description provides clear context on how to specify account, category, and payee (via ID or name), and explicitly states that either payeeId or payeeName must be provided – a critical usage constraint not enforced by the schema. However, it does not explicitly contrast with ynab_import_transactions for bulk creation or mention when to avoid using this tool. The guidance is clear for the primary use case but lacks explicit exclusions.

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 convey read-only and non-destructive behavior. The description adds only the existence of filters, not behavioral details such as default limit behavior, ordering, whether filters combine, or that unapproved transactions require a filter. No contradiction with annotations, but little added transparency.

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 the core action front-loaded. No redundant or promotional language; every sentence contributes to understanding the 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 an 8-parameter tool with no output schema, the description is thin: it omits default behavior, return shape, and sibling-tool routing. However, the schema covers parameter formats and defaults, and annotations cover the safety profile, so the definition is minimally viable.

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

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

Schema description coverage is 100%, so the baseline is 3. The description summarizes filter categories like date range and account, but does not add meaning beyond the schema's per-parameter descriptions.

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 ('Gets') and a concrete resource ('transactions from a plan'), then enumerates the supported filter dimensions. It is clearly understandable, but it does not explicitly distinguish itself from sibling tools like ynab_get_unapproved_transactions or ynab_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?

The description implies this is the general transaction-listing tool, but it gives no explicit guidance on when to choose it over alternatives. It does not mention exclusions or point to specialized siblings such as ynab_get_unapproved_transactions for unapproved-only queries.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds that it returns every unapproved transaction and can be date-scoped, but discloses no further behavior such as pagination or output shape.

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 with the main action and the sole optional modifier, front-loaded and free of filler. 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 operation with a rich schema and safety annotations, the description is sufficiently complete. It omits output details and explicit sibling distinctions, but those are minor given the schema already handles parameter context.

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

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

Schema coverage is 100% and the schema entries already document planId, the deprecated budgetId alias, the ISO date pattern, and default behavior. The description adds no parameter meaning beyond what the schema provides, 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 names a specific verb and resource: 'Gets every unapproved transaction in a plan', which immediately separates it from sibling ynab_get_transactions by the 'unapproved' qualifier. It also states the optional date filter without ambiguity.

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 intended use is clear: this tool is for unapproved transactions, optionally filtered by date, which is a concrete context. It does not explicitly say 'use ynab_get_transactions for all/approved transactions', so it stops short of full alternative 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 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 and destructiveHint=false, and the description adds no behavioral context beyond the deprecation note. It does not mention what happens when called, return format, or any side effects. The description's only behavioral implication is that the tool is legacy, but it does not elaborate on how it behaves. Given annotations exist, the description adds minimal value here.

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 conveys the essential information (the legacy name and its replacement). It is front-loaded and contains no superfluous words, making it highly concise and structured.

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 legacy alias, the description provides the critical information—the canonical tool to use instead—making it functionally complete for deprecation purposes. However, it omits any description of what the tool actually does, which could be necessary if the agent still needs to invoke it directly. Given its redirect nature, this is a minor gap.

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

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

The tool has zero parameters, so the schema is trivially complete (100% coverage). The description does not need to explain parameters, and it doesn't. Per the baseline for 0 parameters, a score of 4 is appropriate since there is nothing to clarify.

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 it is the 'Former name of ynab_list_plans,' which clearly identifies it as a legacy alias and implies its function mirrors that of the replacement. However, it does not explicitly state what the tool does (e.g., 'lists budgets'), leaving the agent to infer behavior from the sibling tool's name. It distinguishes itself from siblings by referencing the canonical tool but lacks a direct statement of purpose.

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 explicitly names the alternative tool (ynab_list_plans) and indicates this is the former name, effectively telling the agent to use the replacement instead. This is clear, actionable guidance on when to use this tool versus its successor, with no ambiguity.

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 cover the safety profile (readOnlyHint=true, destructiveHint=false), and the description adds that each month contains budgeting-status summary information. It does not mention pagination, ordering, or plan scoping details, but for a straightforward read-only list tool the combination of annotations and description is adequate. No contradiction with 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 two short sentences with no filler, front-loading the action ('Lists all plan months') before clarifying the content of each month. 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 tool with optional parameters and no output schema, the description provides the essential context: all plan months are returned, each with summary budgeting information. It could mention ordering or pagination, but the schema covers parameter defaults, so the definition is nearly 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?

Schema description coverage is 100%, so the schema fully documents planId and budgetId, including the default to YNAB_PLAN_ID and the deprecated alias behavior. The tool description adds no parameter-specific information, but the baseline of 3 applies because the schema carries the load.

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 starts with a specific verb and resource: 'Lists all plan months', making the operation and scope explicit. The second sentence clarifies the return content (budgeting status summaries), which distinguishes this tool from sibling list tools like ynab_list_accounts and ynab_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?

The description implies this tool is for retrieving plan months and their summary budgeting status, but it does not name alternatives or state when not to use it. However, for a simple list operation, the context is reasonably inferred from the description.

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 and destructiveHint=false, so the safety profile is covered. The description adds modest behavioral detail by saying 'all' scheduled transactions are returned, but it does not go beyond what the name and annotations already suggest, such as absence of filtering or pagination behavior.

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, front-loaded sentence with no filler. Every word earns its place: 'Lists' states the action, 'scheduled (recurring)' defines the resource type, and 'in a plan' gives the scope.

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, the description combined with the annotations and fully documented schema is almost sufficient. It is slightly incomplete because there is no output schema and the description does not note what fields the returned scheduled transactions will contain, but the tool name and simple nature make the return value predictable.

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 and budgetId, including the default and deprecation alias. The description adds no parameter-specific meaning, which fits the baseline of 3 when the schema carries the burden.

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') with a clear resource ('scheduled (recurring) transactions') and a scope ('in a plan'). The parenthetical '(recurring)' disambiguates this from regular or unapproved transaction listing siblings, so an agent can distinguish it 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?

The phrase 'scheduled (recurring)' implies this is the tool for recurring/scheduled transactions, but it does not explicitly state when to use it instead of ynab_get_transactions or ynab_get_unapproved_transactions, nor does it mention any exclusions. Usage context is implied rather than stated.

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 indicate read-only and non-destructive behavior. The description adds context about the month scoping and the category-level highlight focus, but it does not disclose more operational details like response structure or any limitations. No contradictions with 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?

A single concise sentence communicates the operation, scope, and key output signals with no redundant wording. All content earns its place and the main purpose 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 read-only tool with three optional parameters already fully documented in the schema, the description adequately explains what the summary highlights. The lack of an output schema is partially compensated by the description's mention of overspent and positive-balance categories, though exact return fields are not specified.

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 full 100% coverage of all three optional parameters with detailed descriptions and defaults. The tool description adds no parameter-specific meaning, so the schema carries the burden and the baseline score 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 clearly states the tool retrieves a month-specific plan summary and specifies the key outputs (overspent categories and positive-balance categories). It is distinct from obvious siblings like ynab_budget_summary by focusing on plan month and category health, though it does not explicitly name alternatives.

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 to use it—when a month-level plan summary is needed with attention/positive category highlights. It provides no explicit guidance on when not to use it or which sibling tool might be more appropriate for other summary needs.

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 the tool read-only and non-destructive, and the description adds meaningful behavioral details: split transactions are counted via subtransactions, and transfers between own accounts are excluded. These nuances significantly affect results and are not inferable from 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?

Two dense, purposeful sentences with no filler. The core behavior and ordering are front-loaded, and the two edge-case clarifications are packed into a single second sentence.

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?

The description covers the essential behavior, ordering, split handling, and transfer exclusion, which is enough for an agent to select and invoke the tool correctly. There is no output schema, but the return concept is simple and obvious from the title; explicitly describing response fields would push this to a 5.

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 documents all five parameters with full descriptions and defaults, so the description does not need to repeat them. It adds no parameter-specific meaning beyond what the schema already provides, matching the baseline for high schema coverage.

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's action ('Totals spending per category over a date range') and ordering ('biggest spend first'), naming the exact resource and operation. It also distinguishes itself from the sibling ynab_spending_by_payee by explicitly focusing on categories rather than payees.

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 establishes clear analytical context: this is for category-level spending totals over a date range, which lets an agent separate it from transaction-listing and mutation tools. It does not explicitly name alternatives or say when not to use it, so it falls just short of a 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context beyond annotations: it explains how splits are handled (counted through subtransactions) and that transfers between own accounts are excluded. This is useful edge-case disclosure that helps an agent predict results. It doesn't mention pagination or output format, but with no output schema and read-only semantics, the key behaviors are covered.

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 zero waste. The core function is front-loaded, and the edge-case behaviors (splits, transfers) are packed into the second sentence. 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 read-only aggregation tool with 100% schema coverage and no output schema, the description is nearly complete. It covers the core function, the sort order, the split handling, and the transfer exclusion. The only minor gap is that it doesn't describe the return shape (e.g., whether it returns a list of payee names with amounts), but with no output schema and a clear aggregation description, this is a small gap.

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

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

Schema description coverage is 100%, so the schema already documents all parameters (limit, planId, budgetId, sinceDate, untilDate) with defaults and formats. The description adds the conceptual meaning of 'limit' (top N payees by spend) and the date range concept, but doesn't add much beyond the schema. Baseline 3 is appropriate 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?

The description clearly states the tool's function: 'Totals spending per payee over a date range, biggest spend first'. It also adds a helpful real-world framing ('where the money actually goes by merchant') and distinguishes it from related tools by mentioning specific exclusions (splits counted via subtransactions, transfers between own accounts excluded). This is a specific verb+resource with clear scope.

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 to use this tool: when you need spending totals by merchant/payee over a date range. It doesn't explicitly name alternatives or say when not to use it, but the sibling list includes ynab_spending_by_category and ynab_cash_flow, and the description's focus on payees/merchants makes the use case clear. It lacks explicit exclusions or alternative routing, so it doesn't earn 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?

The description states that the tool mutates budgeted amounts, which is consistent with readOnlyHint=false and idempotentHint=true and does not contradict the annotations. It adds little beyond the core operation, such as effects on available amounts, permissions, or return behavior, but the annotations already cover the basic safety profile.

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 only two sentences and front-loads the core operation. It is concise and easy to scan, though the second sentence's overlap with ynab_move_money makes it slightly less crisp than it could be.

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 update operation with fully documented parameters and informative annotations, the description is sufficiently complete for an agent to select and invoke the tool. The main missing element is explicit guidance about when to prefer ynab_move_money, but this is a minor gap given the straightforward purpose.

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 all five parameters are already well documented, including the critical fact that budgeted sets the total amount rather than an increment. The tool description adds no parameter-specific meaning beyond the general allocation/move-money framing, 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 names a specific verb and object: it updates the budgeted amount for a category in a specific month. It is clear about the core operation, but it does not explicitly distinguish itself from sibling tools like ynab_move_money, and the phrase 'move money between categories' blurs that boundary.

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 direct use case: 'Use this to allocate funds to categories or move money between categories.' However, it does not mention alternatives or exclusions, which matters because ynab_move_money exists as a sibling and may be the more appropriate tool for cross-category moves.

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 that the operation is non-read-only and non-destructive. The description adds useful behavioral context beyond that: it is a partial update where omitted fields are left unchanged. There is no contradiction with 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 focused sentences with no superfluous content. The core purpose is front-loaded, and the parameter guidance is stated immediately and clearly.

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 13 parameters, complete schema descriptions, and annotations covering idempotence and destructive behavior, the description is sufficiently complete. The only minor omission is the return value, but this is not critical for correct invocation of an update tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value beyond the schema by clarifying that all non-transactionId fields are optional and that only fields explicitly provided are changed, which prevents an agent from sending the entire object unnecessarily.

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 action ('Updates') and resource ('an existing transaction'), and the word 'existing' clearly distinguishes it from ynab_create_transaction and ynab_delete_transaction. It is unambiguous about what the tool does.

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 clear context: use this to modify an existing transaction, and only send fields to change. It does not explicitly name alternatives or state when not to use it, but the partial-update guidance is practical and sufficient for selection.

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