YNAB MCP Server

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, but the description adds substantial behavior beyond that: the per-mode request behavior ('one API request' without accountId vs. additional listing with accountId), an explicit 'Makes no changes' statement, and a genuinely useful interpretation note explaining that an old last_reconciled_at is not itself a problem if cleared_balance matches the bank. This equips the agent to interpret results, not just call safely.

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 longer than average but every sentence earns its place: purpose and mode behavior are front-loaded, safety and workflow contrast follow, and the interpretation note closes with actionable diagnostic insight. It is logically ordered and dense without being padded, though slightly wordy compared to the tightest possible version.

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 two-mode diagnostic tool with an output schema already present, the description covers everything an agent needs: what the tool produces in each mode, that it makes no changes, when in the workflow to use it, and how to interpret ambiguous results. The reconciliation domain concepts (last-reconciled date, cleared balance, uncleared transactions) are all explained. Nothing critical is left to inference.

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% — both budgetId and accountId already have meaningful descriptions in the schema, so the baseline of 3 applies. The description reinforces the accountId semantics by explaining what 'inspect in detail' produces (uncleared/unapproved transactions since last reconciliation), but adds no fundamentally new parameter-level information 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 opens with a specific verb+resource ('Read-only reconciliation diagnosis') and precisely enumerates the two behavioral modes: account-level summary without accountId, and detailed transaction listing with accountId. It clearly differentiates itself from siblings like get_transactions (raw retrieval), audit_credit_card_payments (a different audit target), and review_unapproved by framing itself as the 'find what needs attention first' diagnosis step.

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

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

The description gives explicit when-to-use guidance ('use this to find what needs attention first') and states what the tool is NOT for ('actual reconciliation... happens in the YNAB UI'), preventing an agent from attempting to perform reconciliation through this tool. It does not name a specific sibling alternative, but the timing and workflow context ('compare against the bank statement', 'before actual reconciliation') are clear enough for an agent to route 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 readOnlyHint=true and destructiveHint=false. The description adds valuable context about transient differences ('small transient differences appear while recent transactions are pending/uncleared') and interpretation notes, confirming it is non-destructive and explaining expected timeliness of data.

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

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

The description is well-structured with a clear first sentence stating the core purpose, followed by explanatory details. It is appropriately sized but could be slightly trimmed (e.g., 'Interpretation note' is slightly verbose). Nonetheless, it is efficient and 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, the description does not need to cover return values. It covers everything else: what the tool does, when to use it, behavioral notes, and interpretation guidance. Complete for a read-only audit tool.

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

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

Schema coverage is 100% and the description of the single parameter 'budgetId' in the schema is adequate ('Budget ID (uses default if not provided)'). The tool description does not add further parameter semantics, but given complete schema coverage, a 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 clearly states it is a 'read-only audit' comparing credit card balances to payment category balances. It specifies the verb 'audit', the resource 'credit card payments', and uniquely distinguishes itself from sibling tools like get_account or get_transaction by focusing on the audit/reconciliation of payment categories.

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

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

Provides explicit guidance: 'Makes no changes — fix shortfalls by assigning to the payment category via update_month_category.' This tells the agent when to use this tool (to identify shortfalls) and when not to, and points directly to an alternative tool for remediation.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior. The description adds valuable behavioral context beyond annotations: grouping logic, supported cadences, estimated annual cost, and concrete limitations such as missing variable-amount bills and payee spelling variations. 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 dense but well-organized: the opening sentence states the core function and mechanism, followed by clear use cases, differentiation from a sibling tool, and specific limitations. Every sentence contributes meaningful 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?

Given the rich annotations, complete parameter schema, and output schema, the description covers all necessary selection and usage context. It explains when to use the tool, what it cannot detect, and how to avoid misinterpretation, making it fully adequate 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?

All three parameters are fully documented in the schema with 100% coverage, so the description does not need to repeat them. The description adds some context about exact-amount grouping and cadence detection but does not substantially extend parameter-specific semantics beyond the schema.

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

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

The description clearly states the tool detects recurring charges from transaction history using a specific mechanism (grouping outflows by payee and exact amount, matching cadence). It also explicitly distinguishes itself from list_scheduled_transactions, making it easy for an agent to select the right 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 explicit use cases: subscription audits and 'what am I paying for' questions. It also names the alternative list_scheduled_transactions and explains when that tool is insufficient, plus warns against concluding a subscription was cancelled without verifying payee variants.

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?

Descriptors are already covered by annotations (readOnlyHint=true, idempotentHint=true, destructiveHint=false) and the description's 'Read-only' is consistent with them. The description adds genuinely valuable behavioral context beyond annotations: the leading-apostrophe CSV escaping to prevent spreadsheet formula injection, and a warning that large date ranges produce large output. Not exhaustive (no header-row or ordering guarantees), but substantial.

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 long but every sentence carries distinct payload: purpose, column semantics, formula-injection defense, usage routing, and output-size caveat. It is front-loaded with the core purpose. The only redundancy is 'Read-only', which merely repeats the annotations — minor, given the density of genuinely useful 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?

