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

The description adds value beyond annotations by noting deterministic calculation and that aggregations use the complete fetched period. It does not contradict the readOnly, idempotent, or non-destructive hints. More detail on error handling or data limits would be beneficial.

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 fluff. The first sentence clearly states the core function and options; the second adds a critical behavioral detail. Highly efficient.

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?

While the description covers the main purpose and grouping, it omits explanations for budget_id and include_transfers, and does not mention return structure (though output schema exists). More details on required parameters and result format would improve completeness.

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 0%, so the description must compensate. It explains group_by enum values and implies date range parameters, but budget_id and include_transfers are left unexplained. Partial coverage leaves gaps for a 5-parameter tool.

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 calculates income, spending, and net totals over an inclusive date range, grouped by category, payee, account, week, or month. This distinguishes it from siblings like ynab_list_transactions and ynab_compare_spending_periods.

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 via the grouping and date range options but does not explicitly state when to use this tool versus alternatives like ynab_compare_spending_periods or ynab_list_transactions. No when-not-to-use guidance is provided.

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

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

Annotations already indicate idempotent and non-destructive. Description adds safety confirmation and return value. No contradictions.

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?

Extremely concise: two sentences plus usage line. Front-loaded with core purpose. No wasted words.

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

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

Given zero parameters and simple operation, description covers purpose, safety, usage, and return. Completeness is 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?

No parameters, baseline 4 as per guidelines. Description notes 'Args: (none)' which aligns with 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?

Description explicitly states it clears in-memory caches, emphasizing safety and no data modification. Clearly distinguishes from sibling tools that manipulate YNAB data.

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

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

Provides explicit guidance on when to use: after external YNAB changes or to free memory. Lacks explicit when-not scenarios but context is 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint, so safety and idempotency are clear. The description adds 'deterministically' which reinforces idempotency, and 'complete spending periods' clarifies scope. No contradictions exist. Additional context like data sources or side effects is not needed given 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 that conveys all essential information without redundancy. It is front-loaded with the action and outcome, making it easy to scan. Every word adds value.

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 tool's complexity (5 parameters, nested objects, output schema exists), the description covers the core purpose and outcome. However, it omits details like the necessity of complete historical periods, handling of missing data, or default behavior for budget_id. The presence of an output schema mitigates the need for return value documentation. Overall, it is nearly complete for a comparison 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 description coverage is 0%, meaning the description does not explain any parameters. While the schema itself is well-defined with required fields and enums (group_by, period_a, period_b), the description should at least mention the grouping options or the purpose of 'include_transfers' to compensate for the lack of parameter documentation. The rubric requires compensation when coverage is low (<50%), and the description fails to provide 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 clearly states the tool's function: 'Compare two complete spending periods and calculate total and per-group differences.' It uses a specific verb ('compare') and resource ('spending periods'), and the result type is clearly defined ('differences'). This distinguishes it from sibling tools like 'ynab_analyze_spending' (general analysis) and 'ynab_compare_transactions' (transaction-level comparison).

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 use when needing to compare two complete spending periods across groups. It does not explicitly state when not to use it or mention alternatives, but the tool name and sibling context (e.g., ynab_compare_transactions) provide clear differentiation. The phrase 'deterministically' hints at reproducibility, which is useful.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint, so the safety profile is covered. The description adds the comparison report categories matched, unmatched_bank, and unmatched_ynab, but does not explain matching behavior, tolerances, or other operational details.

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

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

The purpose is front-loaded in the first sentence, followed by a compact Args list and a short Returns note. There is no filler, and the structure is easy for an agent 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?

This is a complex 12-parameter tool with a nested csv_format object and tolerance controls, but the description leaves several behavior-affecting options undocumented and contains a requiredness mismatch for the CSV input. The output schema exists, so the return format does not need full explanation here, but invocation guidance is still incomplete.

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 0% across 12 parameters, and the description documents only budget_id, account_id, the CSV source, and two date filters. It omits debug, csv_format, amount_tolerance, auto_detect_format, date_tolerance_days, and enable_chronology_bonus, and it incorrectly says csv_file_path or csv_data is required while the schema requires only account_id.

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 resources: compare bank CSV transactions with YNAB transactions to find missing or mismatched entries. It is clear against most siblings, but it does not explicitly distinguish this from the related ynab_reconcile_account tool.

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

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

The purpose implies when to use it: when you have a bank CSV and want to identify missing or mismatched YNAB entries. However, it provides no explicit when-not guidance or alternatives such as ynab_reconcile_account or ynab_list_transactions.

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 the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true), and the description adds genuinely new behavior: a dry-run preview mode and a short-lived, single-use confirmation_token gate before the write executes. It does not address idempotency nuances (e.g. whether repeating with a new token creates a duplicate account) or any rate limits, so not a 5.

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

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

Front-loaded with the verb and resource, then cleanly sectioned into Args, Returns, Examples, and Write safety. The two examples are largely redundant with the parameter docs (the dry-run example just restates dry_run=true), which is minor waste in an otherwise tight definition.

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 6-parameter mutation tool with an output schema, the description covers the workflow, defaults, and required fields. The return-value sentence duplicates the output schema, and edge cases such as duplicate-name behavior or failure modes are unaddressed, but nothing essential to calling 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 coverage is only 17%, so the description carries the burden and does: budget_id omission falls back to the default budget, balance defaults to 0 and is expressed in dollars, dry_run defaults to false, and the confirmation_token flow is spelled out. The type enum is restated from the schema but every other parameter gains meaning it does not have in the schema alone.

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 ("Create a new account in a YNAB budget") with an unambiguous scope. It does not need to distinguish against a sibling because no other create-account tool exists, but it also never places itself relative to ynab_list_accounts or ynab_get_account, so it stops short of full sibling routing.

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 "Write safety" paragraph gives an explicit two-step protocol: call without confirmation_token to preview, then execute the identical request with the short-lived token. Two concrete examples show the intended call shape. It lacks any "when not to use this" or alternative-tool routing, so it is clear context without 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?

