YNAB MCP Server

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

Annotations already declare readOnlyHint=true and idempotentHint=true, but the description adds specifics: it performs a single API request without accountId, lists uncleared/unapproved transactions with accountId, and helps compare against the bank statement. This is valuable behavioral context beyond the annotations, and it reinforces the read-only promise by stating 'Makes no changes.' No 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 front-loaded with the core purpose and the parameter-dependent behavior, and each subsequent sentence earns its place by covering usage and interpretation. Despite its length, there is no redundancy or filler; the structure mirrors the decision process an agent would follow.

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

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

With an output schema present, the return format is covered. The description fully explains what the tool does, when to use it, how to interpret results, and what it does not do (actual reconciliation). Nothing an agent needs to call this correctly and interpret the result is missing.

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

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

Schema coverage is 100% for both parameters, but the description adds crucial semantics: it explains how the presence or absence of accountId changes the tool's behavior (summary vs. detail listing). This goes far beyond the schema's bare field descriptions and directly informs the agent which parameter to set for the desired outcome.

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

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

The description opens with a precise verb and resource ('Read-only reconciliation diagnosis') and then distinguishes two modes (with/without accountId) that map cleanly to the two parameters. It clearly separates this tool from siblings like audit_credit_card_payments by focusing on reconciliation state rather than card payment issues.

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 states when to use it ('use this to find what needs attention first') and when not to (actual reconciliation happens in the YNAB UI). It also provides an interpretation note that helps the agent decide if a finding is actionable, which is exactly the kind of usage guidance that reduces mis-calls.

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?

Even though annotations already mark the tool read-only, idempotent, and non-destructive, the description adds valuable behavior: it 'makes no changes,' reports each card's balance/category balance/difference/status, and warns that pending/uncleared transactions can cause transient sub-dollar differences to be treated as timing rather than error. This goes beyond the annotations.

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

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

The description is front-loaded with the core audit purpose and flows naturally into purpose, healthy/unhealthy interpretation, output contents, non-mutating behavior, and a practical caveat. Every sentence adds information; there is no filler or repetition.

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

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

For a read-only audit tool with an output schema and a single optional parameter, the description fully covers what the tool computes, what the results mean, what it does not do, and how to interpret edge cases. Nothing material is missing for an agent to invoke it confidently.

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 only parameter, budgetId, is fully described in the schema ('Budget ID (uses default if not provided)'), so schema coverage is 100%. The description adds no budgetId-specific semantics, but none are needed because the schema already handles it; this is the appropriate baseline score.

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

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

The description opens with 'Read-only audit of credit card payment categories' and precisely defines the behavior: comparing each open card/line-of-credit balance with the corresponding payment category's available balance. This clearly distinguishes it from generic read tools like get_account or get_category, and from the fix-oriented update_month_category 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?

It explicitly states when this audit is relevant (healthy budgets show a sign-flipped match; shortfalls indicate underfunded future payments) and gives an actionable alternative: 'fix shortfalls by assigning to the payment category via update_month_category.' This is strong when-to-use and when-not-to-use guidance.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds meaningful behavioral context: exact-amount grouping, cadence matching, estimated annual cost, and important limitations that affect interpretation. This goes well beyond what the annotations alone convey and does not contradict them.

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 detailed yet well-structured: the core function and use case come first, followed by the key sibling distinction and then limitations. Every sentence carries essential information, and the length is justified by the tool's analytical 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 rich annotations, complete parameter schema, and presence of an output schema, the description covers everything an agent needs to select and invoke the tool correctly. It explains what the tool catches, what it misses, and how to verify ambiguous results.

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

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

The input schema fully describes all three parameters, including defaults and the effect of monthsBack on cadence detection. The description reinforces the grouping-by-exact-amount limitation that explains why minOccurrences matters, but it does not add substantial parameter-level detail beyond the schema, so the baseline of 3 applies.

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

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

The description clearly states the tool's function: read-only detection of recurring charges from transaction history, with specific methodology (grouping by payee + exact amount and cadence detection). It also distinguishes itself from list_scheduled_transactions, 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?

Explicit guidance is provided for when to use this tool ('subscription audits' and 'what am I paying for' questions), and when not to rely on it (variable-amount bills, payee spelling variants). It also names the alternative tool and the verification step with search_payees, giving clear decision criteria.

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 (read-only, idempotent, non-destructive), the description discloses several important behaviors: CSV column semantics ('negative = outflow'), formula-injection protection via leading apostrophe and why it exists, and a warning about large date ranges producing large output. The 'Read-only' line is redundant with annotations but does not contradict them.

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 efficiently structured, front-loading the core purpose and then adding column details, security rationale, usage guidance, and a size warning. The only mild redundancy is the standalone 'Read-only.' sentence, which duplicates the readOnlyHint annotation, so it does not receive a 5.

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

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

For a tool with 9 optional parameters, an output schema, and a non-trivial CSV formatting behavior, the description covers everything an agent needs to select and invoke it correctly: format, columns, amount sign convention, formula-injection safety, usage context, and scale warning. Nothing important is missing.

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

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

Schema description coverage is 100%, so the schema carries the parameter documentation burden. The description adds a useful hint that filters are shared with get_transactions and highlights the 'type' filter, but it does not materially elaborate on individual parameters. Baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Export transactions as CSV text.' It also names the format and explicitly contrasts with get_transactions ('same filters as get_transactions'), making the tool's role unambiguous relative to its siblings.

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

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

Explicit when-to-use guidance is provided: 'Use when the user wants data for a spreadsheet or offline analysis; for programmatic work prefer get_transactions (structured JSON).' It also advises narrowing filters for large ranges, giving the agent actionable selection and invocation rules.

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. The description adds 'Read-only' (redundant) and 'fresh detail' (implies live fetch). Minimal additional behavioral context beyond annotations, but no contradiction. Baseline 3 is appropriate.

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

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

Two sentences, front-loaded with purpose and details, then usage guidance. Every sentence earns its place with zero waste.

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

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