Given the 100%-covered schema, rich annotations, and an output schema, the description fills the important remaining gaps: the CSV format itself, dollar/negative-as-outflow column semantics, and the security-critical escaping behavior. Minor omissions such as header-row presence and exact date formatting are acceptable because the output schema exists and the core calling decision is fully supported.

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 8 parameters including the type enum and the one-year default in sinceDate are already documented structurally. The description only adds the cross-tool context 'same filters as get_transactions, including type', which helps an agent re-use knowledge of the sibling tool but does not enrich individual parameter meaning. Baseline 3 applies.

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

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

States a specific verb, resource, and output format: 'Export transactions as CSV text' with the exact column list spelled out (date, amount, payee, category, etc.). It is clearly differentiated from its most similar sibling, get_transactions, by the 'same filters as get_transactions' note plus the JSON-vs-CSV contrast.

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 routing rule: 'Use when the user wants data for a spreadsheet or offline analysis; for programmatic work prefer get_transactions (structured JSON).' It also gives operational guidance to narrow with filters when date ranges are large, leaving no ambiguity about when this tool is the right choice.

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, idempotentHint, and destructiveHint. Description adds 'Read-only' and 'fresh detail' implying no caching. This adds context 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, front-loaded with purpose, no wasted words. Every sentence is informative and 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 presence of output schema and comprehensive annotations, the description covers all necessary context: what it does, when to use it, and what data it returns. It distinguishes from a key sibling 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?

Input schema has 100% description coverage, so description adds minimal value. It reinforces that accountId is the primary key and mentions default behavior for budgetId, but no significant extra semantics.

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

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

The description specifies the verb 'Get', the resource 'one account', and lists specific details returned (balances, type, reconciliation timestamp, debt metadata). It clearly distinguishes from sibling list_accounts.

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

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

Explicitly states when to use this tool ('when you already have the account ID and want fresh detail') and when to prefer an alternative ('list_accounts when comparing several accounts').

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, destructiveHint=false, which the description does not contradict. The description adds transparency about the delta mechanism and response size limits, providing valuable behavioral context beyond annotations.

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

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

The description is well-structured, front-loading the basic purpose then detailing the delta feature. While verbose, every sentence adds value and the length is justified by the complexity of the dual behavior.

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 existence of an output schema, the description need not explain return values. It covers both modes (summary and delta), warns about size limits, and suggests alternatives, making it complete 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 coverage is 100% and both parameters have descriptions. The description adds significant context to lastKnowledgeOfServer (delta export, full budget export, size warnings) but does not add much to budgetId. Overall, it enhances understanding beyond the schema.

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

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

The description clearly states it gets a budget summary with specific fields (name, currency format, counts) and explains the delta export behavior. This distinguishes it from sibling tools like get_account or get_category.

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

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

The description provides explicit guidance on when to use the delta export (pass lastKnowledgeOfServer), warns about large responses and the 8 MB cap, and recommends dedicated list tools for incremental retrieval. This helps avoid misuse.

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, and the description adds meaningful behavioral context: it combines month data, account balances, and trailing-3-month summaries; explains the green/yellow/red thresholds; notes defaults are not YNAB rules; and discloses an approximate API cost of 4 requests.

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: what it returns, threshold interpretation, and when to use it. Front-loaded with the core purpose and 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 output schema exists and annotations cover safety, the description fully equips an agent to decide when to call it and what to expect. It also gives cost and usage-position context that structured fields do not.

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 does not add extra semantics for budgetId beyond what the schema already provides, but the schema is sufficient on its own.

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 ('snapshot') and resource ('budget health') and enumerates the exact metrics included. It clearly distinguishes itself from sibling tools by framing itself as a composite overview and 'opening move' rather than a drill-down 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?

Explicitly says to use it as the opening move of a monthly review or 'how am I doing' question, then drill into specific tools. This is clear contextual guidance, though it does not name particular alternatives or when-not conditions.

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 well covered. The description adds useful behavioral context by naming what settings are returned and clarifying that inputs are always canonical (dollars and YYYY-MM-DD), which goes beyond the schema and 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 tight sentences with no redundancy: the first states the resource, the second confirms safety, and the third gives precise usage guidance. Information is front-loaded and 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 full annotation coverage, an output schema present, one optional parameter, and a description that covers both when and when not to use the tool, nothing material is missing 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?

Schema description coverage is 100%, and the schema already documents budgetId as optional with a default. The description adds no additional parameter-specific detail, 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?