Annotations already declare readOnlyHint=false and destructiveHint=false, so the description's main addition is the two-phase write safety model: call without confirmation_token to preview, then replay the identical request with the short-lived token. That is genuinely useful behavioral context. It stops short of saying what happens on a subtotal/total mismatch or how tax is apportioned when items are partially exempt, and the confirmation flow partly duplicates the confirmation_token schema description.

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

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

Purpose is front-loaded in sentence one, followed by scannable Args, routing guidance, return shape, and write-safety notes. The Args block is long but proportionate to 14 parameters; a few lines (e.g. enumerating flag colors already in the schema enum) are redundant.

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

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

An output schema exists and the description still summarizes the return (transaction with subtransactions and receipt_summary). For a mutation tool with annotations, the confirmation-token workflow, defaults, and validation hint make it callable without ambiguity. The remaining hole is what exactly the proportional tax allocation does and how mismatched receipt_subtotal is handled.

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 only 7%, so the description carries the burden, and its Args block documents 13 of 14 parameters with meaningful semantics beyond the schema: budget_id falls back to the default, receipt_total is positive dollars, receipt_tax is 0 if none, date defaults to today, memo applies to the parent, receipt_subtotal is for validation, and defaults are given for cleared/approved/dry_run. Gaps remain on how category amounts relate to receipt_total and how tax is split across category groups.

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 first sentence names a specific verb (Create), a specific resource (split transaction), and the distinguishing input source (itemized receipt data) plus the unique behavior (proportional tax allocation). This clearly separates it from the generic ynab_create_transaction / ynab_create_transactions siblings without needing to open a schema.

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

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

It explicitly states when to use it ("when you have receipt line items and want tax allocated across categories automatically") and names the alternative with its condition ("For generic manual split transactions without receipt/tax logic, use ynab_create_transaction with subtransactions"). The preview-vs-execute prerequisite is also 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 and destructiveHint=false, so the safety profile is partially covered, but the description adds genuinely non-obvious behavior: that a call is a preview unless a short-lived single-use token from the identical request is supplied. That preview/commit contract is not derivable from the annotations. It does not explain side effects of the actual commit beyond the token flow.

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 and the amount guidance second, with the safety workflow last. No filler, though the two amount-related clauses in the first sentence could be tighter.

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

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

An output schema exists so return values needn't be described, and the critical preview/commit flow is covered. But for a 14-parameter mutation tool with 29% schema coverage, missing guidance on date format, frequency semantics, and when budget_id should be supplied leaves meaningful gaps.

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 only 29%, so the description must compensate, and it largely does not: 10 of 14 parameters (date, frequency, memo, payee, category, budget_id, flag_color, dry_run) are left with no semantic explanation anywhere beyond bare types/enums. The amount_decimal vs amount_milliunits guidance it gives is already duplicated in the schema 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?

"Create a recurring scheduled transaction" names a specific verb and resource, and "scheduled/recurring" separates it from the plain ynab_create_transaction sibling. It stops short of naming the alternative tool explicitly, which keeps it from 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?

It gives a clear two-step workflow (call without token to preview, then replay with the token), which is real usage guidance for the write path. However it never says when to choose this over ynab_update_scheduled_transaction or ynab_create_transaction, and gives no exclusions or prerequisites.

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 annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=false) by disclosing real side effects: payee_name silently creates a payee if not found, import_id affects later bank-import matching eligibility, and defaults for cleared/approved/dry_run. It also defines the two-step write-safety protocol — preview without confirmation_token, then execute the identical validated request with the short-lived token — which no annotation conveys.

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 purpose in the first sentence, then args, guidance, returns, examples, and write safety in a sensible order. The 17-line Args block is long and duplicates the few parameters the schema already documents, but given 24% schema coverage most lines earn their 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?

Covers required vs optional fields, defaults, enum values, split semantics, deprecation path, side effects, and the confirmation-token workflow. An output schema exists, so the brief 'Returns' line is sufficient for return-value awareness.

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 only 24%, and the description more than compensates by documenting all 17 parameters, including precedence rules among the three mutually exclusive amount fields, 'values are never guessed by magnitude', the budget_id omit-for-default behavior, and the per-split-line structure. This is meaning the schema alone does not supply.

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

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

Opens with a specific verb plus resource ('Create a single transaction in YNAB') and the scope word 'single' distinguishes it from the plural batch sibling ynab_create_transactions. An agent immediately knows this is the one-transaction write path.

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

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

Explicitly routes between the three amount inputs (amount_decimal preferred, amount_milliunits alternative, amount deprecated), points to ynab_create_receipt_split_transaction for itemized receipts with tax allocation, and explains subtransactions for manual splits. The notable gap is that it never mentions the batch sibling ynab_create_transactions, which is the most likely wrong turn for a caller.

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 it non-read-only, open-world, non-idempotent, and non-destructive; the description adds the important preview/confirmation-token write-safety flow, duplicate-detection behavior, batch limit, and summary of created/duplicates/failed. 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?

It front-loads purpose, then uses Args/Returns/Examples/Write safety sections; the content is dense but well organized. The Returns line is slightly redundant with the output schema but still gives a useful quick shape.

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 complex batch mutation with preview-token semantics, the description covers the operational essentials: limits, dry-run, duplicate handling, amount representation, and confirmation workflow. Because an output schema exists, it need not fully document the return structure.

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

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