For a single-account fetch with an output schema and annotations covering safety, the description is complete: it states what it returns, when to use it, and that it's read-only. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so the schema fully documents accountId and budgetId. The description does not add parameter-specific semantics beyond what the schema provides; it lists output fields but not parameter usage. Baseline 3 stands.

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 ('one account's details') and enumerates the specific data returned (balances, type, reconciliation timestamp, debt metadata). Explicitly distinguishes itself from list_accounts by stating it is for single-account detail retrieval when the ID is already known.

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, explicit guidance on when to use this tool versus the sibling list_accounts: 'Prefer list_accounts when comparing several accounts; use this when you already have the account ID and want fresh detail.' No ambiguity left for the agent.

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

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

Annotations already mark this as read-only and idempotent, and the description adds substantial behavioral context: the delta response includes changed entities plus new server_knowledge, responses over YNAB_MAX_RESPONSE_BYTES are rejected, and the default cap is 8 MB. This goes well beyond the annotation hints.

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 sentences, front-loaded with the primary purpose, followed by the delta mode and a practical size-limit warning. Every sentence earns its place and the structure is 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?

Given the output schema exists, return values need no explanation. The description covers both usage modes, the special lastKnowledgeOfServer: 0 behavior, the size cap, and alternatives for large budgets. An agent has everything needed to call this correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful parameter behavior beyond the schema by explaining that lastKnowledgeOfServer: 0 returns the full budget export and that large responses may be rejected, plus guidance to prefer incremental deltas. This is extra semantic value, though some delta semantics are already present in the schema.

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

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

The description states a specific verb and resource ('Get a budget summary') and enumerates the exact contents (name, currency format, counts). It also describes the delta-export alternative, which clearly distinguishes this tool from siblings like get_budget_settings and 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 explicitly explains when to use the delta mode versus the summary mode, warns that lastKnowledgeOfServer: 0 returns a very large full export, and directs users to prefer incremental deltas or dedicated list tools on big budgets. This is explicit when/when-not guidance with named 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=true, idempotentHint=true, and destructiveHint=false. The description adds that it 'combines' multiple data sources and discloses an approximate cost of 4 API requests, which is relevant for rate-limit expectations. This adds value beyond annotations, though no auth or other behavioral details are mentioned.

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 moderately long but each sentence earns its place: core components, thresholds, usage guidance, and cost. Information is front-loaded with the snapshot description before interpretation details. Slightly verbose with the threshold list but still 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?

Given the tool's complexity and the presence of an output schema, the description covers what the tool computes, how to interpret thresholds, when to use it, and an approximate cost. Nothing critical is missing for an agent to invoke it correctly.

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

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

The input schema already fully documents the single optional parameter 'budgetId' with 100% coverage. The description does not add any semantic detail about the parameter beyond what the schema provides, so the baseline of 3 applies.

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

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

The description states a specific verb ('get') and resource ('budget health snapshot'), enumerates the components (month data, balances, trailing-3-month income/spending summary) and indicators (savings rate, age of money, etc.), and distinguishes it from sibling tools like get_budget or get_month by framing it as an aggregated opening move.

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 states when to use: 'opening move of a monthly review or how-am-I-doing question', and advises to 'then drill into specific tools', implying alternatives without needing to name them. The threshold guidance also helps the agent interpret results, which is part of using the tool correctly.

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 operation read-only, idempotent, and non-destructive, so the description's 'Read-only' adds no new safety information. However, the description adds behavioral context beyond annotations: it clarifies that the output formats are for display only and that all tool inputs are in a fixed dollar/YYYY-MM-DD style, which helps the agent understand the tool's role without risking misuse.

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

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

The description is two sentences with no filler. The core purpose is front-loaded, the read-only note follows, and the usage guidance is packed into the second sentence. Every word contributes to help an agent decide to call this tool and understand its output.

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 simple tool with one optional parametercrazy and an output schema already present. The description covers its purpose, the exact fields returned, and when to use it versus not. There is no missing information an agent would need to invoke this tool correctly, and the presence of an output schema means return structure is already defined elsewhere.

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

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

The schema already documents the single parameter 'budgetId' with its description ('Budget ID (uses default if not provided)') at 100% coverage. The tool description itself adds no additional meaning to the parameter, such as how the default budget is chosen or the expected format of the ID. With complete schema coverage, baseline 3 is appropriate.

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

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

The description clearly states a specific verb ('Get'), a specific resource ('a budget's settings'), and enumerates the exact contents (currency format with symbol, decimal digits, placement, and date format). This differentiates it from sibling tools like get_budget, which would return the budget object itself, and list_budgets, which returns all 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 gives an explicit when-to-use: 'Use when formatting amounts or dates for display.' It also provides a clear when-not-needed exclusion: 'not needed for tool inputs, which always use dollars and YYYY-MM-DD,' effectively telling the agent this tool is for display presentation, not for constructing API inputs. This is directly actionable.

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/non-destructive behaviorza. The description adds non-obvious context: the tool is scoped to the current month and includes goal/target fields, which is useful beyond what annotations state.

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

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

Two concise sentences, front-loaded with the operation and scope, followed by routing guidance. No filler; the redundancy of 'Read-only' with annotations is minor and does not hurt clarity.

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 single-resource lookup with full schema coverage and an output schema, this description provides the necessary scope and routing context. Nothing critical is missing for correct invocation.

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

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

Schema description coverage is 100%, so the schema already documents both budgetId and categoryId. The description adds contextual meaning about current-month data but no additional parameter-level format or behavior details.

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 it retrieves one category's full detail for the current monthches, explicitly mentioning goal/target fields. It clearly identifies the resource and scope, and differentiates from get_month_category.

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

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

Explicitly says 'Use for goal inspection' and directs past/future month queries to get_month_category instead. This gives the agent a clear selection criterion and alternative.

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 substantial behavioral detail beyond the annotations: it explains computation rules (income/spending definitions, exclusion of transfers and deleted transactions, savings-rate formula, refunds as negative spending offsets). The 'Read-only' wording is consistent with readOnlyHint=true, and the extra context about double-counting and refund handling is valuable.

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?

Every sentence in the description earns its place: the core summary is front-loaded, followed by precise counting rules, the savings-rate definition, explicit use cases, and an edge-case clarification about refunds. The five sentences are justified by the tool's computational complexity and remain tightly structured.

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

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

With an output schema present, return values need no explanation here. The description covers the tool's purpose, exact calculation methodology, exclusions, refund behavior, and usage guidance, leaving no critical gap for an agent to select and invoke it correctly.

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

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

Input schema covers all three parameters with clear descriptions and 100% coverage, so the baseline is 3. The tool description adds no parameter-level semantics beyond what the schema already states; it references monthly windows but does not detail date formatting or defaults.

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

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

The description opens with a precise verb and resource: 'Read-only income vs. spending summary by month, computed from transaction history.' It further defines the exact income and spending scope (non-transfer inflows/outflows) and clearly differentiates this tool from siblings like get_transactions or get_budget_health by focusing on monthly summary with savings-rate calculation.

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

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

The description explicitly states applicable contexts: 'Use for savings-rate reports, month-end closes, and trend questions like

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the safety profile is covered. The description adds useful context about the batched re-allocation nature and the month-scoped behavior. The 'Read-only' phrase is redundant with annotations, but the additional domain context earns credit.

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 very short and front-loaded, packing the core purpose into the first sentence. However, the standalone 'Read-only.' sentence adds little value because it merely repeats the readOnlyHint annotation, so it does not fully earn 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?

The tool has only two parameters, a 100% documented schema, rich annotations, and an output schema. The description explains what money movement groups are, that they are month-scoped, and how this tool relates to its sibling. Nothing essential for correct invocation is missing.

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

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

Schema coverage is 100%, so both month and budgetId are already documented in the input schema. The description does not add any parameter-specific details beyond what the schema provides, so baseline 3 applies.

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

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

The description uses a specific verb and resource: 'Get money movement groups' with the qualifier 'for one month', and adds the clarifying parenthetical 'batched budget re-allocations'. It also explicitly distinguishes the tool as 'the month-scoped view of list_money_movement_groups', making it easy to differentiate from its 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?

The description clearly indicates the tool is for retrieving money movement groups for a single month and references list_money_movement_groups as the broader alternative. It does not explicitly state 'when not to use' or list other alternatives, but the context is clear enough for an agent to select this tool for month-scoped queries.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior; the description adds useful context by explaining that money movements are budget re-allocations and that this is a month-scoped, read-only view. There is no contradiction, and the extra domain context goes beyond what annotations alone 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 compact and front-loaded: it states the action, clarifies the domain term, notes read-only behavior, and names the intended use case in two sentences. Every sentence earns its place with no filler.

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

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

For a read-only, month-filtered retrieval tool, the description is complete: the annotations cover safety, the schema fully documents parameters, and an output schema exists. Nothing essential is missing for an agent to select and invoke this tool correctly.

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

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

Schema description coverage is 100%, with clear descriptions for both 'month' and 'budgetId'. The tool description adds the notion of month-scoping but does not provide parameter-specific detail beyond what the schema already states, which is acceptable but not additive.

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 ('Get money movements') and immediately defines the domain term as 'category-to-category budget re-allocations.' It also distinguishes this tool from the sibling list_money_movements by explicitly framing it as the 'month-scoped view,' so an agent can clearly identify what this tool does.

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

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

The description clearly indicates when to use this tool ('during month-end review') and ties it to the broader list_money_movements tool, implying the monthly scoping as the deciding factor. It could be stronger by explicitly saying when not to use it, but the context is clear enough for correct selection among siblings.

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

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

The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description's 'Read-only' adds no new safety information beyond that. It does add useful scoping context (single month, all category fields, dollars), but no additional operational behavior such as pagination, errors, or side effects is disclosed.

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 densely informative sentences with no filler. The core scope and payload are front-loaded, the companion alternative is placed at the end, and every clause earns its place.

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

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

For a read-only getter with full schema coverage, rich annotations, and an output schema, the description is complete. It tells the agent what data it returns, when to use it, and which sibling tool complements it for a narrower use case.

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

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

Schema description coverage is 100%, so both parameters are already documented including month format and budgetId default behavior. The description adds contextual value by clarifying the result is for one budget month and expressed in dollars, but it doesn't meaningfully expand on parameter mechanics 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 uses a specific verb-resource pair ('Get one budget month's detail') and precisely enumerates the payload: month totals plus every category's budgeted/activity/balance and goal fields in dollars. This clearly differentiates it from sibling tools like get_month_category or list_months, which cover singular categories or month lists.

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 identifies this as 'the workhorse for monthly reviews and budget-vs-actual questions,' giving an agent a clear trigger context. It also names get_overspent_categories as the companion for negative balances only, providing a concrete when-to-use versus when-not-to-use distinction.

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, and destructiveHint=false, so the safety and idempotency are clear. The description adds no additional behavioral context such as what 'category budget' means, how missing data is handled, or whether it includes activity. It is consistent with annotations but does not go beyond them.

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, efficient sentence with no fluff. It front-loads the core action and context, making it immediately understandable. It is appropriately sized for the tool's simplicity.

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 a full schema, annotations, and an output schema present, the description is sufficient for an agent to call this tool correctly. It could mention the meaning of 'category budget' or edge cases, but given the rich structured metadata, the missing detail is minor.

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

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

Schema description coverage is 100%, so all parameters (month, budgetId, categoryId) are documented in the schema. The description does not add any parameter-specific semantics beyond what the schema provides, meeting the baseline of 3 for high schema coverage.

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

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

The description clearly states a specific verb ('Get') and resource ('category budget') with a context ('for a specific month'), which distinguishes it from generic tools like get_category or get_month. It is not a tautology; it adds the month qualifier. However, it does not explicitly contrast with sibling tools, leaving some differentiation to the schema and naming.

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

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

No guidance is provided on when to use this tool versus alternatives such as get_category, get_month, or get_overspent_categories. The description only states what it does without any context on selection criteria, 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds behavioral context by explaining the significance of the returned data ('silently reducing the current month's Ready to Assign') and the temporal scope ('prior-month overspends'). This enriches the agent's understanding without contradicting any annotation.

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

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

Two sentences with zero wasted words. The primary purpose is stated first, followed immediately by the practical use case. The description is front-loaded and 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?

An output schema is present, so the return format is covered. The description explains the tool's purpose and use-case clearly. For a simple tool with only two parameters (one required), the description is sufficient. It does not discuss edge cases or the default budgetId behavior, but these are minor given the schema and annotations.

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

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

Schema description coverage is 100%, so both parameters (month and budgetId) are already documented in the schema. The description only references the month parameter implicitly via 'for a given month' but adds no syntax or format details beyond what the schema provides. The baseline of 3 applies because the schema handles the heavy lifting.

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

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

The description states a specific verb ('Get'), a resource ('all categories with a negative balance'), and a temporal scope ('for a given month'). It clearly conveys the tool's function. While it doesn't explicitly contrast with sibling tools like get_month_category, the phrasing 'all categories' and the focus on negative balance make the 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 provides a clear use case: 'Use this to find prior-month overspends that are silently reducing the current month's Ready to Assign.' This tells the agent when to apply the tool. It does not list alternatives or exclusion conditions, but the context is sufficiently specific for the agent to infer appropriateness.

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, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context beyond annotations by specifying the returned fields and the practical purpose, though it does not discuss not-found behavior or auth requirements.

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

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

The description is two compact sentences, front-loading the operation and scope before naming the alternative. Every sentence contributes either capability, intent, or routing guidance, with no filler.

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

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

For a simple read-only get-by-ID tool, the description covers purpose, use case, alternative selection, returned fields, and read-only nature. The presence of an output schema means return-value details need not be repeated, and annotations cover side-effect safety, making the description complete.

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

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

Schema description coverage is 100%, with 'Payee ID' and 'Budget ID (uses default if not provided)' already documenting both parameters. The tool description adds no further parameter-level detail, so the schema carries the burden and a baseline score of 3 is appropriate.

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

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

States a specific verb and resource ('Get one payee by ID') and names the key returned fields: name, transfer_account_id, deleted flag. It also distinguishes itself from the discovery-oriented sibling by pointing to search_payees, preventing confusion with list_payees or get_payee_location.

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 describes when to use the tool: to confirm a payee still exists or resolve its transfer account. It also names the alternative, search_payees, for discovery use cases, giving the agent clear routing guidance.

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

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

The description explicitly states 'Read-only', which aligns with and reinforces the annotations (readOnlyHint=true, destructiveHint=false). It adds context about the required input source (from list_payee_locations), which is useful behavioral information beyond the annotations.

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

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

The description is a single, efficient sentence that front-loads the core function, includes the return fields, and notes the read-only nature. Every word earns its place 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 single-record retrieval tool with an output schema present, the description is complete. It covers the input requirement, the read-only nature, and the return fields. The only minor gap is not describing error behavior (e.g., what happens if the ID doesn't exist), but that's not critical for a read-only getter.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description adds minimal parameter meaning beyond the schema, but it does clarify that payeeLocationId is the primary identifier and that budgetId is optional (uses default). This is baseline 3 territory.

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: 'Get one payee location record by its ID' with the specific fields (payee, latitude, longitude). It distinguishes itself from sibling tools like list_payee_locations and get_payee_locations_by_payee by specifying it retrieves a single record by ID.

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

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

The description explicitly states it requires a payee-location ID from list_payee_locations, providing clear context on when to use this tool. It doesn't explicitly exclude alternatives, but the single-record-by-ID scope is clear enough to differentiate from list operations.

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 destructiveHint, so the description's 'Read-only' is redundant. However, it adds valuable behavioral context by stating that results are empty for payees never used in YNAB's mobile app, which is not covered by 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 concise and front-loaded with the core action. It contains three sentences, but the 'Read-only' phrase is redundant given the annotations, slightly reducing efficiency. Still, every other part contributes 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?

Given the presence of an output schema and safety annotations, the description covers the essential aspects: purpose, use case, and edge-case behavior (empty result). It does not explain return format, but that is delegated to the output schema, so it is adequately complete.

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

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

Schema description coverage is 100%, with both parameters already documented in the input schema. The description does not add any additional parameter-specific semantics, so it stays at the baseline for high 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 verb (Get) and resource (all recorded GPS locations for one payee), making the purpose obvious. It also specifies the scope 'for one payee,' which helps differentiate from list_payee_locations, though it does not explicitly name that sibling tool.

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

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

The description provides a concrete use case ('confirm which physical merchant an ambiguous payee refers to'), which implies when to use it. However, it does not mention when not to use it or point to alternative tools like list_payee_locations or get_payee_location, so 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, idempotent, non-destructive. The description adds meaningful beyond-annotation context: the ID format restriction and the list of returned fields. No contradiction with annotations.

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

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

Two tight sentences: purpose and output first, then the exclusion/fallback. Zero filler, perfectly front-loaded.

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

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

For a single-get read tool with an output schema available, everything an agent needs is covered: what it does, valid inputs, and when to use an alternative. Nothing missing.

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

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

Schema coverage is 100%, so baseline is 3. The description adds critical nuance about the ID format (not composite) and clarifies what is returned, exceeding what the schema provides.

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 specifies a clear verb+resource ('Get one scheduled (recurring) transaction by ID'), lists the exact fields returned, and explicitly contrasts with get_transaction. This distinguishes it from siblings.

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 states when NOT to use this tool (composite IDs are invalid) and provides the alternative (use get_transaction). This is concrete, actionable routing guidance.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds substantial behavioral detail: automatic composite ID handling, fallback to scheduled-transaction template with a marker shape, and strict behavior for non-composite IDs. It also clarifies the exact return shapes and error behavior, going well 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?

The description is dense but every sentence earns its place. It front-loads the core purpose, then details composite handling and return shapes. No fluff, well-structured, and easy to parse despite its length.

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

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

Given the tool's complexity (composite IDs, fallback behavior, two return shapes), the description is thorough. The output schema covers return values, and the description covers all edge cases and special handling. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100%, but the description adds crucial semantics: it explicitly warns that the argument is 'transactionId' (not 'id'), explains the composite ID format and stripping, and describes the fallback logic. This adds meaning that the schema alone doesn't provide.

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 'Get a single transaction by ID' – a specific verb and resource. It clearly differentiates from siblings like get_transactions and search_transactions by focusing on a single transaction via ID, and even clarifies the argument name. No ambiguity.

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

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

The description implies when to use (single transaction lookup) but doesn't explicitly name alternatives. However, it provides critical context on composite vs. non-composite IDs, which guides appropriate usage. It's clear enough for an agent to infer the right tool, though explicit exclusions would push it to a 5.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds substantial behavioral detail beyond that: the 500-row default cap with limit/offset pagination, the changed response shape when capped (returning metadata fields), and the YNAB default of sinceDate to one year ago. This gives the agent accurate expectations for pagination and response handling.

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

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

The description is dense but every sentence earns its place: purpose, payee disambiguation detail, pagination rules and response shape, and a routing recommendation. It is front-loaded with the core purpose and filters, then progressively adds operational details. No filler or 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?

Given 11 parameters, an output schema, and the presence of sibling tools, the description covers the essential operational aspects: filters, pagination, response format differences, and the default date behavior. The output schema handles return details, and annotations cover safety. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100% with descriptions for all 11 parameters, so the schema already explains each parameter. The description adds extra semantics for key parameters: the default behavior of sinceDate, the fact that limit is ignored for delta requests, and that offset follows YNAB's date-ascending order. These enrich the schema without repeating 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 states a specific verb ('List') and resource ('transactions'), enumerates the available filters, and explicitly contrasts with the sibling search_transactions by saying 'Prefer search_transactions to find specific rows.' This gives an agent a clear, distinct purpose without needing to open the schema.

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

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

The description clearly says to prefer search_transactions for finding specific rows, which is an explicit alternative and a when-not-to-use condition. It also implies usage for filtered listing via the enumerated filters. However, it does not contrast with get_transaction (single transaction retrieval) or other list_* siblings, so the routing guidance is not exhaustive.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the useful context that this tool exists primarily to verify the API token works, which is behavioral context beyond the annotations. No contradiction; 'Read-only' aligns with readOnlyHint=true.

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

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

Two sentences with zero waste; the purpose is front-loaded and the alternative is named in the second sentence. Every clause earns its place.

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

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

For a zero-parameter tool with an output schema (which documents return values) and annotations covering the safety profile, the description covers purpose, usage, and the routing decision. Nothing an agent needs to call it correctly is missing.

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

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

The tool has zero parameters and schema coverage is 100%, so there is nothing for the description to document. The description confirms 'takes no input,' which matches the empty schema. Baseline 4 applies for a zero-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 states a specific verb and resource ('Get the authenticated YNAB user (their user ID)') and specifies the exact output (user ID). It distinguishes itself from the key sibling ynab_auth_status by framing its purpose as token verification, so an agent can tell them apart without opening schemas.

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

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

Explicitly names the alternative (ynab_auth_status) and the condition that selects it ('for credential/config diagnostics prefer ynab_auth_status'), noting it needs no API request. This is explicit when-to-use vs. when-not-to-use guidance with a concrete sibling.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds value by noting closed accounts are included, the direct_import_in_error field, and the returned metadata. 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?

Three sentences with no filler: the core action comes first, followed by read-only clarification, use cases, and a helpful note about closed accounts. Every sentence earns its place.

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

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

For a read-only list tool with full schema coverage holes and a defined output schema, this description is complete. It tells the agent what will be returned, that closed accounts are included, and how it should be used.

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

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

Schema description coverage is 100%, and both budgetId and lastKnowledgeOfServer are already clearly described in the schema. The description adds no additional parameter-specific meaning beyond high-level context, so the baseline of 3 is appropriate.

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

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

The description starts with a specific verb and resource: 'List all accounts in a budget', and enumerates the exact fields returned (balances, type, status, last-reconciled time, debt metadata). It clearly distinguishes this tool from singular get_account and other list siblings by scope and content.

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?

States concrete use cases: finding account IDs for transaction tools, checking balances, and spotting direct-import errors. It also gives a filtering caveat for closed accounts. It does not explicitly contrast with get_account or other list tools, but the provided context is sufficient for a straightforward list operation.

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=true, idempotentHint=true, destructiveHint=false) fully cover the safety profile. The description adds no additional behavioral context beyond the schema and annotations; it doesn't mention pagination, ordering, or other side effects. The mention of 'last-used budget' implies state but is irrelevant given budgetId is not a parameter.

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 (two sentences), but the second sentence contains inaccurate and unnecessary information about budgetId. While brevity is good, the inclusion of a non-existent parameter makes the structure less helpful and could cause the agent to attempt invalid calls.

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 (one parameter, no required fields) and has an output schema, so the description doesn't need to explain return values. However, the misleading budgetId reference creates a gap in understanding—an agent cannot reliably know that the tool does not accept budgetId. This makes the description incomplete and potentially harmful.

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 references a 'budgetId' parameter that does not exist in the input schema, which actively misleads the agent. For the actual parameter includeAccounts, the schema already provides a complete description, so the description adds no value. The false budgetId reference is a serious flaw, lowering the score significantly.

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 core purpose is clear: 'List all budgets' specifies the verb and resource. It distinguishes from get_budget by implying a collection. However, the second sentence introduces a budgetId parameter that is not in the schema, which muddies the purpose and could confuse an agent about the tool's scope.

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

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

The description gives usage guidance about using a budget ID from results or omitting budgetId for last-used budget, but the input schema only defines includeAccounts and has no budgetId parameter. This is misleading and does not help an agent decide when to use this tool vs alternatives like get_budget. No explicit when-to-use or exclusions are 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 cover read-only/idempotent/safe, so the description's main added behavior is that hidden, deleted, and YNAB-internal items are included with flags. The current-month scope and the instruction to filter on flags provide useful behavior beyond the structured fields. No contradiction with annotations.

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

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

The description is front-loaded with the core action and contains the alternative tools and hidden-item behavior in a compact form. 'Read-only' is slightly redundant with the annotations, but the four sentences are otherwise dense and useful.

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

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

For a 2-parameter, read-only list tool with a full output schema and 100% parameter documentation, the description is complete. It covers scope, alternatives, return contents, and special items, so an agent can invoke it correctly without digging further.

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

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

Schema description coverage is 100%, so the schema already documents both optional parameters. The description doesn't add parameter-level detail beyond that, which is acceptable under the baseline for fully documented schemas.

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

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

The description opens with a specific action and object: 'List all category groups and their categories with budgeted/activity/balance amounts (dollars) for the current month.' It clearly distinguishes this from get_month and search_categories by naming those siblings, and it does not just restate the title.

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 use cases: find category IDs and survey the budget structure. It names get_month for a specific month's numbers and search_categories for name-based lookup, and it tells the agent to filter hidden/deleted/internal items when presenting. This leaves no ambiguity about when to select this 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 declare readOnlyHint, idempotentHint, and destructiveHint, and the description explicitly states 'Read-only', which matches. It adds semantic context by defining what a money movement group represents and how to join to movements, which goes beyond the structured fields. It does not cover pagination or ordering, but the output schema exists and the safety profile is clear, so this is solid coverage.

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 concise sentences, with the primary action ('List all money movement groups') front-loaded, followed by a clarifying definition and a join hint. There is zero redundant phrasing; every clause earns its place.

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

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

For a read-only list tool with an output schema and annotations covering safety, the description is largely complete: it defines the domain concept, states read-only behavior, and explains how to connect to related data. The only notable gap is not mentioning the sibling get_money_movement_groups_by_month, which could be the intended tool when filtering by month; however, this is a minor omission given the overall clarity.

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

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

The schema provides 100% coverage for the single optional parameter budgetId, including its description ('Budget ID (uses default if not provided)'). The description adds no additional meaning about the parameter—it does not even mention budgetId. Baseline of 3 is appropriate since the schema already documents the parameter 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?

The description clearly states the verb 'List' and the resource 'all money movement groups', and defines what a group is (batches of related money movements applied together). It also gives a concrete example (multi-category re-allocation), which distinguishes it from list_money_movements by implying the join relationship. This is a specific, unambiguous purpose.

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

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

The description explains how to relate this tool to list_money_movements via the join key, but it does not explicitly state when to use this tool versus get_money_movement_groups_by_month or other sibling tools. The usage context is implied (general list-all), but no explicit alternatives or exclusions are given, so it stops short of full guidance.

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

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

Annotations already declare readOnlyHint, destructiveHint, and idempotentHint, so the safety profile is covered. The description adds a performance warning ('can be long on old budgets') and clarifies the semantic distinction from transactions, which is valuable beyond the annotations.

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

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

Two sentences with no filler. The core purpose is stated first, followed by usage guidance and a performance note. Every sentence earns its place.

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

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

Given the tool's simplicity, the presence of annotations covering safety, and an output schema, the description fully covers purpose, usage, and performance caveats. Nothing essential is missing for an agent to call it correctly.

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

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

Schema coverage is 100% with a single optional parameter budgetId that is self-explanatory in the schema. The description does not add parameter-specific guidance, so baseline 3 is appropriate.

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

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

States a specific verb 'List' and resource 'money movements' with a clear definition of what they are (history of budget re-allocations) and explicitly distinguishes from transactions. It also names a sibling tool for scoped queries, making it unmistakable.

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 an explicit use case ('why did this category's assigned amount change') and an explicit exclusion (these are not transactions). It also advises preferring get_money_movements_by_month for a specific month, giving clear routing guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds contextual value by explaining the dollar-unit summary metrics and the tool's scope across all months, which goes slightly beyond the structured annotations.

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

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

Two well-structured sentences with no wasted words. The core behavior is stated first, followed by a precise routing note to the alternative tool.

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

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

For a simple read-only listing tool with an output schema, rich annotations, and optional parameters, the description fully covers what an agent needs to select and call it correctly. The delta parameter behavior is documented in 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 100%, so the schema fully documents both parameters. The description does not elaborate on parameter behavior beyond what the schema provides, meriting the baseline score.

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 ('List') with a precise resource ('all budget months') and enumerates the summary fields returned. It clearly differentiates from the sibling get_month by noting this is the month-level overview 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?

It explicitly states when to use the tool ('find which months exist and their headline totals') and names the alternative for per-category detail ('use get_month'). This gives an agent clear routing guidance with no inference needed.

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, non-destructive, so the bar is lower. The description adds behavioral context beyond annotations by disclosing the filtering rule ('only payees with mobile-recorded transactions appear') and data provenance ('GPS coordinates... recorded at transaction time'). This helps set expectations for empty results and data scope.

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 sentences, each earning its place: purpose, behavioral caveat, and alternative routing. No filler or redundancy. Front-loaded with the key action and context.

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 param, output schema present, annotations complete), the description covers the essential interpretation, result-sparsity behavior, and sibling differentiation. Nothing needed for correct invocation is missing.

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

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

Schema covers the sole optional parameter budgetId fully with 'Budget ID (uses default if not provided)', so baseline is 3. The description does not elaborate on parameter semantics, but the schema handles it completely; no additional meaning is required.

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

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

States a specific verb and resource: 'List all payee locations (GPS coordinates YNAB's mobile app recorded at transaction time).' It clearly distinguishes from sibling get_payee_locations_by_payee by noting the all-scope and by explicitly naming the scoped alternative.

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

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

Provides explicit guidance: 'Only payees with mobile-recorded transactions appear; many budgets have none' warns about result sparsity, and 'Use get_payee_locations_by_payee to scope to one payee' tells the agent exactly when to use the sibling instead.

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 destructiveHint=false, so safety is covered. The description adds significant behavior beyond that: the meaning of non-null transfer_account_id, the recommendation to use it as payeeId instead of inventing names, and the warning about list size. These are critical operational details not present in structured data and are highly relevant to correct invocation.

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

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

Three tight sentences: the first states the core function and key output field, the second adds the transfer payee nuance, the third routes to the alternative and warns about volume. No filler, no repetition; every sentence earns its place.

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

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

Given the tool's simplicity, full schema coverage, present output schema, and comprehensive annotations, the description provides all essential context. It covers the key output semantics (transfer payee), the performance characteristic, and the alternative tool. Nothing an agent needs to correctly select and call this tool is missing.

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

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

Schema description coverage is 100%, so both parameters (budgetId, lastKnowledgeOfServer) are fully documented in the schema. The description does not add any new parameter-level meaning beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb and resource ('List all payees with IDs and transfer_account_id'), distinguishes from siblings like search_payees and get_payee, and clarifies the critical transfer payee field. An agent can immediately understand what this tool does and how it differs from related tools.

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

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

Explicitly directs users to search_payees for name-based lookup and warns about long lists on mature budgets. It also instructs how to use transfer_account_id as payeeId for transfers, which tells the agent when to use this output. This is direct, actionable guidance on when to choose this tool versus 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 establish readOnly and idempotent behavior. The description adds critical behavioral context beyond those: the returned set excludes auto-imported recurring entries, which materially changes how an agent should interpret results. This prevents a subtle misuse that annotations alone cannot express.

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

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

The description is compact and front-loaded: it states the core purpose first, then the essential caveat the agent must know, then the fallback behavior. Every sentence carries important information with no filler.

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

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

Given the rich output schema, 100% parameter documentation, and safety annotations, the description covers the only significant gap: what class of items is actually included. The warning plus alternative makes the tool fully actionable for an agent.

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

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

Schema description coverage is 100%, and both parameters (budgetId, lastKnowledgeOfServer) already have meaningful descriptions. The tool description does not add parameter-level detail, which is acceptable under the baseline for fully documented schemas.

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 all scheduled (recurring) transactions') and immediately clarifies the exact scope: only manually-created recurring entries. This distinguishes it both from get_scheduled_transaction and from detection of auto-imported recurring charges, leaving no ambiguity about what the tool returns.

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

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

The description explicitly says when the tool should NOT be used—for auto-imported recurring charges such as subscriptions, utilities, and insurance—and gives an actionable alternative: use prior-month transaction history to identify those recurring charge timings. This is clear routing guidance.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds valuable context beyond annotations: it reads a local journal file, never the YNAB API, returns most recent first, and explains the meaning of undoable:false. This is transparent and consistent with the annotations.

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

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

Four sentences with no wasted words. The core purpose and ordering are front-loaded, followed by the read-only distinction, usage guidance, and the undoable:false caveat. Every sentence contributes necessary information.

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

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

For a single-parameter read-only tool with a rich description, an output schema, and safety annotations, this is complete. The description covers behavior, source, ordering, use cases, and a key edge condition; return format is covered by the output schema.

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

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

Schema coverage is 100% and the only parameter, limit, already has a full description including default and maximum. The tool description doesn't add further parameter semantics, so the baseline 3 applies given the schema handles the documentation burden.

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

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

States a specific verb and resource: 'List the local undo journal' with clear scope ('every write this MCP server performed'). It distinguishes itself from YNAB API tools by explicitly saying it reads a local journal file and never the YNAB API, making sibling differentiation 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?

Provides explicit use cases: review before calling undo_operation, or audit a session's writes. It also clarifies the limitation that entries with undoable:false are only for audit and cannot be reversed, giving agents actionable guidance on when the tool 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?

The description adds substantial behavioral context beyond the readOnlyHint/idempotentHint annotations: it explains flag semantics (match_broken is cosmetic and row remains editable, scheduled_transaction_realized is writable), degradation behavior (compact/summary fallback above thresholds), and response grouping details. This enriches the agent's understanding without contradicting 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 dense but well-structured, front-loading the core purpose and then logically detailing flags, grouping, and degradation. Every sentence adds unique value, and the use of semicolons and clauses keeps it readable. It is appropriately sized for the complexity of the tool.

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

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

Given the output schema exists (as indicated) and annotations cover safety, the description covers all necessary aspects: the categories, flags, grouping headers, degradation modes, and references to a flags reference. An agent can invoke the tool correctly and interpret the response without ambiguity.

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?

Despite 100% schema coverage, the description adds meaningful semantics: it explains the effect of summary:true and compact:true, the degradation logic tied to maxTransactions, and the default of 400. These behavioral details are not in the schema, significantly enhancing parameter understanding.

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: 'Unapproved transactions across all history', split into ready_to_approve and needs_category_first. It specifies the resource (unapproved transactions) and the action (review), distinguishing it from sibling tools like get_transactions or search_transactions. The verb and scope are explicit and not a tautology.

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

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

The description provides clear context for when to use the tool (reviewing unapproved transactions) and explains parameter usage for large queues (summary:true, compact:true, maxTransactions). However, it does not explicitly mention alternatives or when not to use it, leaving the selection among siblings to inference.

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 read-only, idempotent, non-destructive behavior, and the description adds valuable context beyond that: case-insensitive matching, tokenized OR semantics, ranking order, matched_on/matched_terms reporting, and no synonym expansion. This gives an agent clear expectations about how results are produced and labeled. No contradiction with annotations exists.

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 deliver the core matching behavior, ranking rules, result reporting, and a fallback instruction. Every clause earns its place, and the most important information is front-loaded.

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

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

For a search tool with a full output schema and annotations covering safety and idempotency, the description is complete. Required query behavior, matching edge cases, hidden-category handling in the schema, and fallback routing are all present, leaving no material gap for a correct invocation.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description enriches the query parameter with important semantics: case-insensitivity, tokenization, OR matching, and ranking behavior. budgetId and includeHidden remain adequately documented in the schema itself.

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 precise verb-resource pair, "search categories", and narrows scope to name plus category-group name. It also names list_categories as the fallback, making the tool's role distinct from that sibling without opening the schema.

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

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

The description explicitly gives an alternative and a condition: "if a search is empty, fall back to list_categories". It frames search as the lookup entry point, and the resource-specific wording naturally distinguishes it from search_transactions and search_payees.

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, and destructiveHint=false, covering safety. The description adds meaningful behavioral context beyond annotations: case-insensitive matching, HTML entity unescaping (with a concrete example), and the substring-vs-tokenized distinction. 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?

Three sentences with no filler. The core behavior and the most important caveat (HTML entity handling) are front-loaded, followed by a usage note and a sibling comparison. Every sentence earns its place.

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

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

With annotations covering the read-only/idempotent safety profile and an output schema present, the description sufficiently covers matching behavior, usage guidance, and the key sibling distinction. Nothing critical is missing for an agent to call this tool correctly.

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

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

Schema coverage is 100% and both parameters have basic descriptions. The description adds value beyond the schema by explaining the query semantics (partial, case-insensitive, HTML-entity-ignoring) and advising to search one word at a time. It doesn't clarify budgetId's default behavior beyond the schema, but the schema already says 'uses default if not provided'.

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 ('Search payees'), a resource ('payees'), and a precise matching behavior (partial, case-insensitive, HTML-entity-ignoring). It explicitly differentiates from the sibling search_categories by contrasting substring match vs tokenized OR, so an agent can select it correctly without inspecting the schema.

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

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

The description says the tool is 'useful for finding payee IDs' and gives a concrete usage tip ('search one distinctive word at a time'), plus contrasts with search_categories. It doesn't explicitly state when NOT to use it or list alternatives beyond the one sibling, but the context is clear and actionable.

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

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

Despite strong annotations (readOnlyHint=true, idempotentHint=true, destructiveHint=false), the description adds substantial behavioral detail: the server fetches and filters locally, query is a case-insensitive substring over specific fields, amount matches on absolute value with half-cent tolerance, results are newest-first, and pagination uses next_offset. This goes far beyond what the annotations alone communicate and is consistent with them.

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

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

The description is front-loaded with the core purpose and then efficiently delivers high-value details: implementation rationale, field coverage, amount tolerance, ordering, pagination, and a required-argument constraint. Every sentence earns its place. It is detailed but not bloated, and the most important information appears first.

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, eight-parameter tool, but the description covers the essential usage contract thoroughly: what is searched, how amount matching behaves, optional bounds, result ordering, pagination, and the minimum-argument requirement. An output schema exists for return shapes, and annotations cover safety, so no critical operational context is missing.

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

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

Schema description coverage is 100%, but the description still adds crucial meaning: the exact set of fields query searches, the absolute-value half-cent tolerance for amount, the account/date bounding behavior, and the requirement to provide at least one of query or amount. It also explains the limit/offset pagination contract with next_offset, enriching the schema's otherwise mechanical parameter descriptions.

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

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

The description opens with a specific verb and resource: 'Search transactions by text and/or amount, with pagination.' It clearly differentiates this from listing tools by emphasizing text/amount filtering and pagination, and even details the exact fields searched. An agent can immediately identify what this tool does.

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

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

The description gives clear context for use: it filters a potentially large YNAB transaction list and returns a small page, explicitly advising against multi-megabyte dumps that could exceed timeouts. It also states the requirement 'Provide at least one of query or amount' and explains pagination via next_offset. It does not explicitly name a sibling alternative such as get_transactions when no filtering is needed, so it stops short of a full when-to-use/when-not-to-use contrast.

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. The description adds specific context about checking credentials and write-tool enablement, which is useful beyond the generic annotations. It does not contradict 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?

Single, clear sentence with no wasted words. Verb and resource are front-loaded.

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

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

With an output schema present and no parameters, the description covers the essential purpose. It's complete for a status-check 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?

No parameters exist, so schema coverage is trivially complete. Baseline score of 4 applies as the description doesn't need to add parameter semantics.

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

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

States a specific action (Check) and resource (YNAB MCP server credentials and write tools enabled), clearly distinguishing it from the data-retrieval siblings. The title and description align perfectly.

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?

Description does not explicitly state when to use this tool vs alternatives, though it's clear it's a diagnostic status check. No exclusions or conditions are provided, but the purpose implicitly guides usage. Lacks explicit guidance on when to call it.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, and the description reinforces the read-only boundary while adding the routing behavior and the YNAB_ALLOW_WRITES condition. It does not describe failure behavior, but the output schema and annotations cover the main safety contract, so this is solid rather than exceptional.

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

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

Three sentences with the core purpose first, then the usage workflow, then the write-tool exception. Every sentence earns its place and no words are wasted.

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

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

For a generic dispatcher, the description covers discovery, parameter passing, the read-only restriction, and the alternative path for write tools. With output schema and rich annotations present, nothing essential is missing for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, so the schema already documents tool_name with examples and input and describes input as an optional JSON object. The description adds workflow context (use index first) but no additional parameter semantics beyond what the schema provides, making baseline 3 appropriate.

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

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

The description opens with a specific action—'Execute an existing read-only YNAB MCP tool by name'—and immediately separates this dispatcher from ynab_tool_index (discovery) and from direct write tools. This gives an agent a clear model of what the tool does and what it is not.

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 tells the agent to call ynab_tool_index first, then pass tool_name and JSON input, and it names the alternative path for write-capable tools (direct call or ynab_write_tool_execute when YNAB_ALLOW_WRITES=1). This is concrete when-to-use and when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the agent knows this is a safe, non-destructive operation. The description adds that the tool discovers available server tools, which is consistent with the annotations but does not add much beyond the title and the obvious meta-tool behavior. There is no 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 a single, front-loaded sentence with no filler. It opens with the action and object, then lists the relevant domains. Every word contributes to helping an agent decide whether to call this tool.

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

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

For a zero-parameter discovery tool with rich annotations and an output schema, the description is complete. It tells the agent exactly when to use the tool, what domains are covered, and the tool's safe read-only nature is already captured by annotations. No return-value explanation is necessary because an output schema exists.

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

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

The tool has zero parameters, and schema description coverage is 100%, so there are no parameter details that need compensation. The baseline of 4 applies because there is nothing to document; the description does not need to add parameter meaning.

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: 'Discover the YNAB MCP server tools.' It enumerates specific domain areas such as budgets, accounts, categories, payees, transactions, and cleanup tools, distinguishing it from the sibling tools that perform those operations directly. The verb 'Discover' plus the resource makes the meta-tool nature obvious.

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 explicit usage context: 'Use this when you need YNAB budgets, accounts, categories, payees, transactions, scheduled transactions, unapproved transaction review, approval, or budget cleanup tools.' This tells an agent when to invoke the tool, though it does not explicitly name alternatives or state when not to use it. For an index/discovery tool, this is clear and sufficient.

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