States a specific verb and resource ('Get a budget's settings') and names the exact contents: currency format (symbol, decimal digits, placement) and date format. This clearly distinguishes it from sibling tools like get_budget and list_budgets, which address different scopes.

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 when to use it ('when formatting amounts or dates for display') and when not to ('not needed for tool inputs, which always use dollars and YYYY-MM-DD'). This gives the agent actionable routing guidance and prevents unnecessary 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds the context of current-month scope and goal fields. No additional behavioral traits needed given annotation 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?

Two efficient sentences with no wasted words. The description is front-loaded with the action and scope, and every sentence provides value.

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

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

For a simple read tool with an output schema and clear annotations, the description covers purpose, usage guidance, and boundary conditions. No gaps remain.

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 does not add further meaning beyond the schema; it only implies the 'current month' context which is not a parameter.

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

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

The description clearly states it retrieves one category's full detail for the current month, including goal/target fields. It uses a specific verb ('Get') and resource ('category') and distinguishes from the sibling tool 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 states when to use ('for goal inspection') and when not to ('for a past or future month's numbers use get_month_category instead'), providing direct guidance on alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds valuable behavioral details: exclusion of transfers and deleted transactions, handling of credit card payments, and refund treatment, which are beyond what annotations provide.

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

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

Description is concise: first sentence states core purpose, then clarifies exclusions and use cases. Every sentence adds value with no wasted words.

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

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

Given the tool's complexity (include/exclude logic, savings rate calculation), the description is complete. Output schema exists, so return values are covered. No gaps noted.

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 parameters are fully documented. Description adds context about default values (6 months back, today) and date format, supplementing the schema without redundancy.

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

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

Clearly states it provides a read-only income vs spending summary by month, computed from transaction history. Distinguishes from siblings by specifying exactly what counts as income and spending.

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: for savings-rate reports, month-end closes, and trend questions. Also explains what is excluded (transfers, deleted transactions) and how refunds work, helping the agent avoid misuse.

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, and the description repeats 'Read-only'. It adds some useful context beyond annotations by explaining the groups are batched budget re-allocations and that the scope is a single month, but it does not disclose additional behaviors such as error cases or default budget 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 extremely concise: two short sentences plus a one-word read-only statement. The key scope information is front-loaded, and every sentence earns its place without redundancy.

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

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

Given the simple two-parameter schema, complete schema descriptions, rich annotations, and presence of an output schema, the description covers what an agent needs to invoke the tool correctly. It also names the sibling relationship, which helps routing.

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 month and budgetId are already documented in the input schema. The description's 'for one month' aligns with the month parameter but adds little beyond what the schema already states. 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' for a month. It also clarifies what these groups are ('batched budget re-allocations') and differentiates this tool from list_money_movement_groups by calling it the 'month-scoped view', so an agent can tell them apart.

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 identifies list_money_movement_groups as the broader sibling and frames this tool as its month-scoped counterpart, which conveys when this tool is appropriate. It does not explicitly state a when-not condition or name other alternatives like get_money_movements_by_month, but the context is clear.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. Description adds 'Read-only' and relationship to sibling, but does not significantly extend behavioral info 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?

Two sentences, no wasted words, front-loaded with purpose. Highly concise and well-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?

Given simple tool with output schema and rich annotations, description covers purpose, usage context, and relationship to sibling completely. No gaps.

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

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

Schema coverage is 100%, so baseline 3. Description does not add additional meaning to parameters beyond what 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?

Clearly states verb 'Get', resource 'money movements (category-to-category budget re-allocations)', and scoped to 'one month'. Distinguishes from sibling 'list_money_movements' by being month-scoped.

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 usage context: 'month-scoped view of list_money_movements' and 'use during month-end review'. Lacks explicit when-not-to-use but provides clear 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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful context about what data is included and that values are in dollars, making the tool's behavior more concrete than the annotations alone.

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

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

Two sentences, no filler. The first sentence front-loads the core purpose and return contents; the second adds use-case guidance and a pointer to the relevant sibling tool.

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

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

For a read-only tool with an output schema, two well-documented parameters, and annotations covering safety and idempotency, the description is complete. Nothing an agent needs to know before calling it is missing.

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

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

The input schema covers both parameters (month and budgetId) with clear descriptions, so the schema already does the heavy lifting. The description adds a high-level sense of what the month returns but does not add meaning beyond the schema for individual parameters.

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

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