With only 25% schema description coverage, the description compensates by explaining budget_id defaulting, the transactions array limit, required account_id/date, and the exactly-one amount variant rule with amount_decimal preferred. It also explains confirmation_token in the write-safety paragraph, though it is missing from the Args list and many optional nested fields are left to the schema.

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

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

The opening sentence gives a specific verb (Create), resource (transactions), batch size (1–100), and distinguishing features (duplicate detection, dry-run). The word 'batch' separates it from the singular ynab_create_transaction sibling.

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 explicit mode-selection guidance: use dry_run=true to validate before committing, omit confirmation_token to preview, and use the returned token to execute. It also notes when to set import_id for YNAB-side duplicate detection, but it does not explicitly compare against ynab_create_transaction or ynab_create_receipt_split_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?

Annotations already declare destructiveHint=true, idempotentHint=true and openWorldHint=true, so the safety profile is covered structurally. The description adds genuinely new behavior: a two-phase preview/execute protocol with a short-lived single-use token, which is not visible in the annotations. It does not state whether deletion is reversible or what happens to already-processed occurrences.

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 with the core action front-loaded and the safety protocol immediately after. No boilerplate or repetition, though the second sentence is somewhat dense and could be split for scanability.

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

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

An output schema exists, so return values need not be described, and annotations cover the destructive/idempotent profile. However, for a destructive mutation with an unusual confirmation flow and two overlapping preview mechanisms, the missing budget_id semantics and dry_run-vs-token explanation leave real gaps.

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 only 25%, so the description must carry more weight than it does. It explains the confirmation_token preview path (which the schema already documents) but says nothing about budget_id scoping, and never clarifies the relationship between dry_run and the token flow — an agent could reasonably wonder which of the two triggers preview mode.

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 ("Delete a scheduled transaction"), which cleanly separates it from ynab_delete_transaction and from the scheduled-transaction create/update/list siblings. It stops short of explicitly naming the non-scheduled delete as the alternative, but the resource noun does the disambiguation work.

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

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

Gives clear procedural context: call without confirmation_token to preview, then re-issue the identical request with the returned token. That is a concrete when/how instruction. It does not say when to prefer this over ynab_update_scheduled_transaction or whether a list/get call is needed first to obtain a valid id.

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 destructiveHint=true and idempotentHint=true, but the description adds what annotations cannot: irreversibility, a mandatory preview/confirmation_token lifecycle, and a named error condition ('Transaction not found' → invalid transaction_id). What is missing is any statement about scope of destruction (e.g., whether this touches scheduled occurrences or transfers) and rate/permission constraints.

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

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

Front-loaded with the action and its irreversibility, then structured into Args/Returns/Errors/Write safety sections that are easy to scan. The 'Returns' line is redundant with the output schema and the confirmation_token parameter is discussed in prose rather than listed with the other args, costing a little coherence.

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

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

With an output schema present, return values need not be explained, and annotations carry the safety profile — so what remains is the dangerous, non-obvious part: the two-step confirm flow, which is fully described along with error mapping. An agent has everything needed to invoke this destructive tool safely.

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 only 25% (only confirmation_token is documented in the schema), so the description must compensate, and it does: budget_id default behavior, transaction_id role, and dry_run default are all spelled out. The one soft spot is that the relationship between dry_run and omitting confirmation_token — two apparent preview paths — is never reconciled, which could confuse an agent.

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

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

The opening sentence states a specific verb and resource ('Delete a transaction from YNAB') and immediately characterizes the consequence ('This action is irreversible'). Among the siblings, only ynab_delete_scheduled_transaction is a similar deletion, and the resource name distinguishes them unambiguously.

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 'Write safety' paragraph explains the preview-then-confirm invocation flow, which is real procedural guidance. However, it never says when to choose this tool over the plausible alternative (ynab_update_transaction to modify rather than remove) or any preconditions for deletion. Usage is implied rather than contrasted with alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered and the description doesn't need to restate it. The description adds useful defaults (all sections on by default, markdown output by default) but says nothing about output volume or whether diagnostics include sensitive values when include_environment/include_security are enabled.

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

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

Purpose is front-loaded in a single clear sentence, followed by a compact Args block. The parameter list largely duplicates schema information but is the only prose source for it, so it earns most of its space; the trailing 'Returns' line is slightly wasted given an output schema exists.

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

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

With an output schema present, return values need not be detailed, and the description covers every parameter plus defaults, which is the main completeness burden for a 7-param, 0%-coverage schema. What remains unstated is the practical context — when an agent should run this and any caution about environment/security data exposure.

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 0% — the JSON schema carries only types, defaults and one enum — so the description does the heavy lifting, naming all seven parameters and explaining what each include_* flag adds. It also restates the response_format enum values. Only minor gap: it doesn't clarify whether the include flags interact (e.g. whether security stats require server info).

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 ('Get') and resource ('comprehensive diagnostic information about the MCP server') and enumerates the content domains (health, cache, delta, security). This is unmistakably distinct from every sibling, all of which operate on YNAB budget data rather than server internals.

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 only implied by the word 'diagnostic' — an agent can infer this is for health/troubleshooting checks, but the description never says when to reach for it or when a sibling (e.g. ynab_clear_cache) would be the better choice. No exclusions or prerequisites are 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?

Annotations already declare readOnly/openWorld/idempotent, so the description earns credit for additive context: it discloses the local file-write side effect, the return keys (file_path, transaction_count, file_size_kb), and a specific error string with a remediation path. It omits where the file is written and whether an existing file is overwritten, which matters for an idempotent-flagged write-to-disk operation.

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

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

Purpose is front-loaded in a single sentence, followed by clean Args/Returns/Examples/Errors sections with no filler. The Returns block is somewhat redundant given an output schema exists, but it is short and does not bloat the definition.

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 7-parameter tool with zero schema descriptions and no required fields, the description omits four parameters including a semantically significant enum and a default-true boolean. The file destination and overwrite behavior are also unstated, so an agent cannot fully predict the export's content or side effects from this definition.

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 0% across 7 parameters, so the description must compensate, and it documents only 3 (budget_id, account_id, since_date). The enum parameter 'type' (uncategorized/unapproved), the 'minimal' boolean defaulting to true, 'filename', and 'category_id' are entirely unexplained, leaving an agent unable to predict what those flags change about the export.

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 first sentence states a specific verb+resource+output: exporting transactions from a budget to a local JSON file. That distinguishes it from mutation siblings, but it never names or contrasts with ynab_list_transactions, the closest read alternative, leaving the agent to infer the difference from 'local JSON file' alone.

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 Examples block gives concrete invocation contexts ('call with no args' for everything, 'set account_id' to scope to an account), and the Errors block routes the agent to ynab_set_default_budget as a prerequisite. It stops short of explicit when-not guidance, e.g. when to use this versus ynab_list_transactions or ynab_analyze_spending.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds return fields including cached and cache_info, and lists possible errors, providing useful context beyond 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?

Well-organized with clear sections: brief purpose, Args list, Returns, Errors. Each sentence is informative without unnecessary fluff.

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

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

Given the presence of an output schema and annotations, the description covers all needed aspects: parameter details, return fields, error cases, and default behavior. No gaps for a read-only get operation.

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 0%, but the docstring explains all 3 parameters: budget_id (optional, default budget), account_id (required), response_format (optional, enum with default). This fully compensates for missing schema 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?

Description clearly states 'Get details for a single account including current balance,' which is a specific verb+resource. It distinguishes from sibling 'ynab_list_accounts' which lists all accounts.

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

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

Provides clear context: optional budget_id with default budget behavior, required account_id, and error guidance for 'No default budget set' and 'Account not found'. No explicit 'when not to use' or comparison to alternative tools, but sufficient for its purpose.

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 indicate readOnly, idempotent, non-destructive. The description adds further behavioral details: mentions the return fields explicitly and describes an error case. No contradictions.

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 well-structured with clear sections (Args, Returns, Examples, Errors), front-loaded with the one-line purpose. Every sentence adds value and is concise.

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 output schema exists, the description still provides complete context: input, output, error handling, and example. For a simple get tool, it covers all necessary 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?

With 0% schema description coverage, the description compensates fully: it explains both parameters (budget_id as UUID, response_format with enum and default) and adds context 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 'Get summary information for a specific YNAB budget', using a specific verb and resource. It distinguishes from siblings like ynab_list_budgets by focusing on a single budget. The title annotation reinforces this.

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 an example linking to ynab_list_budgets and mentions error handling. However, it does not explicitly state when not to use this tool versus alternatives, though the name and sibling context make it 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?

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint. The description adds value by disclosing that results are for the 'current month', detailing the return fields (id, name, budgeted, activity, balance, goal_type, etc.), and explaining error conditions. This goes beyond what annotations convey.

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

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

The description is well-structured with a clear one-line purpose, bulleted args, a returns line, and error list. It is front-loaded and concise, though the docstring style (Args:, dashes) is slightly verbose for a function 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?

Given the tool's simplicity (3 params, no nested objects) and the presence of an output schema (not shown but signaled), the description covers the key aspects: current month scope, return fields, and error handling. It is largely complete, though it could mention that activity is the month-to-date activity.

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 0%, but the description compensates by explaining each parameter: budget_id (UUID, optional to use default), category_id (UUID), response_format (enum default 'markdown'). This adds practical meaning though it could be more precise (e.g., UUID format).

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 'Get current month details for a specific budget category' with a specific verb and resource. It distinguishes from siblings like ynab_list_categories (which lists many) and ynab_get_month (which gets a full month) by focusing on a single category's details.

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 basic usage hints like omitting budget_id to use default and lists errors that guide troubleshooting (e.g., requiring ynab_set_default_budget first). However, it lacks explicit guidance on when to use this tool instead of alternatives like ynab_list_categories or ynab_get_month, and does not mention prerequisites beyond the default budget.

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, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered elsewhere. The description's added value is the return contract ('default_budget_id (null if not set), has_default'), which tells the agent how to detect the unset case – useful, but it does not describe sourcing (local config vs API) or caching 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?

The purpose is front-loaded in a single sentence, followed by a compact Args/Returns block. Nothing is padded, though the Args restatement of the enum is somewhat redundant with the schema.

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

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

For a one-optional-parameter read-only lookup with an output schema and strong annotations, this is close to complete: the agent knows what it returns and how to read an unset default. Only the relationship to its counterpart ynab_set_default_budget is left implicit.

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 0%, so the description must carry the parameter, and it does: it names response_format, gives the two enum values, and states the 'markdown' default. That is exactly the information the bare schema lacks, though no guidance is offered on which format to prefer.

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: 'Get the currently configured default budget ID.' This clearly separates it from ynab_set_default_budget and from the budget-listing tools, though the description never names those siblings 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?

Usage is only implied by the narrow purpose – an agent can infer it is a config lookup rather than a budget data fetch. There is no explicit statement of when to call it instead of ynab_get_budget or ynab_list_budgets, and no prerequisites are given.

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

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