The description states a specific verb and resource ('Get one budget month's detail') and enumerates exactly what is returned: month totals plus every category's budgeted/activity/balance and goal fields. It also distinguishes itself from sibling tools like get_month_category and get_overspent_categories by clarifying it returns the full month picture.

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 when to use the tool ('workhorse for monthly reviews and budget-vs-actual questions') and points to a specific alternative for a narrower need ('combine with get_overspent_categories for the negative balances only'). This gives an 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?

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds no additional behavioral context beyond the operation's scope, and it does not contradict 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 short sentence that is fully front-loaded and contains no filler. Every word contributes to conveying the tool's purpose.

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

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

For a simple read-only tool with a full output schema and comprehensive annotations, the description is adequate. The optional budgetId default behavior is documented in the schema, so 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 fully documents month, budgetId, and categoryId. The description adds no parameter-level detail beyond what the schema already provides, which matches the baseline.

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

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

The description states a specific verb ('Get'), a specific resource ('category budget'), and the scope ('for a specific month'). This clearly differentiates it from sibling tools like get_category or get_month, which target different resources.

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 the tool: when a category budget for a specific month is needed. However, it does not explicitly mention alternatives or conditions for choosing this tool over related siblings such as get_category or get_budget.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. Description adds domain context ('silently reducing Ready to Assign') but not further behavioral specifics; output schema handles return shape.

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

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

Two sentences, no filler; the core action is front-loaded and the use-case sentence earns its place.

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

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

For a simple read-only query with one required parameter, rich annotations, and an output schema, the description supplies the missing decision context. Nothing needed to call it correctly is absent.

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

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

Schema coverage is 100%, so month and budgetId are already documented in the schema. Description merely says 'given month' and does not add format or default behavior beyond schema.

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

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

States a specific action ('Get all categories with a negative balance') and scope ('for a given month'). This clearly distinguishes it from generic category/month listing tools and matches 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?

Explicitly tells the agent when to use it: to find prior-month overspends that are reducing current Ready to Assign. Does not name excluded alternatives, but the use-case framing is strong enough to route selection.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the bar is lower. The description reinforces read-only behavior and adds that the response includes a deleted flag, plus context on why the tool is useful. It does not cover not-found behavior, but for a simple getter this is a reasonable margin above baseline.

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 filler. The core action and resource are front-loaded, followed immediately by the primary use cases and the alternative. Every sentence earns its place.

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

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

For a simple get-by-ID tool with an output schema present and annotations covering the safety profile, the description provides purpose, use cases, and routing. Nothing required for correct invocation is missing; not-found behavior is a minor omission for a tool this straightforward.

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%: payeeId is described as 'Payee ID' and budgetId as 'Budget ID (uses default if not provided).' The description only adds that lookup is 'by ID,' which maps to payeeId, but does not materially enrich parameter meaning beyond the schema. 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: 'Get one payee by ID' and enumerates the returned fields (name, transfer_account_id, deleted flag). It also distinguishes itself from search_payees by noting that discovery should use the sibling tool, 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?

It states explicit use cases: 'confirm a payee still exists or resolve its transfer account,' and directly names the alternative for discovery ('for discovery use search_payees'). This gives an agent clear routing criteria without needing to inspect 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds that the ID must come from list_payee_locations, but it does not cover error handling, authentication, or default budget behavior. This is adequate but not rich.

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 redundant clauses. It states the purpose, the read-only nature, and the required ID source efficiently.

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 fetch, the annotations, input schema, and output schema cover the essential safety, parameter, and return-value information. The only notable gap is not explicitly distinguishing this from get_payee_locations_by_payee when the caller has a payee ID instead of a payee-location ID.

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 budgetId and payeeLocationId. The description only adds provenance for payeeLocationId by pointing to list_payee_locations, a minor bonus over the schema.

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

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

The description names a specific verb ('Get'), a singular resource ('one payee location record'), and a clear lookup mechanism ('by its ID'). It also lists the key returned fields (payee, latitude, longitude), which distinguishes it from list_payee_locations and get_payee_locations_by_payee.

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

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

The description gives a clear precondition: the caller needs a payee-location ID from list_payee_locations. It does not explicitly mention sibling alternatives or when not to use this tool, so it stops short of full 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, destructiveHint. The description reinforces 'read-only' and adds the important behavioral detail that results are empty for payees never used in the mobile app. 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 concise sentences with no extraneous information. The first sentence states the action and read-only nature; the second adds use case and a key behavioral note. Every sentence serves a purpose.

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 lookup tool with an output schema (not shown here), the description covers what it does, when to use it, and a crucial behavioral nuance. No additional context is needed.

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 parameters are fully documented in the input schema. The description does not add extra meaning beyond what the schema provides, hitting the baseline for a well-covered schema.

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

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

The description clearly states the action ('Get all recorded GPS locations'), resource ('for one payee'), and a specific use case ('confirm which physical merchant an ambiguous payee refers to'). It distinguishes from sibling tools like list_payee_locations by specifying 'for one payee'.

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

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

The description provides clear context on when to use the tool ('confirm which physical merchant an ambiguous payee refers to') and notes a behavioral outcome ('empty for payees never used in YNAB's mobile app'). It does not explicitly compare to alternatives, but the purpose is well framed.

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. The description adds behavioral context beyond annotations: it confirms read-only operation ('Read-only') and clarifies the ID format restriction. 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 sentences, concisely structured. First sentence defines purpose and returned fields. Second sentence provides critical usage guidance. Every sentence adds value with no redundancy.

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

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

Given the presence of output schema, the description does not need to explain return values in detail. It fully covers the essential behavioral nuance (ID format restriction) and is complete for this tool's complexity.

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 meaning beyond the schema by listing the returned data (next date, frequency, amount, payee, category) and highlighting the invalid composite ID pattern. This provides context not 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 clearly states 'Get one scheduled (recurring) transaction by ID' and lists specific fields returned (next date, frequency, amount, payee, category). It distinguishes from the sibling tool 'get_transaction' by noting that composite realized-transaction IDs are not valid here.

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 the tool (composite IDs with date suffix) and directs users to use 'get_transaction' instead for those cases. Provides clear context for correct invocation.

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

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

Adds significant behavioral detail beyond annotations: composite ID auto-stripping, fallback to scheduled transaction on deletion, and strict 404 for non-composite IDs. No contradictions.

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

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

Single paragraph, well-structured, front-loaded with main purpose followed by edge cases. No wasted words.

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

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

Covers all relevant behaviors: composite IDs, fallback return shape, strict mode. Output schema exists, so return value details are handled. Complete for a single-fetch tool.

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

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

Schema has 100% coverage, so baseline is 3. Description adds value by explaining composite ID handling for transactionId, which is semantic beyond schema.

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

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

The description clearly states it gets a single transaction by ID, with specific handling for composite IDs. It distinguishes from sibling tools like get_scheduled_transaction and get_transactions.

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

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

Provides clear context for when to use (single transaction retrieval). Implicitly contrasts with get_transactions for multiple. Lacks explicit when-not-to-use statements but covers composite ID edge case.

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

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

Annotations already indicate read-only and non-destructive behavior. The description adds value by disclosing default sinceDate behavior, data size warnings, and the inclusion of 'import_payee_name_original' field with its raw merchant string details, providing behavioral context beyond annotations.

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

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

The description is a single, dense paragraph that front-loads the main purpose and filters. Each sentence adds value without redundancy, but it could benefit from slight restructuring for readability. It is appropriately sized for the 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 tool's complexity (9 parameters, optional filters, filter combinations) and the existence of an output schema, the description is comprehensive. It covers filter strategies, default behavior, data volume warnings, and a critical field explanation, making it complete enough for effective tool usage.

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 baseline is 3. The description adds extra meaning by explaining filter combinations and default behaviors, such as the one-year default for sinceDate, and highlights the significance of a parameter field ('import_payee_name_original') not detailed in schema, enhancing semantic 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 'Get transactions with optional filters', specifying the resource (transactions) and action (get). It provides distinct filter types and a key field ('import_payee_name_original'), differentiating it effectively from singular get_transaction and list tools among 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?

The description gives clear guidance on filter combinations (e.g., combining accountId with month) and warns about large date ranges, but does not explicitly mention when to use alternative tools like get_transaction or search tools. It has clear context but lacks exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false. Description adds that it is read-only and takes no input, and that it returns the user ID. No contradictions.

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

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

Two sentences, front-loaded with purpose and result. Every sentence adds value: first describes action and return, second provides usage guidance.

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 no parameters and presence of output schema, description fully covers purpose, return value, use case, and alternatives. No gaps.

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

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

No parameters, baseline is 4. Description correctly states 'takes no input', leaving no ambiguity.

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 the verb 'Get' and resource 'authenticated YNAB user (their user ID)'. Distinguishes from sibling 'ynab_auth_status' by clarifying that this tool returns user ID and verifies the API token, while the sibling is for diagnostics.

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 (verify API token works) and when not to (prefer ynab_auth_status for credential/config diagnostics). Also notes it takes no input, which simplifies usage.

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, idempotency, and non-destructiveness, so the description's 'Read-only' adds minimal new information. However, it adds useful behavioral context beyond annotations: the tool includes closed accounts, returns direct_import_in_error, and requires filtering if only active accounts are wanted. This helps the agent set expectations correctly.

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

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

The description is compact and front-loaded: the core action and result come first, followed by practical use cases and filtering guidance. Every sentence adds value and there is no redundant filler or restating of the tool name.

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

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

The tool is a low-complexity list operation with an output schema, full parameter documentation, and annotations covering safety. The description adds the missing domain context: what the list contains, why you would use it, and how to handle closed accounts. Nothing critical is missing 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?

Schema description coverage is 100%, so both parameters (budgetId and lastKnowledgeOfServer) are fully documented in the schema. The description does not add parameter-level detail beyond that, which is acceptable given the high coverage. It mentions 'budget' contextually but does not explain the delta-request behavior; the schema already does.

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') and identifies the resource ('all accounts in a budget'), then enumerates the returned fields (balances, type, status, last-reconciled, debt metadata). It clearly distinguishes itself from single-account or other list tools by emphasizing 'all accounts' and account-ID lookup for transaction tools.

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

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

The description states explicit use cases: finding account IDs for transaction tools, checking balances, and spotting direct-import errors. It also gives filtering guidance for closed accounts. It does not explicitly name get_account as the alternative for single-account lookups, so it misses a small opportunity to clarify when not to use 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=true and idempotentHint=true, so the description's 'List all budgets' is consistent. However, the description adds no further behavioral context beyond the annotations, and the misleading parameter reference slightly detracts.

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 has two sentences; the first is concise and relevant, the second is confusing and unnecessary. It could be more focused on the actual parameter.

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 simple tool with one optional boolean parameter and an output schema, the description partially explains the tool's purpose but fails to mention the includeAccounts parameter. The misleading reference to budgetId reduces completeness.

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

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

Schema description coverage is 100% (1 parameter described), but the description does not explain the includeAccounts parameter. Instead, it introduces a non-existent budgetId parameter, which misleads about the tool's input requirements.

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

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

The description clearly states 'List all budgets' which is a specific verb and resource. However, it also mentions 'omit budgetId to use the last-used budget' despite budgetId not being a parameter in the schema. This introduces confusion and reduces clarity.

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 attempts to guide usage by suggesting to use a budget ID from results, but the reference to 'omit budgetId' is misleading because budgetId is not a parameter. No explicit when-not-to-use or alternatives 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral detail beyond annotations: the return includes hidden and deleted items flagged for filtering, amounts are in dollars, and the data is scoped to the current month. This gives the agent context about what to expect without relying solely on schema.

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

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

The description is compact and front-loaded: main purpose first, then usage guidance, then an important data-quality caveat about hidden/deleted items. Every sentence contributes new information, with no filler or repetition of schema details.

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

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

Given the simple two-parameter schema, rich annotations, and the presence of an output schema, the description covers what an agent needs: scope, purpose, alternatives, and how to handle hidden/deleted entries. There are no obvious missing prerequisites, side effects, or return-behavior gaps that would prevent 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%, and both parameters (budgetId and lastKnowledgeOfServer) already have meaningful descriptions. The tool description does not add extra parameter-level semantics, which is acceptable because the schema carries the load. 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 action (list) and resource (all category groups and categories), plus the output scope (budgeted/activity/balance amounts for the current month). It also distinguishes itself from related tools like get_month and search_categories, making the tool's role immediately clear.

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 when to use this tool: to find category IDs and survey the budget structure. It also names alternatives for adjacent use cases: get_month for a specific month's numbers and search_categories for name-based lookup. The hidden/deleted filtering instruction adds practical guidance for presenting results.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. Description adds useful context about the grouping behavior and how to join with list_money_movements, which is beyond annotation 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?

Two sentences, no wasted words. Purpose and key usage hint 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?

Output schema exists, so return values are covered. Description explains purpose and data relationship. Could be improved with explicit when-to-use/not-to-use compared to sibling list tools.

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. Description does not add any additional information about the budgetId parameter beyond 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 clearly states verb 'List', resource 'money movement groups', and provides context ('batches of related money movements applied together'). It also differentiates from sibling tools by mentioning the join to list_money_movements.

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 guidance: 'Read-only' and suggests using results with list_money_movements. However, no explicit when-not-to-use or alternatives beyond the join hint.

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 that: the result can be long on old budgets, and the tool returns budget moves rather than transactions. This helps the agent anticipate response size and semantic meaning.

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 deliver purpose, semantic clarification, use case, and a routing recommendation to a sibling tool. There is no filler, and the most important definition 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?

Given the tool's simple shape (one optional parameter, rich annotations, output schema present), the description covers everything needed to select and invoke it correctly. It explains what it returns, when to use it, and when to prefer an alternative, so no critical 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%: the single optional budgetId parameter is documented with 'Budget ID (uses default if not provided)'. The description does not add parameter-level detail, but with complete schema coverage 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 clearly states the action ('List all money movements') and defines the resource as the history of budget re-allocations, including who, how much, from where, to where, and when. It explicitly distinguishes money movements from transactions and names the sibling tool get_money_movements_by_month, making 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 gives an explicit use case ('why did this category's assigned amount change'), explicitly excludes transactions, and recommends a specific alternative (get_money_movements_by_month) when a specific month is needed. This is exactly the kind of when-to-use and when-not-to-use guidance an agent needs.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds context by stating it is 'Read-only' and describing the returned summary numbers. While it doesn't mention potential limitations like pagination, the added context is sufficient given 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 concise, consisting of two sentences with no unnecessary words. It front-loads the primary purpose and then provides usage guidance. Every sentence serves a clear purpose.

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, an output schema exists (so return values are documented), and the description covers usage, purpose, and alternatives. The description is complete for the agent to understand when and how to use this tool effectively.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add new information about the parameters beyond what is in the schema. It implicitly relies on the schema to define the two optional parameters.

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

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

The description clearly states the tool's purpose: 'List all budget months with summary numbers per month' and specifies the fields returned. It also distinguishes from the sibling 'get_month' tool by mentioning that for per-category detail, one should use 'get_month'.

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 when to use this tool ('use to find which months exist and their headline totals') and when not ('for per-category detail in one month use get_month'). It provides a clear alternative, which helps the agent decide 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 readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds that it lists GPS coordinates recorded at transaction time and that only payees with mobile-recorded transactions appear, which is useful behavioral context 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?

Three sentences, all valuable and front-loaded with the core purpose. No unnecessary words, and the structure is clear.

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 comprehensive annotations, the description sufficiently covers the tool's behavior, constraints (only payees with mobile records), and relationship to the sibling tool. It is complete for its complexity.

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 parameter description in the schema already states 'Budget ID (uses default if not provided).' The tool description does not add any information about the parameter beyond what the schema provides, so it meets the baseline but does not exceed 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 explicitly states it lists all payee locations (GPS coordinates), and distinguishes from the sibling tool get_payee_locations_by_payee by noting the scope difference. Verb 'list' + resource 'payee locations' is specific.

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: 'List all payee locations' and points to the sibling tool for scoped queries. It also notes that only payees with mobile-recorded transactions appear and many budgets have none, which helps set expectations. However, it does not explicitly list when-not-to-use.

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

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

Annotations already indicate read-only and non-destructive behavior. Description adds transfer payee nuance and declares read-only, but omits potential pagination or rate limiting.

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 essential information, front-loaded with action and key outcome. No redundant text.

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

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

Covers transfer payee usage, alternative search tool, and read-only nature. Could mention output schema or pagination but not necessary given the tool simplicity.

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

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

Schema already covers both parameters with full descriptions. Description does not add new parameter-level detail beyond what the schema provides, so baseline 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?

Description clearly states 'List all payees with IDs and transfer_account_id' and distinguishes transfer payees. It also contrasts with search_payees, making 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?

Explicitly advises to prefer search_payees for name-based lookup and notes that lists can be long, guiding appropriate usage.

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 readOnlyHint, destructiveHint=false, and idempotentHint. The description adds important behavioral context: only manually-created entries are returned, not auto-imported ones. No contradictions but no additional details on pagination or rate limits.

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 every word contributes to clarity. 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?

Given the presence of an output schema (as indicated by context signals), the description need not explain return values. It adequately covers the tool's key limitation and offers guidance, making it complete for a list tool.

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

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

Schema coverage is 100%, so the description does not need to add param details. It does not provide extra meaning beyond the schema, meeting the baseline.

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

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

The description clearly states the tool lists scheduled (recurring) transactions and specifies it only includes manually-created entries, distinguishing it from auto-imported charges. This provides a specific verb+resource with a clear scope.

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

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

The description explicitly states when to use (manually-created recurring entries) and when not to (auto-imported charges), and suggests using prior-month transaction history as an alternative for auto-imported timing.

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. Description adds that it reads a local file never the YNAB API, and explains undoable:false entries, providing additional context beyond annotations.

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

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

Three sentences, no fluff. Front-loaded with main function, then usage and caveats. Every sentence adds value.

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

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

The description fully covers what the tool does, when to use it, and what the entries mean. With output schema present, no need to explain return values.

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 describes the limit parameter well. Description does not add meaning beyond the schema, 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?

The description clearly states it lists the local undo journal of writes, most recent first, with undo capability. It distinguishes from sibling YNAB API tools by specifying it reads a local journal file.

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 to use it before calling undo_operation or to audit writes. It also notes entries with undoable:false are for audit only. No explicit when-not-to, but context makes it clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered — and the description then adds substantial behavioral context: matched_transaction_id is read-only via this API and requires YNAB UI to clear, scheduled entries have composite ids, category_name is null for mixed groups, total is a NET that can hide refunds via mixed_amount_signs, and the safety rule 'Never approve uncategorized transactions without explicit user instruction'. This is exactly the kind of non-obvious runtime behavior an agent needs.

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 purpose and nearly every sentence carries substantive content, so it earns its length. However, the match_broken flag explanation is a single ~90-word nested parenthetical with multiple clauses stacked inside it, and the flag list reads as a dense run-on; the structure would benefit from bullets or split sentences even if the total length stayed the same.

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

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

The description covers every semantic nuance needed to interpret the response correctly: all six flag meanings, group-header invariants (category_name null when mixed, mixed_amount_signs revealing net-hidden refunds), read-only vs mutable fields, the 100KB response-size behavior, and the explicit prohibition on approving uncategorized transactions. An output schema exists, so raw shapes are covered structurally, and what the description adds is the meaning layer — 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 baseline is 3 — the schema already documents compact, summary, and budgetId in detail. The description adds a high-level restatement of the summary/compact trade-off (counts vs per-transaction rows) and ties it to the 100KB overflow behavior, which is modest added value but not enough to push above baseline.

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

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

The opening sentence states a specific verb and resource — 'Get all unapproved transactions grouped by status' — and the ready_to_approve vs needs_category_first split defines a scope that is clearly distinct from the generic get_transactions/get_transaction siblings. The grouping-by-readiness framing makes the tool's unique role unmistakable 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 gives explicit conditional guidance: 'For large budgets the full response can exceed 100KB; pass summary:true... or compact:true' — clear context for when to use each mode. It stops short of an explicit when-not-to-use statement or direct sibling routing (the 'drill into specifics with get_transactions afterwards' pointer lives in the schema, not the description), so it earns a 4 rather than a 5.

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

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

Annotations already declare this is read-only and idempotent, but the description goes far beyond that: it discloses tokenization, OR-matching, ranking priorities, matched_on fields, HTML entity handling, whitespace collapsing, and explicitly warns about the absence of synonym expansion. This gives the agent a precise model of how results are produced and how to interpret 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 long but every sentence carries operational value: matching rules, ranking, result interpretation, escaping behavior, a negative case, and a fallback instruction. It is front-loaded with the core behavior and closes with actionable 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 search tool with an output schema already present, the description covers everything an agent needs to select and invoke it correctly: what is searched, how matching works, how to interpret results, and what to do when results are questionable. The mention of fallback to list_categories completes the decision loop.

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

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

Schema coverage is 100% and the query parameter's schema description already includes an example. The tool description adds meaning beyond the schema by explaining tokenization, OR-matching, ranking, and matched_on semantics, which materially improves the agent's understanding of the query parameter and its results.

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'), a resource ('categories'), and the key behavior: case-insensitive partial match against both category name and category-group name. It includes concrete details like tokenized OR-matching and result ranking that clearly distinguish it from the sibling list_categories and get_category tools.

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

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

The description explicitly tells the agent when to fall back to list_categories ('When a search comes back empty or looks wrong'), which is clear alternative-selection guidance. It also explains the search semantics so the agent can judge whether the tool fits the current need versus doing a full dump.

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 meaningful behavioral context beyond annotations: case-insensitivity, HTML entity escaping behavior, and single-substring matching. There is no contradiction with the annotations.

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

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

Three dense, purposeful sentences. The core behavior is front-loaded, the HTML entity example makes a subtle behavior concrete, and the alternative-tool comparison is placed at the end. Every sentence earns its place with no repetition or 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?

This is a simple read/search tool with strong annotations, a complete input schema, and an output schema present. The description covers the search behavior, provides an example, and gives usage guidance. Nothing material 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?

Schema coverage is 100%, so the baseline is 3. The description nonetheless adds real semantic value to the 'query' parameter by explaining case-insensitivity, HTML entity handling, and substring matching behavior. It does not add anything about budgetId, but the schema already fully documents that parameter.

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: 'Search payees by partial name match (case-insensitive).' It also distinguishes itself from the closest sibling, search_categories, by explaining the matching semantics. This fully clarifies what the tool does and how to tell it apart.

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 compares this tool to search_categories and explains why it is different ('single substring match, not a tokenized OR'). It also gives practical guidance: 'Useful for finding payee IDs' and 'search one distinctive word at a time.' This clearly tells an agent when and how to use it.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior, so the description does not need to restate those. It does add useful context about what is being checked (credentials and write-tool enablement), which is more specific than the tool name alone, though it does not describe response details or side effects beyond that.

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

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

A single sentence that front-loads the core purpose and states both checks without wasted words. Every word earns its place.

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

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

For a zero-parameter status-check tool with an output schema and safety annotations already provided, the description is complete. An agent can understand what the tool does, what it checks, and that it is safe to invoke.

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

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

The tool has zero parameters, so there is no parameter semantic burden for the description to carry. The baseline of 4 applies because no parameters exist to document and the schema covers everything relevant.

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 ('Check') against a clear resource (YNAB MCP server auth state) and names exactly what is verified: credential configuration and write-tool enablement. This clearly differentiates it from the data-query siblings like get_user or 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 implies the tool is useful for determining whether the server is ready and whether write operations are allowed, but it does not explicitly state when to call it or how it relates to the write-capable siblings like ynab_tool_execute. Usage context is present but only by implication.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds context about write tools and the need for YNAB_ALLOW_WRITES=1, which is valuable behavioral information 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?

Two concise sentences with no wasted words. Information is front-loaded: first sentence states core purpose, second adds usage guidance.

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 existence of an output schema (not shown but indicated), the description is complete. It covers how to discover tools, how to call them, and write tool alternatives. The tool is a generic executor, so no need to list siblings.

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 description adds useful guidance: 'Omit or pass an empty object for tools that take no input.' This supplements the schema's description of the input parameter.

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

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

Description clearly states the action ('execute'), the resource ('read-only YNAB MCP tool'), and distinguishes from write tools. It also mentions the prerequisite tool ynab_tool_index.

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 advises to use ynab_tool_index first for discovery, and specifies that write tools must use a different pathway (ynab_write_tool_execute). Provides clear 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 indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false, which align with the description's 'Discover' verb. The description adds value by explaining that the tool lists available tools, going beyond annotation safety profile.

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

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

The description is two sentences, front-loaded with the core purpose. Every sentence is informative with no wasted words.

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

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

For a simple index tool with no parameters, the description fully captures purpose and usage context. The existence of an output schema is noted but not required to be described.

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 100% schema description coverage, so no additional meaning is needed. The baseline score of 4 applies as the description correctly omits parameter 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?

The description uses the specific verb 'Discover' and clearly states it is a tool index for YNAB MCP. It lists the capabilities (budgets, accounts, etc.) and distinguishes it from sibling tools that perform specific actions.

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 'Use this when you need YNAB budgets, accounts...' providing clear context for when to invoke. It implies discovery before using specific tools, though it lacks explicit when-not-to-use or alternative guidance.

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