Annotations already declare readOnly/idempotent/non-destructive/openWorld, so the safety profile is covered. The description adds what annotations cannot: that results may be served from cache (`cached`, `cache_info` in the return) and a documented error string with its recovery step. It never says when the cache is bypassed or how stale data can be, which keeps it below a 5.

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

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

The purpose sentence is front-loaded and the Args/Returns/Examples/Errors blocks are scannable, with no filler prose. Some structure is redundant with the schema (parameter names and types restated), costing a small amount of space without adding meaning.

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 month-fetch, the definition covers required format, budget selection, output format choice, return fields, and the one known error path. With an output schema present, the Returns line is a bonus rather than a gap, and nothing needed to invoke the tool correctly is missing.

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

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

Schema description coverage is 0%, so the description must carry all three parameters and it does: budget_id's optionality and default-budget behavior, month's exact YYYY-MM-DD convention plus the non-obvious 'use first day' rule and a concrete example, and response_format's two values and markdown default. The first-day convention is genuinely additive beyond the schema's regex pattern.

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 first sentence names a specific verb and resource ('Get full budget data for a specific month') and adds a scope detail ('including all category balances') that separates it from ynab_list_months and ynab_get_budget. It stops short of naming a sibling explicitly, so an agent must infer the boundary rather than read it.

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 states the default-budget fallback ('Omit to use the default budget') and routes a specific failure to a remedy ('run ynab_set_default_budget first'), which is real when-to-use guidance. It gives no explicit when-not or alternative-tool comparison, so it lands at clear-context-without-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?

Annotations already cover readOnly, idempotent, non-destructive. Description adds caching behavior and error conditions (default budget, not found), which go beyond annotations.

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

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

Front-loaded with purpose, uses structured bullet points for args/returns/errors. Every sentence adds value with no redundancy.

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

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

For a simple retrieval tool, covers inputs, outputs (field list), errors, and caching. Output schema exists but description still mentions return fields.

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 has 0% description coverage, but description fully explains all parameters: budget_id (optional, default), payee_id (required), response_format (enum, default markdown). Compensates completely.

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 'Get details for a specific payee'—a specific verb and resource. Clearly differentiates from sibling 'ynab_list_payees' which lists all 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?

Provides clear context: use by payee_id, optional budget default, response format choice. Includes error handling guidance but no explicit when-not or comparison to alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint, so the safety profile is fully covered. The description adds nothing beyond that — no not-found behavior, no auth/scope notes, no mention of how the budget context is resolved.

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, so nothing is wasted. The terseness is efficient but leaves too little substance to call it exemplary.

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

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

An output schema exists, so return values need not be explained. Still, for a tool with two undocumented parameters and an unspecified not-found/error path, the description is too thin to let an agent call it correctly without trial and error.

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 0% and the description only hints that a scheduled_transaction_id identifies the record ("by ID"). The budget_id parameter is completely undefined in both schema and description, including whether it defaults to a configured budget.

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 ("Get one scheduled transaction") and the singular "one" implicitly distinguishes it from ynab_list_scheduled_transactions. It does not, however, explicitly name that sibling or contrast with the create/update/delete variants, leaving the agent to infer the 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 no when-to-use guidance, no prerequisites, and no alternatives. An agent must infer from the name alone that this is the single-record lookup path versus the list tool.

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

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

Annotations already cover read-only, idempotent and non-destructive semantics, and the description adds real context beyond them: the cache flags ('cached, cache_info') in the return, plus two named error conditions with remediation. It does not explain caching lifetime or rate-limit 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?

Front-loaded one-line purpose followed by compact Args/Returns/Errors blocks, so an agent can scan it quickly. The Args block restates names and types already in the schema, but with 0% schema coverage that repetition 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?

Given an output schema exists, the Returns line is supplementary rather than essential, and the Errors section plus the default-budget fallback cover the main failure modes. What remains unstated is whether a missing transaction vs a missing budget requires different recovery paths beyond the two listed errors.

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 0%, so the description carries the full burden and largely succeeds: it labels budget_id optional with the meaningful 'omit to use the default budget' behavior, marks transaction_id required, and gives response_format's enum and default. 'Transaction UUID' is the only thin spot.

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 ('full details for a single transaction by ID'), which implicitly separates it from list_transactions and the update/delete siblings. It never names a sibling explicitly, so the differentiation is inferred 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 by the 'single transaction by ID' framing and reinforced by the error routing ('No default budget set' → run ynab_set_default_budget first), which is genuinely actionable. There is still no explicit guidance on when to use this versus ynab_list_transactions or ynab_compare_transactions.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description discloses error conditions (UNAUTHORIZED) and return details (user id), adding meaningful behavioral 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?

The description is short, well-structured with clear sections (description, args, returns, errors), and every sentence adds value.

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 simplicity of the tool (1 optional parameter, read-only), the description covers purpose, parameter, return, and errors completely, despite an available output schema not shown.

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 description fully explains the single parameter (response_format), including its optional nature, default value, and enum options, compensating for 0% schema description 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 retrieves information about the authenticated YNAB user, with a specific verb and resource. It uniquely identifies the tool among siblings as the only one for user info retrieval.

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 no guidance on when to use this tool versus alternatives or when not to use it, lacking explicit usage context or 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?

Annotations already declare readonly, idempotent, non-destructive. The description adds behavioral details: pagination (limit, offset, has_more), caching info, and error conditions, going beyond 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?

Well-organized with Args, Returns, Examples, Errors sections. Purpose stated first. Every sentence adds value. Concise yet comprehensive.

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 sibling tools, annotations, and presence of output schema (mentioned in description), the description covers return structure, pagination, caching, and errors adequately.

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 0%, but description compensates by documenting all 4 parameters with types, defaults, constraints, and examples (e.g., budget_id optional, limit exclusiveMin 0, offset min 0, response_format enum).

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?

Clearly states 'List all accounts for a budget.' Verb and resource are specific, and it differentiates from siblings like ynab_get_account and ynab_list_budgets.

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?

Includes error guidance (e.g., 'No default budget set' suggests ynab_set_default_budget) and examples for pagination. However, no explicit when-not-to-use compared to alternatives like ynab_get_account.

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

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

The description adds behavioral context beyond annotations: it discloses caching behavior, return structure (budgets[], cached, cache_info), and a specific error (UNAUTHORIZED). Annotations already indicate read-only and idempotent, so the description complements these well without contradiction.

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 concise and well-structured, using clear headings for args, returns, examples, and errors. Every line adds value with no wasted words.

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

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

Given the tool's simplicity (one optional parameter, read-only), annotations, and existence of an output schema, the description is complete: it covers purpose, parameter, return format, example usage, and error handling. No gaps are evident.

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

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

With 0% schema coverage, the description compensates by explaining the single parameter response_format, including its enum values and default. This adds meaning beyond the schema, which only defines the property without description.

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 YNAB budgets for the authenticated user, using a specific verb and resource. It distinguishes from siblings like ynab_get_budget by specifying 'all budgets', making its 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 implies usage for listing all budgets but does not explicitly state when to use this tool versus alternatives like ynab_get_budget for a single budget. No exclusions or alternatives are mentioned, relying on the agent to infer context.

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 (readOnlyHint, idempotentHint) indicate safe operation. Description adds behavioral context: pagination behavior (has_more, next_offset), caching (cached, cache_info), and default budget dependency. No contradictions.

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?

Well-structured: one-purpose sentence followed by a clean docstring format with Args, Returns, Examples, Errors. Every sentence adds value without verbosity.

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?

Covers pagination, default budget, response format, caching, error cases, and return fields. Despite output schema existing, description adds comprehensive context with examples and error handling.

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 0%, but the description fully documents all 4 parameters: budget_id (optional, default), limit (default 50), offset (default 0), response_format (enum, default 'markdown'). Also explains return fields beyond 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 'List all budget categories for a budget with pagination,' specifying the verb (list), resource (budget categories), and scope (pagination). It distinguishes from sibling tools like ynab_get_category (singular) and other list 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?

Provides explicit guidance: omit budget_id for default budget, pagination examples (limit=50, offset=50), and error handling ('No default budget set' → run ynab_set_default_budget first). Does not explicitly say when to avoid but 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 readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false. The description adds useful behavioral context beyond annotations: pagination defaults, response fields, cache-related fields, and the "No default budget set" error path with remediation. It does not discuss rate limits, but it is materially transparent for a read-only list tool.

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

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

The definition is structured and front-loaded: purpose first, then Args, Returns, Examples, and Errors. Every section adds actionable information, and the examples are concise and directly usable.

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 tool is a read-only paginated list operation with annotations, an output schema, and zero required parameters. The description still supplies all necessary parameter semantics, pagination guidance, return field awareness, and error remediation, so an agent can call it correctly without opening the schema.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning; it does so fully. It documents budget_id as optional with default-budget behavior, limit and offset with defaults, and response_format with allowed values and default.

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

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

The description states a specific verb and resource: "List summary data for all budget months with pagination." This clearly distinguishes the tool from single-month siblings like ynab_get_month and from unrelated transaction 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?

The description gives practical usage context: no-args lists recent months newest-first, and pagination examples show limit/offset usage. It also names ynab_set_default_budget as remediation when no default budget exists. It does not explicitly say when to choose this over ynab_get_month, but the list-vs-single distinction is 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?

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds valuable behavioral context: pagination parameters, return fields (including cache_info), and error handling, going beyond what annotations provide.

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 well-organized into Args, Returns, Examples, and Errors sections. Every sentence adds value, no redundancy. It is appropriately sized for the tool's complexity.

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

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

Given the presence of an output schema, the description still provides comprehensive information: all parameters, return structure, pagination details, and error handling. Examples cover common use cases, making it complete for agent 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 coverage is 0%, so the description fully documents all 4 parameters. It explains budget_id as optional UUID, limit and offset with defaults and constraints, and response_format with enum values 'json' or 'markdown', adding meaning 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 explicitly states 'List all payees for a budget with pagination,' using a specific verb and resource. It clearly distinguishes from sibling tools like ynab_get_payee (single payee) by focusing on listing all payees with pagination.

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 includes examples for pagination and an error section advising to run ynab_set_default_budget if no default budget is set. It provides clear guidance on usage, though it does not explicitly contrast with alternative tools like ynab_get_payee.

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

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

Annotations already cover readOnly, idempotent, openWorld, and non-destructive. The description adds two useful behavioral facts: results are paginated and delta-cached, and amounts are returned in both decimal and milliunits. However, "delta caching" is never explained (no cache token parameter exists in the schema), leaving an unclear mechanism for the agent.

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

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

Two tight sentences with the core action front-loaded and no filler. Slightly under-specified rather than bloated, but structurally efficient.

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 three-parameter tool with 0% schema coverage, the description leaves key semantics unresolved: budget_id's role and whether it defaults, what delta caching means to the caller. The presence of an output schema excuses it from explaining return values, but parameter-level gaps remain significant.

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 0%, so the description carries the full burden for limit, offset, and budget_id, yet it explains none of them. "Pagination" only loosely hints at limit/offset, and the budget_id parameter — critical since no default budget behavior is stated — is entirely undocumented.

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 and resource ("List scheduled transactions") that clearly separates it from the get/create/update/delete scheduled-transaction siblings. It does not explicitly name the single-record sibling (ynab_get_scheduled_transaction) as the alternative, so differentiation is inferable 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?

It mentions pagination and delta caching but never says when to use this versus ynab_get_scheduled_transaction or the general ynab_list_transactions. There is no guidance on preconditions, no exclusions, and no indication of what happens if budget_id is omitted.

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?

With readOnlyHint/idempotentHint already declaring a safe read, the description still adds real value: it discloses caching (cached, cache_info), pagination mechanics (has_more, next_offset, offset), the exact returned envelope, and two named error conditions with remedies. It does not state rate limits or the underlying API's per-request cap, but the behavioral profile is unusually complete.

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

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

Front-loaded one-sentence summary followed by Args/Returns/Examples/Errors, so an agent can stop reading at any level. It is longer than average, and the Args bullets partly restate the schema, but with 0% schema coverage that restatement is load-bearing rather than 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 9-parameter read tool this covers everything an agent needs: filters, pagination, output format choice, response envelope, failure modes, and sibling hand-offs. An output schema exists, so the Returns line is a bonus rather than a requirement.

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 0%, so the description carries the full burden and does: all 9 parameters are documented with type, semantics, defaults (limit 50, offset 0, markdown format), the ISO YYYY-MM-DD date shape, and the 'omit to use default budget' resolution rule. The allowed values for type and cleared are also spelled out in prose, so an agent can construct a call without inspecting 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+resource ('List transactions for a budget') plus the scoping axes (filtering, pagination), which is well beyond a restatement of the name. It routes large-result cases to ynab_export_transactions, but never distinguishes itself from ynab_get_transaction or ynab_compare_transactions, which are the nearest neighbors an agent could confuse it with.

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

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

The Examples block gives concrete call scenarios (no args for default budget, account filter, since_date, page 2) and the Errors block explicitly prescribes ynab_set_default_budget for the 'No default budget set' case and ynab_export_transactions for large result sets. There is no explicit 'when not to use' versus single-transaction or comparison siblings, so it stops 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?

Adds substantial context beyond the annotations: defaults for every destructive-ish flag (dry_run=true, all auto_* flags false), what each auto flag actually mutates (clearing, unclearing, creating), the confirmation_token write-safety protocol, and the shape of the return narrative. This tells an agent exactly what will change before it acts, which the readOnlyHint=false / destructiveHint=false annotations alone do not.

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?

Well-structured and front-loaded, with a one-line summary followed by an arg list, a returns line, examples, and a write-safety note. It is long, but 17 parameters justify the length; a couple of entries (max_suggestions_in_output) are lower-value than the undocumented ones.

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 high-complexity, 17-param, open-world write workflow, the description covers the safety model, defaults, return shape (output schema also exists), and the key domain quirks like liability sign handling. The only real omissions are the csv_format nested config and the date-matching tolerance knobs, which an agent may need to reconcile a non-standard CSV.

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 only 6%, so the description carries the burden and largely does: it explains budget/account ID semantics, the csv_file_path-or-csv_data alternative, the liability sign convention for statement_balance with a concrete example, what sign_convention and match_strictness actually do, and each auto flag's effect. Notable gaps: csv_format (a nested 8-property object controlling column mapping) and date_tolerance_days/auto_adjust_dates are never mentioned in the description.

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

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

Opens with a specific verb chain and resource: 'Guided account reconciliation: match bank CSV transactions to YNAB, detect discrepancies, and optionally execute bulk create/update/unclear operations.' This is plainly distinct from siblings like ynab_compare_transactions or ynab_create_transactions, which do comparison or plain creation without the CSV-to-YNAB matching workflow.

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 workflow guidance: preview with dry_run=true (default), execute with dry_run=false plus the specific write flags enabled, and the confirmation_token two-step. It doesn't explicitly contrast against sibling tools (e.g. when to use this instead of ynab_compare_transactions), so it falls short of a 5, but the when-to-use and how-to-execute guidance is 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?

Annotations provide idempotentHint, destructiveHint, readOnlyHint. The description adds value by specifying validation against the YNAB API, the return fields (success, default_budget_id, cache_warm_started), and the error case. This complements the annotations without contradiction.

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 concise, uses clear sections (Args, Returns, Examples, Errors), front-loads the main purpose, and every sentence adds value without redundancy.

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

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

The tool is simple with one parameter and clear returns. The description covers input, output, error handling, and usage example. It could mention persistence scope (e.g., session or permanent) but overall is adequate given the tool's simplicity and presence of an output schema (though not shown).

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 only defines budget_id as a string with minLength. The description adds critical semantic info: it is a UUID (format), required, and validated against the YNAB API. It also includes an example referencing ynab_list_budgets for obtaining the UUID.

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 purpose: 'Set a default budget so other tools don't require budget_id every call.' It uses a specific verb (set) and resource (default budget) and implicitly distinguishes from siblings like ynab_get_default_budget and ynab_list_budgets.

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 explains the benefit of using this tool (reducing need to pass budget_id in other calls) but does not explicitly state when not to use it or mention alternatives. The context suggests setting a default is optional, but no exclusion criteria are given.

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 idempotentHint=true and destructiveHint=false, but the description goes further by documenting the preview/confirmation_token write-safety workflow, including that the token is short-lived, single-use, and bound to the exact validated request. It also names the error condition and the sibling that fixes it, and states the returned fields.

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

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

Front-loaded with a one-line purpose, then labeled Args/Returns/Examples/Errors sections that make it easy to scan, and every example demonstrates a distinct unit or mode. It loses a point because the Args entries largely restate the schema property descriptions already present for category_id, budget_id, and dry_run.

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 7 parameters, this covers the things an agent cannot infer: unit precedence, the two-step confirmation workflow, the default-budget fallback, and the specific failure case. Return values are optionally summarized and an output schema exists anyway, so nothing material is absent.

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

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

Schema coverage is only 57%, but the description compensates: it lays out the precedence among budgeted_decimal (preferred), budgeted_milliunits (alternative raw units), and budgeted (deprecated alias), plus dry_run's default and worked examples showing the 100.00 vs 100000 equivalence. It passes through confirmation_token's role implicitly via the write-safety paragraph rather than restating its schema contract.

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 ("Update the budgeted amount for a category") plus a scoping constraint ("in the current month") that a bare name like ynab_update_category would not convey. This implicitly distinguishes it from ynab_get_category and from the transaction-update siblings, so an agent knows this mutates a month's funding figure, not category metadata.

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 guidance: omit budget_id for the default budget, use dry_run to preview, and a remediation path for the "No default budget set" error (run ynab_set_default_budget first). What is missing is discovery guidance — nothing says to call ynab_list_categories to obtain category_id — and there is no explicit statement of when an alternative tool would be preferable.

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. The description adds important behavior beyond annotations: calling without a confirmation_token previews, and execution requires the short-lived token from that preview.

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 focused sentences with no wasted text. The preview/execute constraint is front-loaded and easy to act on.

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 15 parameters and low schema description coverage, the description is too sparse. It covers the confirmation workflow but leaves most field semantics and partial-update behavior undocumented; an output schema exists, so return values need not be explained.

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 only 27%, and there are 15 parameters, but the description explains only confirmation_token behavior. It does not clarify which fields can be updated, how partial updates work, or the meaning of budget_id, account_id, payee fields, frequency, or amount aliases.

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: updating selected fields on a scheduled transaction. It clearly distinguishes this from sibling tools like ynab_create_scheduled_transaction, ynab_delete_scheduled_transaction, and ynab_get_scheduled_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 preview/execute workflow is described, which tells the agent how to call it safely. However, it does not explain when to choose this tool over ynab_update_transaction or when not to use it, so usage guidance is implied rather than explicit.

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=false and idempotent=true, but the description adds genuinely new behavioral facts: the two-step preview/confirmation_token protocol, the dry_run preview mode, and the important limitation that YNAB cannot replace existing split lines. It also states what is returned, going beyond the annotations and the output schema summary.

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

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

Front-loaded with a one-line purpose, then a compact Args block where each line adds meaning rather than echoing the schema, followed by a Returns and Write-safety line. Dense but every section earns its place for a 17-parameter 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?

Given 17 parameters, a nested subtransactions array, and an existing output schema, the description covers the split-conversion constraint, the token handshake, and the return shape. It stops short of documenting the remaining fields (account_id, flag_color) and any permission or error behavior, but is otherwise sufficient to call 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?

With only 24% schema coverage across 17 params, the description carries most of the load and mostly does: it explains the amount_decimal / amount_milliunits / deprecated amount precedence, the cleared enum values, the date format, the split-conversion rules, and the budget_id default. Two schema properties, account_id and flag_color, are undocumented in both schema and description, which is the main gap.

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 ('Update fields on an existing YNAB transaction') so the agent immediately knows this is a single-transaction mutation. It does not name the sibling it differs from (ynab_update_transactions for bulk, ynab_create_transaction for creation), so sibling differentiation is only implicit from the singular name.

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 strong procedural guidance on how to invoke safely (preview first, then replay with confirmation_token), which implies when to use the preview mode. However, it never states when to choose this tool over ynab_update_transactions or ynab_create_receipt_split_transaction, and gives no exclusions for which fields are updatable versus not.

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 annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false) by disclosing the 100-item batch cap, the preview→confirmation_token execution protocol with token lifetime/single-use semantics, and the key domain constraint that YNAB does not support replacing lines on an existing split. These are exactly the mutation behaviors the annotations cannot convey.

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

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

Front-loaded summary sentence, then structured Args/Returns/Example/Safety sections that are easy to scan. Slight redundancy — the Returns line duplicates an output schema that already exists, and the amount-variant guidance is repeated between the Args entry and the schema.

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

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

For a 4-parameter batch mutation with a nested transaction array, the description covers the critical decision points (preview flow, batch limit, split rules) and an output schema handles return values. It stops short of explaining the per-object fields a caller must actually set, which is the main residual 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?

With only 25% schema description coverage, the description carries real weight: it documents budget_id's default-budget omission behavior, the amount_decimal > amount_milliunits > deprecated amount precedence, and the split-conversion rule. The remaining nested transaction fields (cleared, approved, flag_color, payee_id) are still undocumented in either place, and confirmation_token appears only in the safety paragraph, not the Args list.

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

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

Opens with a specific verb+resource+scope: 'Update 1–100 transactions in a single batch with dry-run preview.' The batch cardinality (1–100) implicitly distinguishes it from the single-record sibling ynab_update_transaction, 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?

The 'Write safety' paragraph gives a concrete when/how-to-call workflow: preview without confirmation_token, then replay the identical validated request with the short-lived token. The dry-run example reinforces it. What's missing is any explicit routing vs. ynab_update_transaction (single) or ynab_create_transactions (create).

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