YNAB MCP Server

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

Annotations already cover readOnly/idempotent/non-destructive, so the description adds value by disclosing that everything comes back in one request and that accountId expands the payload with uncleared/unapproved rows since reconciliation. It also pre-empts a false-positive interpretation (old dates are not errors when balances match), which is genuine 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?

Purpose is front-loaded in the first sentence and every subsequent sentence carries a distinct instruction. Phrasing is telegraphic ('(one request)', 'Reconcile in YNAB UI') and slightly clipped, but there is no redundant 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?

An output schema exists, so return-value detail is not required, and the description supplies the interpretive guidance an audit tool needs. The remaining gap is the undocumented budgetId and no explicit statement of what happens when accountId is omitted versus supplied beyond the schema's own note.

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 50%: accountId is documented in the schema, and the description adds 'since reconciliation' and 'for bank comparison' meaning on top of it. budgetId, however, is left entirely undocumented in both the schema and the description, so the description does not compensate for the coverage gap. Baseline 3 for this coverage level.

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 ('Summarize') and a concrete resource ('open-account reconciliation dates and cleared/uncleared balances'), which is distinct from any sibling (e.g., audit_credit_card_payments, get_account). No sibling is named as an alternative, so it stops short of a 5, but the resource scope is 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?

'Reconcile in YNAB UI' is an explicit boundary statement telling the agent this tool inspects but does not mutate. 'Old dates alone are not errors if cleared balance matches; inspect older uncleared rows' gives interpretive guidance on how to act on results. Still no explicit 'use X instead when...' routing to 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 goes beyond them by explaining the expected value model ('negated card balance for budgeted spending') and by flagging that small/same-day pending differences may be timing artifacts — real interpretive guidance that prevents false positives.

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

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

Four short clauses, front-loaded with the core comparison, then remediation, then the interpretation rule. Dense but each sentence carries information; the telegraphic phrasing ('negated card balance for budgeted spending') is terse but still parseable.

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

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

An output schema exists, so return formatting need not be explained, and the description instead supplies the comparison rule and remediation path an agent needs to act on the result. Minor gap: no mention of default budget resolution when budgetId is omitted.

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?

There is one parameter (budgetId) with 0% schema description coverage, so the description would need to compensate and it does not mention the parameter at all. The parameter is a common convention across the sibling set, so the baseline 3 is fair rather than a hard failure.

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 concrete verb and comparison ('Compare open credit/line-of-credit balances to payment-category available dollars') and says what it produces (difference/status). An agent can distinguish it from read-only listing tools like get_overspent_categories, though no sibling is named explicitly for 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?

Gives a next-step rule ('Fund shortfalls via update_month_category'), which implies the intended workflow. However, it never says when to prefer this over adjacent audits such as audit_account_reconciliation or get_budget_health, and there are no stated prerequisites or exclusions.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior, so the description's job is to add beyond that — and it does: data-source differences vs. scheduled tools, false negatives on variable amounts, group splitting from payee variants, and an annualized cost estimate. These accuracy caveats are exactly the behavioral context an agent needs before trusting the output.

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?

Very compact and front-loaded: capability, then data-source scope, then limitations, then the suggested follow-up check. Every clause carries information. The telegraphic, semicolon-chained style borders on fragmented ('Payee variants split groups'), which slightly hurts readability against the otherwise high information density.

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

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

An output schema exists, so return values need no explanation, and annotations cover the safety profile. The description supplies the remaining decision-critical context: cadence coverage, estimation of annual cost, and known detection gaps. The only real omission is the role of budgetId and whether results are budget-scoped or all-budgets, which leaves a small gap for a 3-parameter 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 67%, so the schema already documents monthsBack (with its default and the rationale for longer windows) and minOccurrences (default 3). The description adds nothing about any parameter, and budgetId remains undocumented in both places. The cadence list implies why a longer monthsBack matters, but that is inference rather than stated semantics, so baseline 3.

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

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

States a specific verb and resource ('Find recurring outflows') plus the detection method ('by payee/exact amount') and the cadence set it recognizes. It also differentiates itself from the scheduled-transaction siblings by noting it 'Includes auto-imports absent from scheduled tools.' An agent can identify the tool and its distinct niche without opening the schema.

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

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

Gives a concrete next step ('check search_payees before concluding cancellation') and implicitly routes away from list_scheduled_transactions by naming what that family misses. It also states a disqualifying condition ('misses variable amounts'), which helps an agent pick a different approach. It stops short of naming an explicit alternative for the variable-amount case, so not a full 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 readOnly/idempotent/non-destructive, yet the description adds real behavior: CSV formula-injection defense (apostrophe prefix on formula-leading text) and row-cap truncation semantics. It omits auth requirements and any server-side limits beyond maxRows, so it stops short of full disclosure.

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 sentences with the output format and column list front-loaded, followed by safety notes and the routing hint. Every clause carries information an agent would otherwise have to infer.

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 need not explain return values, and it still sketches the CSV shape, sanitization, and truncation behavior. The only gap is the undocumented budgetId filter, a minor omission for an all-optional-parameter export 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 89% and the schema already documents type, month, maxRows, date filters with defaults and truncation reporting. The description adds only the amount-sign convention and a nudge toward narrowing dates; it says nothing about budgetId, the one parameter lacking a schema description.

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

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

States a specific verb+resource ('Export filtered CSV') and enumerates the exact output columns, including the sign convention for amounts. It also explicitly contrasts itself with get_transactions, so an agent can distinguish it from the JSON-based sibling without reading 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?

'prefer get_transactions for JSON' names the alternative and the condition that selects it, and 'Narrow date ranges to limit output' advises on scope. It does not state outright exclusions (e.g., when not to export at all), which keeps it short of a 5.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety burden is covered; the description adds genuinely new behavior — horizon default and cap, exclusion of overdue/unscheduled items, disclosure of omitted schedules, and handling of ambiguous twice-monthly anchors. It stops just short of describing pagination or output shape in detail, though the output schema covers 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?

Three dense sentences with the scope first and exclusions after; nearly every clause carries information. Minor cost in readability from stacked domain jargon ('end-of-day minimum/negative balances, evidence and omitted schedules').

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

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

An output schema exists, so return values need not be spelled out, yet the description still summarizes the report contents and discloses modeling caveats (exclusions, ambiguous anchors) that an agent needs to interpret results honestly. Only the unexplained budgetId keeps it from being fully self-sufficient.

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

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

With only 33% schema coverage, the description carries most of the burden: it supplies the horizonDays default and maximum and the transfer-scope nuance for accountId (reinforcing the schema). budgetId is left entirely undefined in both schema and description, which is the main gap for a 3-parameter tool.

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

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

States a concrete verb and resource: read-only ledger balances projected forward through scheduled payments/income/transfers. The parenthetical scope (default 30 days, max 365) and the explicit exclusions pin down exactly what the number means, which no sibling tool provides.

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

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

Gives clear when-not guidance: current/overdue entries and unscheduled spending are excluded, and it is explicitly 'not bank settlement or available-to-spend guidance.' It does not name a sibling alternative for actual/current balances, so it stops short of a full when/when-not/alternative set.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered and the description needn't restate it. The description adds the shape of the payload (balances, type, reconciliation time, debt metadata), which is a modest but real value-add; it does not cover auth requirements, error behavior, or whether the account must be on-budget.

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

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

Two short sentences with zero filler, and the core purpose is front-loaded ahead of the sibling routing hint. Every clause earns its place.

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

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

The tool is simple, annotations are rich, and an output schema exists, so return values do not need explaining — the description is largely adequate. However it never clarifies the optional budgetId, which for a budget-scoped read tool is the one thing an agent is most likely to get wrong.

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

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

Schema description coverage is only 50%: accountId is described tautologically ('Account ID') and budgetId carries no description at all, so ambiguity remains about whether budgetId is optional and what it defaults to. The description says nothing about either parameter to compensate for that gap, leaving the burden entirely on an under-documented schema.

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

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

States a specific verb and resource ('Get account') and enumerates the concrete data it returns (dollar balances, type, reconciliation time, debt metadata), which tells an agent exactly what it will learn. It also names the sibling it is not ('For comparisons use list_accounts'), so it is distinguishable without opening either schema.

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

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

Explicitly routes the agent to list_accounts when it needs comparisons, giving a concrete condition that selects the alternative. It stops short of stating other when-not cases (e.g. fetching many accounts, or when only balances are needed), so it is clear context but not a full decision tree.

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, so the safety profile is covered. The description adds genuinely non-obvious behavior: the implicit-cursor semantics of lastKnowledgeOfServer, that zero means a full export, and the response-size hazard. That is real added context beyond structured fields.

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

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

Two dense sentences with no filler, and the output inventory is front-loaded ahead of the cursor caveat. The phrasing is telegraphic ('zero requests full export'), which costs a little readability but wastes nothing.

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

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

An output schema exists, so return values needn't be spelled out, and the description correctly focuses on the risky parameter path and the size ceiling. The one gap is the undocumented budgetId (optional, but its omission vs required scope is unstated) — otherwise an agent has enough to call this correctly.

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

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

Schema coverage is only 50% (budgetId has no schema description), so the description must compensate. It does so well for lastKnowledgeOfServer — explaining the cursor, the changed-entities-plus-server_knowledge return shape, and the zero/export edge case — which is more than the schema states. budgetId remains unexplained, keeping this short of a 5.

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 gives a concrete inventory of what the call returns (name, currency format, account/category/payee counts), which is specific beyond the bare name 'Get Budget'. It does not, however, distinguish this from the sibling get_budget_settings or list_budgets, so an agent must infer the boundary. Clear purpose, missing sibling differentiation.

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

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

It gives a real routing hint — 'Prefer incremental deltas/list tools' — plus the concrete failure mode (zero cursor may exceed YNAB_MAX_RESPONSE_BYTES, default 8 MB) that should steer an agent away from a full export. It stops short of naming which list tool to use instead or when a full export is actually warranted.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive), and the description adds real value on top: an estimated cost of ~4 requests and the exact data windows (month/accounts, trailing three months) used to compute the score. The explicit disclaimer that the green/yellow/red thresholds are 'Defaults, not YNAB rules' is important interpretive context an agent would otherwise get wrong.

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

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

Two dense sentences, front-loaded with the output contents before the cost and threshold caveats. Semicolon-packed telegraphy costs a little readability, but no clause is filler.

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

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

For a composite analytics tool with an output schema and full safety annotations, the description supplies the essential missing pieces: data sources, request cost, and scoring heuristics. Remaining gaps are the budgetId default and the fact that it references 'month' despite having no month parameter, which could mildly confuse 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 50%: incomeCategoryIds is documented in-schema, but budgetId has no description and zero required parameters, so the default-scoping behavior is unclear. The description's mention of 'Defaults' refers only to score thresholds, not to which budget is used when budgetId is omitted, so it does not compensate for the gap.

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

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

Names a specific artifact (a budget health snapshot) and enumerates exactly what it contains: savings rate, age of money, Ready to Assign, overspends, card funding, plus a green/yellow/red rating. That metric set distinguishes it from siblings like get_income_expense_summary or get_spending_trends, though it never names those alternatives explicitly.

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

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

'Uses month/accounts and trailing-3-month income/spending (~4 requests)' hints at what it aggregates, so an agent can infer it is a composite diagnosis rather than a raw data fetch. But there is no explicit 'use this when...' or routing away from sibling analytics tools such as get_spending_trends or audit_credit_card_payments.

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 closed-world, so safety is covered. The description adds genuinely new information beyond the structured fields: that display settings do not change the wire format of tool inputs. It omits what happens when the optional budgetId is omitted.

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 compact sentences with the capability stated first and the caveat second; nothing is padded. The phrase 'Tool inputs remain dollars and YYYY-MM-DD' is slightly compressed and could confuse an agent about scope, but it 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?

An output schema exists, so return values need not be explained, and annotations carry the safety profile. The remaining gap is the undocumented optional budgetId and the absence of any mention of the enclosing budget, leaving the call under-specified for a single-parameter 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?

There is one parameter, budgetId, with 0% schema description coverage, and the description never mentions it — not what it identifies, not whether it defaults to a primary budget when omitted. The second sentence covers input formatting generally but adds nothing about this parameter, so the coverage gap is left unfilled.

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 resource — display currency and date formats — which is concrete enough that an agent knows exactly what comes back. It stops short of naming the containing budget or differentiating from siblings, and the 'dollars' phrasing narrows it to one currency assumption.

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

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

Usage is implied rather than stated: an agent can infer it should call this to learn how values are displayed before formatting output, reinforced by the note that tool inputs stay in raw dollars/YYYY-MM-DD. There is no explicit when-to-use, when-not-to-use, or named alternative among the extensive 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, idempotentHint, destructiveHint=false and a closed-world scope, so safety behaviour is fully covered. The description adds genuine context beyond that by scoping the read to the current month and noting that goal fields are returned. It says nothing about budget-scoping or missing-category behaviour, so it is additive but modest.

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

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

Two short sentences, front-loaded with what the tool returns and immediately followed by the routing rule. No filler and no repetition of the title.

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 is not obliged to explain return values, and the current-month vs. other-month distinction is the key thing an agent needs. However, the optional budgetId and its default resolution are unaddressed, leaving a real gap for a tool that can be scoped to a specific budget.

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 50%, and the one documented parameter's description is a tautology ("Category ID"). The optional budgetId is undocumented in both schema and description, and the description never mentions either parameter, so it does nothing to compensate for the coverage gap — notably, what happens when budgetId is omitted is left entirely unexplained.

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?

Specific verb (Get) plus resource (category detail and goal fields) with an explicit temporal scope (current-month). It names the sibling it must not be confused with, get_month_category, so an agent can distinguish the two without opening either schema.

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

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

"For other months use get_month_category" gives an explicit routing rule to the alternative for the main branching case. It stops short of covering other adjacency questions (e.g., search_categories for lookup by name, or whether budgetId defaults to the last-used budget), so it is clear but not exhaustive.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive, closed-world), so the description rightly spends its words on domain semantics that annotations cannot carry: reversals reduce income, category refunds reduce spending, split components are counted once, transfers and deleted rows are excluded, and uncategorized inflows are reported separately. These accounting rules materially change how an agent should interpret the result.

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

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

Front-loaded with what the tool returns, then a tight list of accounting rules. Near-telegraphic phrasing is efficient, though the clipped clauses ('Split components counted once') trade a little readability for density.

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

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

An output schema exists, so return values need no explanation, and the description covers the domain semantics that would otherwise be unknowable. Default window behavior and the required-none nature of the call are left to the schema, which is adequate.

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 75%, so budgetId and the date parameters are already documented, and the description adds substantive meaning for incomeCategoryIds: income uses category/group metadata IDs independent of display language, and ambiguous metadata requires explicit IDs. It does not restate the date-window defaults, but those are already 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 first sentence names the concrete outputs: monthly income, net spending, and savings rate. That is a specific verb+resource, but it does not distinguish this tool from analytical siblings such as get_spending_trends or get_budget_health, which also compute aggregates.

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

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

Usage is implied rather than stated: the summary is for monthly income/spending rollups. The one conditional, 'Ambiguous metadata requires incomeCategoryIds,' hints at when extra input is needed, but there is no when-not guidance and no explicit routing to alternative tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so safety is covered. The description adds only the one-month scoping constraint and says nothing about ordering, pagination, or how the groups are structured, though the output schema likely covers 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?

A single front-loaded sentence with no wasted words. It is efficient, though its terseness contributes to the broader under-specification.

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 output schema reduces the need to explain return values, but the description still lacks sibling differentiation and any guidance on the optional budgetId. For a tool with multiple overlapping siblings, this leaves meaningful ambiguity.

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

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

Schema coverage is 50%: the 'month' parameter is documented in the schema (format and 'current'), while 'budgetId' has no description anywhere. The description's 'for one month' merely restates the required parameter and does not compensate for the undocumented budgetId.

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 gives a specific verb and resource ('Get budget reallocation batches') plus a scope ('for one month'), so the basic action is discernible. However, 'budget reallocation batches' is a non-obvious paraphrase of 'money movement groups', and the description never distinguishes this from close siblings like list_money_movement_groups or get_money_movements_by_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?

There is no guidance on when to use this tool versus list_money_movement_groups (all groups) or get_money_movements_by_month (individual movements). The agent is left to infer the distinction from the name alone.

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

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

Annotations already declare read-only, idempotent, closed-world, and non-destructive behavior, so the safety profile is clear. The description adds that the results are historical and scoped to one month, but it does not discuss permissions, defaults, or edge cases.

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

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

The definition is a single, front-loaded sentence with no wasted words. It is appropriately terse, though the most distinguishing concept ('by month') arrives at the end.

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 and rich annotations, the description still omits how it differs from similarly named money-movement tools and what budgetId does when supplied or omitted. Those omissions are material because the sibling list contains closely related alternatives.

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

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

Schema coverage is only 50%, and the description adds no meaning beyond the already-documented month parameter. The optional budgetId parameter remains undocumented in both the schema and the description, so the description fails to compensate for the coverage gap.

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

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

The description gives a specific verb and resource: 'Get category budget reallocation history' with a clear scope of 'for one month.' It is more specific than the tool name alone, but it does not explicitly distinguish this tool from siblings like list_money_movements or get_money_movement_groups_by_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?

There is no guidance on when to use this tool versus alternatives, nor are any conditions or prerequisites stated. An agent must infer usage entirely from the name and one-line purpose.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds a useful signal by labeling amounts as dollars, but says nothing about budget scoping behavior or whether a missing month/budget falls back to a default.

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

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

Two short sentences with no filler, and the core payload is front-loaded in the first sentence. Nothing to trim.

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

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

With an output schema present, return values needn't be explained, and the description adequately lists what the response contains plus units. The only real gap is the undocumented budgetId parameter, which the description never clarifies.

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

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

Schema coverage is only 50%: 'month' is documented in the schema (YYYY-MM-DD, first of month) but 'budgetId' has no description anywhere. The description adds no parameter meaning at all, so it fails to compensate for the undocumented optional 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 names a specific verb and resource ('Get month totals') and enumerates the payload concisely: category budgets, activity, balances, goals. This distinguishes it from list_months and get_month_category well enough, though it doesn't explicitly contrast with get_income_expense_summary or 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?

It gives an explicit routing rule for one edge case ('For negative balances use get_overspent_categories'), which is exactly the kind of sibling disambiguation an agent needs. It stops short of stating when to prefer this over get_month_category or get_income_expense_summary for overlapping data.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive, so safety is covered. The description adds only the month-scoping idea, restating what the schema already implies, and says nothing about what the returned "budget" figure represents.

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

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

A single short sentence with no filler and the scope stated up front. Its brevity is efficient, though it borders on under-specification rather than tightness.

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

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

An output schema exists so return values needn't be explained, but the description leaves the undocumented budgetId parameter, the ambiguous semantics of "budget," and the sibling differentiation unaddressed — gaps an agent would hit when calling.

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 67%: month and categoryId are documented but budgetId is bare. The description does not mention budgetId at all, nor does it clarify the required YYYY-MM-DD month format or the relationship between budgetId and the other 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?

States a verb and a resource ("Get category budget") plus a scope ("for a specific month"), which is better than a tautology. However, "category budget" is ambiguous — it is unclear whether this returns the budgeted amount only, or budget vs. activity vs. balance — and the description does nothing to distinguish it from siblings like get_category or 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?

No guidance on when to use this over get_category, get_month, or get_overspent_categories. The agent must infer the choice from names alone.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false. The description adds useful semantic context that prior overspends can reduce current Ready to Assign, but it does not describe pagination, result ordering, or other behavioral details.

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

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

A single front-loaded sentence with no wasted words. The resource and scope appear immediately, followed by the key semantic clarification.

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

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

An output schema exists, so return values need not be explained. However, the undocumented budgetId parameter and lack of guidance around budget scoping leave a meaningful gap for an agent invoking the 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 only 50%: the month parameter is documented as YYYY-MM-DD first of month, but budgetId has no schema description. The description says "for a month" but does not explain whether budgetId is optional, what budget it defaults to, or how budget scoping works.

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 a precise resource, "negative-balance categories", scoped to a month. It clearly differs from broader siblings like list_categories or get_category, though it does not explicitly name an alternative.

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

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

The month scoping implies when the tool is useful, but there is no explicit guidance on when to choose it over list_categories, get_month_category, or get_budget_health. Usage is implied rather than stated.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds mild context by naming the returned fields, but since an output schema exists this is largely duplicative, and it says nothing about missing/deleted payees or cross-budget behavior for the optional budgetId.

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

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

Two short sentences with zero filler; the core lookup is front-loaded and the ID-discovery hint follows immediately. Every sentence earns its place.

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

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

With annotations covering safety and an output schema covering return shape, the definition gives an agent enough to call the tool correctly for the common case. The sole gap is the undocumented optional budgetId, a minor omission for a simple single-record lookup.

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

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

Schema coverage is only 50%: payeeId has a (minimal) description while budgetId is undocumented in both schema and description. The phrase 'by ID' only restates the payeeId parameter, and the purpose of budgetId when omitted or supplied is never explained, so the description fails to compensate for the coverage gap.

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

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

States a specific verb and resource ('Get payee ... by ID') and enumerates the returned fields (name, transfer_account_id, deleted status), which is more informative than the bare title. It routes ID discovery to search_payees but does not distinguish itself from sibling list_payees, which also surfaces payees.

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

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

Explicitly points to search_payees as the way to obtain the ID this tool requires, giving clear context for use. It stops short of stating exclusions, such as when to use list_payees instead of fetching individual payees by ID.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is fully covered elsewhere. The description adds only the returned fields and the ID provenance — no pagination, error, or scope notes 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 short sentence with the resource and its key fields front-loaded and zero filler. Nothing could be removed without losing information.

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

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

For a simple two-parameter, single-resource getter with full annotations and an output schema, this is nearly sufficient. The only real gap is the undocumented budgetId, which the description does not cover.

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 50%: payeeLocationId is documented identically in the schema and the description, while budgetId is unexplained in both. The description adds no semantics (format, scope, whether budgetId is required context) that the schema doesn't already state.

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

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

States a specific verb ('Get') and resource (payee location) plus the fields returned (payee, latitude, longitude), which is more than a restated name. The reference to a location ID from list_payee_locations implicitly distinguishes it from the list/by-payee siblings, though it never names them.

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 tells the agent where the required ID comes from (list_payee_locations), which is a useful prerequisite. However it gives no explicit guidance on when to pick this over get_payee_locations_by_payee or get_payee — the choice is left to inference from the parameter name.

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

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

Annotations already declare readOnlyHint, idempotentHint and non-destructive, so safety is covered. The description adds real value beyond them by disclosing that results may be empty and by specifying the data source ('mobile-recorded GPS'), but says nothing about pagination, ordering, or current-balance/auth constraints.

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

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

A single compact sentence with the key information (what, scope, caveat) front-loaded. No filler, though the empty-result caveat is appended as a semicolon clause rather than a clear leading statement.

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

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

An output schema exists, so return values needn't be described, and the empty-result caveat covers the main unexpected outcome. Still missing is any explanation of the optional budgetId, which an agent needs in order to call this correctly in multi-budget contexts.

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 50%: payeeId is documented, budgetId is not. The description's 'for one payee' reinforces the required payeeId, but it never explains when or why budgetId should be supplied, so half the parameters remain ambiguous.

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

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

States a specific verb ('Get') and resource ('mobile-recorded GPS locations') scoped to a single payee, which distinguishes it from the sibling list_payee_locations. It doesn't explicitly name that sibling, but the 'one payee' scoping makes the distinction inferable.

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

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

The description gives no when-to-use or when-not-to-use guidance and does not mention the closely related siblings (list_payee_locations, get_payee_location). 'May be empty' is a result caveat, not usage 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 a useful behavioral note about handling composite ID date suffixes, but it does not explain error behavior or what happens with unknown IDs.

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 tightly packed sentences with the field list front-loaded and no filler. The second sentence is slightly cryptic but still earns its place as 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?

An output schema exists, so return-value explanations are not needed, and annotations cover the safety profile. The description lists key fields and mentions ID handling, though it leaves budgetId unexplained for a tool with 2 parameters.

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 50%: scheduledTransactionId has only a minimal 'Scheduled transaction ID' description, and budgetId is undocumented. The description adds a hint about composite ID suffixes, which gives extra meaning to the ID parameter, but it does not compensate for the undocumented budgetId.

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 retrieval action and enumerates the returned fields (scheduled date, frequency, dollar amount, payee, category), making clear it fetches a scheduled transaction's details. It distinguishes itself from the sibling get_transaction explicitly. The verb 'Get' is generic but the resource and output fields compensate.

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 names the alternative get_transaction, which is helpful, but the condition ('Strip composite ID date suffixes') is cryptic and does not explain when to prefer this tool versus list_scheduled_transactions or get_transaction. Usage is implied rather than clearly stated.

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

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

Annotations already declare readOnly/idempotent/non-destructive, yet the description still adds real behavioral content the annotations do not carry: zero-activity months are included, refunds reduce net, split components are accounted for, and partial months are labeled and never flagged. It also discloses the exact anomaly methodology (>=3 prior complete months, median/MAD threshold plus a minimum dollar increase), which is precisely the kind of 'how does it decide' detail an agent needs before trusting flags.

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 filler, and the core purpose is front-loaded in sentence one. Sentences two and three are dense with parenthetical and slash-joined terms ('median/MAD', 'recurring-charge/reconciliation') that take a beat to parse, but every clause carries substantive information rather than restating the 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?

For a six-parameter, zero-required analytical tool with an output schema, the description covers purpose, inclusion semantics, and the anomaly-flag rule set, so an agent can call it correctly without reading source. The small remaining gap is routing guidance among the other analytical siblings (income/expense summary, budget health, recurring charges), which is left implicit.

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

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

Schema coverage is 83%, so groupBy, sinceDate, untilDate, incomeCategoryIds and minAnomalyIncrease are already documented inline, and the baseline is 3. The description reinforces the grouping dimension and the median/MAD concept behind minAnomalyIncrease but adds no syntax, default, or edge-case detail (e.g. behavior when sinceDate and untilDate conflict or exceed the 36-month cap) beyond what the schema states. Marginal added value only.

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

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

The first sentence names the resource precisely: monthly net spending, grouped by category or payee, with an explicit 'read-only' qualifier. It also enumerates inclusion rules (zero-activity months, refunds, split components, prior-month deltas), which lets an agent tell it apart from summary tools. The sibling differentiation in the last sentence is category-level ('recurring-charge/reconciliation tools') rather than naming detect_recurring_charges or audit_account_reconciliation directly, which keeps it short of a 5.

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

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

Usage is implied rather than stated: 'Adds historical comparisons beyond recurring-charge/reconciliation tools' suggests the agent should reach for this when it needs multi-month trend history, and the anomaly-flag rules hint at a 'find unusual spending' use case. But there is no explicit when-to-use clause and no mention of get_income_expense_summary or get_budget_health, which are adjacent analytical siblings an agent must choose between. The reader has to infer the routing.

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

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

Annotations already declare readOnlyHint/idempotentHint, so the bar is lower, and the description adds genuine value by disclosing error semantics: a deleted matched scheduled transaction returns a composite_id_with_no_matched_transaction payload while other missing IDs yield resource_not_found. That tells the agent how to interpret non-success responses, which annotations cannot. It does not cover budget scoping or auth, keeping it short of a 5.

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

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

It is short and front-loads the ID format, which is good, but the prose is telegraphic and grammatically fragmented, making the error-case sentence hard to parse. Every sentence does carry information, but the structure is rough.

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

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

An output schema exists, so return values need no explanation, and the composite-ID format plus error taxonomy are covered. However, budgetId scoping and which error applies to which situation are only partially addressed, leaving a moderate gap for a 2-parameter getter.

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

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

Schema coverage is only 50% (the transactionId description is just "Transaction ID"), so the description must compensate, and it does by revealing the accepted composite format uuid_YYYY-MM-DD. The budgetId parameter is left unexplained in both schema and description, which caps it below 5.

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?

"Get transactionId" conveys retrieval of a single transaction by ID, but the phrasing is awkward (it reads as fetching the ID itself rather than the transaction) and it never distinguishes this from siblings like get_transactions or search_transactions. The purpose is inferable but not stated with a clean verb+resource.

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

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

There is no statement of when to use this versus get_transactions (list) or search_transactions (query-based lookup), which are the most likely confusions for an agent. The single-record nature is only implied by the singular parameter.

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

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

Annotations already declare a safe read-only, idempotent operation, and the description adds meaningful behavior: the 500-row non-delta cap, limit max of 2000, default sinceDate, and capped-vs-array return shape. It still omits some operational detail such as auth or rate-limit behavior, but adds strong 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 dense and front-loaded: purpose first, then filters, defaults, cap behavior, return shape, and sibling routing. Every sentence carries operational information with no wasted prose.

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 14-parameter tool with rich schema coverage, annotations, and an output schema, this description supplies the key operational context an agent needs: scope, defaults, pagination caps, return shape, and the main alternative tool. Remaining details are adequately covered by structured fields.

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

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

Schema coverage is 93%, so the schema already documents nearly all parameter meaning. The description reinforces a few points such as sinceDate default, limit caps, and filter ID choices, but mostly restates schema-provided details rather than adding substantial new parameter semantics.

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

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

The description states a specific verb and resource ('List transactions'), names the raw bank-text field, and explicitly distinguishes this from search_transactions for specific rows. An agent can identify the tool's role and its broad-listing purpose without opening the schema.

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

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

It gives a clear routing rule: prefer search_transactions for specific rows, and suggests filtering by accountId, categoryId, or payeeId. It does not discuss delta-vs-non-delta reads or freshness selection in prose, leaving those usage decisions to the schema.

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 as a read-only, idempotent, non-destructive, non-open-world operation. The description adds useful context that this is the authenticated-user API path, contrasted with the no-API-request diagnostic path, though it does not discuss auth failure behavior.

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

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

Two short sentences, with the core purpose front-loaded and the alternative routing immediately after. There is no redundant or filler 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?

For a zero-parameter read tool with rich annotations and an output schema, the description covers what the agent needs: identity of the resource and when to use the diagnostic alternative. Return values and safety traits are handled by structured metadata.

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?

There are zero parameters, so there is no parameter semantics burden. The schema coverage is fully complete, and the description does not need to explain inputs.

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: getting the authenticated user ID. It also distinguishes the relevant sibling, ynab_auth_status, for credential diagnostics, so an agent can tell which tool to select without opening schemas.

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

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

It gives an explicit when-not condition: use ynab_auth_status for credential diagnostics without an API request. That directly routes the agent between this operation and the closest alternative.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so safety is covered. The description adds one genuine behavioral fact — closed accounts are included — but stays silent on the more consequential traits: cache freshness semantics, delta-cursor behavior via lastKnowledgeOfServer, and envelope metadata via includeFreshness, all of which live only in the 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?

A single front-loaded sentence with no filler; the field list is dense but every item is informative. Slightly jargon-heavy ("debt metadata", "direct_import_in_error") and the trailing closed-accounts note could have been folded into the same clause.

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

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

An output schema and annotations carry return shape and safety, so the description needn't cover those. It is still incomplete for a 5-parameter tool: zero mention of budgetId, freshness/cache behavior, projection tradeoffs, or the delta cursor, so an agent must read the schema to call it well.

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 80%, so baseline is 3. The field enumeration (reconciliation time, debt metadata, direct_import_in_error) indirectly hints at what projection=full vs lean yields, but the description never names a parameter or explains budgetId, freshness, projection, or the delta cursor.

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

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

Opens with a specific verb+resource ("List account IDs, dollar balances, ...") and enumerates the returned attributes, so an agent knows exactly what it gets. Sibling differentiation is only implicit — nothing distinguishes it from get_account beyond the verb 'List'.

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

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

No statement of when to use this versus get_account, no note that budgetId selects the budget, and no guidance on when to prefer freshness=fresh vs cached or lean vs full projection. The only usage-adjacent cue is "Includes closed accounts", which signals scope but not 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 this a read-only, idempotent, closed-world operation, so the safety profile is covered. The description adds a useful cross-tool usage note but says nothing about response shape, ordering, or what happens with the default budget flag.

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 terse sentences with zero filler; the core action comes first and the usage tip follows immediately.

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

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

An output schema exists, so return values need not be explained, and the annotations carry the safety profile. For a one-optional-parameter list tool this is nearly complete, missing only explicit guidance on when to prefer listing versus fetching a single budget.

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 single includeAccounts flag is fully documented there. The description adds no parameter-level detail, so the baseline 3 applies.

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

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

States a specific verb and resource ('List budgets and IDs'), which clearly distinguishes this from the singular get_budget sibling. However, it does not explicitly say how it differs from get_budget or get_budget_settings beyond the plural naming.

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

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

The second sentence gives concrete cross-tool guidance: omit budgetId elsewhere to target the default budget, which implies this tool is the discovery step for budget IDs. It stops short of explicitly stating 'call this first' or naming 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 the full safety profile (readOnly, idempotent, non-destructive, closed-world), so the description only needs to add behavior beyond that. It does: 'Includes hidden/deleted/internal flags' tells the agent that archived/deleted categories are present in results by default, a non-obvious trait that affects filtering downstream. It does not touch freshness/caching or delta-cursor behavior, but the schema covers those, so this is short of a 5 rather than a gap.

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

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

Two sentences, zero filler, and the result-shape statement is front-loaded before the disambiguation clause. Every sentence earns its place and the alternative routing is last, where an agent scanning for the wrong-tool check will find it.

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

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

An output schema exists, so return-value explanation isn't required, and the description covers scope (current month), result content, and the two escape hatches to sibling tools. The only thin spot is that nothing signals the default fresh-vs-cached read behavior or the delta-cursor mode, though the schema carries both.

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 80%, so the schema already explains freshness, projection, includeFreshness and the delta cursor. The description says nothing about any of the five parameters, contributing no meaning beyond structured fields. Baseline 3 is appropriate.

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

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

States a specific verb and resource (list groups/categories) plus the payload it returns: current-month dollar budgets, activity and balances. The scope qualifier 'current-month' and the hidden/deleted/internal flag note separate it cleanly from get_month and search_categories without the agent needing to open any schema.

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

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

Explicitly routes the agent: 'Use get_month for other months or search_categories for names.' Both alternatives are named siblings and each is tied to a concrete condition that selects it, leaving nothing to inference.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is clear without the description. The description adds a useful join semantic via money_movement_group_id, but says nothing about scope, pagination, or what happens when budgetId is omitted.

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

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

Two short sentences with no filler. The join instruction is front-loaded after the purpose statement, though the purpose sentence uses non-canonical terminology that slightly reduces clarity.

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

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

An output schema exists, so return values need not be explained, but the input side is incomplete: the only parameter has no description anywhere and its effect is unspecified. For a list tool with a close sibling that groups by month, the lack of scope and alternative guidance is a meaningful gap.

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

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

Schema description coverage is 0%, so the description must carry the full burden for the single budgetId parameter. It never mentions budgetId at all, and instead mentions money_movement_group_id, which is not an input parameter. An agent cannot tell from the definition whether budgetId is required, what it scopes, or whether omitting it lists across all budgets.

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 gives a specific verb ('List') and a resource framed as 'related budget reallocation batches', but it renames the actual resource ('money movement groups') rather than using the tool's terminology. It does not distinguish this tool from close siblings like list_money_movements or get_money_movement_groups_by_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?

It explains how to join movements using money_movement_group_id, which is useful data-model context, but gives no guidance on when to call this tool versus list_money_movements or get_money_movement_groups_by_month. The agent must infer the selection criteria from the names alone.

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

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

Annotations already declare read-only, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds genuinely useful context beyond them: the records are reallocations rather than spending transactions, and this variant returns a larger payload than the by-month sibling. It does not mention pagination or volume limits, which keeps it from a 5.

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

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

Three short sentences, each with a distinct job: define the resource, disambiguate it from transactions, route to the lighter sibling. Nothing redundant and the definition leads.

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

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

An output schema exists, so the field list need not be explained in prose, and the annotations carry the safety story. The one remaining gap is the undocumented optional budgetId, which the agent must infer from the schema alone.

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 single parameter budgetId has 0% schema description coverage, and the description supplies no information about it at all — not its meaning, not that it is optional (required count is 0), not what happens when omitted. With coverage below 50%, the description is expected to compensate and does not.

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

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

Names a specific verb (List) and a precise resource (category budget reallocation history), then enumerates the returned fields: who, amount, source, destination, time. The sentence 'These are not transactions' preempts the most likely confusion with the large family of transaction tools in the sibling list.

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

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

Gives an explicit routing rule: for less output, use get_money_movements_by_month. That is a real alternative-selection criterion, though it only covers the output-size dimension and says nothing about when this tool should not be used.

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 as a safe, idempotent, read-only operation. The description adds useful scope by naming the returned budget fields and dollar units, but it does not mention delta-sync behavior or other operational details beyond what annotations and schema provide.

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

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

The description is two sentences with no wasted language. It front-loads what the tool returns and puts the sibling routing note immediately after.

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 rich annotations, an output schema, and only two simple parameters, the description is nearly complete for selecting and invoking the tool. The main minor gap is that it does not mention the delta cursor behavior, though the schema covers that.

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 50%: lastKnowledgeOfServer is documented as a delta cursor, while budgetId is structurally obvious but undocumented. The description adds no parameter-level guidance, so it neither compensates for the gap nor contradicts the schema.

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

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

The description uses a specific verb and resource: it lists monthly income, budgeted, activity, Ready to Assign, and age of money. It also explicitly routes category-level needs to get_month, so an agent can distinguish it from that sibling without inspecting schemas.

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

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

It gives clear usage context by stating the monthly budget-summary data it returns and directing category lookups to get_month. It does not exhaustively describe when not to use it versus every other budget-summary sibling, but the main alternative is named.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so 'No financial writes' mostly restates them. The description does add genuine context: outcomes are 'durable' (persisted, retrievable after the fact) and tenant-scoped. It omits ordering, retention, pagination, and what an operation record contains.

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

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

Three short sentences with the core purpose front-loaded, followed by filtering behavior. 'No financial writes' is close to redundant against the readOnly annotation but still serves as a fast safety signal, so nothing is wasted enough to penalize.

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

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

An output schema exists, so return values needn't be described, and annotations cover safety. What's missing is the conceptual anchor: which multi-step operations this lists and how an agent would know one is pending — a meaningful gap in a 47-tool budget-management server.

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

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

Schema coverage is 0% — budgetId has no description in the schema — so the description carries the burden and does so well: omission means all budgets, presence means exact-match filter. It doesn't clarify the ID format or whether partial/multiple IDs are accepted, which is why it's not a 5.

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 ('Read') and resource ('durable multi-step operation outcomes') scoped to the authenticated tenant, which is far more informative than the name alone. It doesn't explicitly contrast with any sibling, but 'operations' is distinct enough from the budgets/transactions/payees listing 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 explains the two calling modes (omit budgetId for all budgets, or pass an exact ID), which is effectively usage guidance for the single parameter. However, it never says when an agent should reach for this tool versus sibling read tools, nor what triggers the existence of an 'operation'.

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

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

Annotations already establish that this is a read-only, idempotent, non-destructive operation. The description adds useful behavioral context beyond that: it explains the data source (YNAB mobile transactions) and warns that the result may be empty.

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

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

Two short sentences with no filler. The core purpose is front-loaded, and the alternative-tool guidance follows immediately.

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

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

For a simple read-only list tool with an output schema and strong annotations, the description covers purpose, data origin, empty-result expectation, and the relevant alternative. The only notable gap is the undocumented budgetId parameter.

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 one parameter, budgetId, but schema description coverage is 0% and the description never mentions budgetId or its meaning. Because the schema provides no parameter documentation, the description should compensate but does not.

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

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

It names a specific verb and resource: list GPS locations recorded by YNAB mobile transactions. It also explicitly distinguishes itself from the sibling scoping tool get_payee_locations_by_payee, so an agent can tell which one to use without opening either schema.

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

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

The description gives clear usage context and names the alternative for scoped results: 'Scope with get_payee_locations_by_payee.' It does not add explicit when-not conditions beyond that alternative, but the routing signal is clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description contributes domain-specific behavior beyond that: payee IDs (especially transfer payees) must be resolved from real data rather than fabricated names. It does not mention the 30-second cache or delta cursor behavior, but those live in the schema, so this is a modest gap rather than a missing disclosure.

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

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

Two short sentences with zero filler, and the core scoping statement plus the sibling routing advice are both front-loaded. Nothing could be removed without losing information.

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

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

For a zero-required-param read tool with rich annotations, a detailed schema and an output schema, the description covers the essential calling constraint and the sibling rivalry. The only omission is guidance on when to prefer fresh versus cached reads or to use the delta cursor, which the schema handles adequately but not in a task-oriented way.

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 80%, so freshness, projection, includeFreshness and lastKnowledgeOfServer are already well documented in the schema and the baseline is 3. The description adds only the notion that transfer_account_id is part of the returned ID set, which is marginal value over structured fields.

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

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

States a specific verb and resource ('List payee IDs and transfer_account_id'), including the exact fields returned, so the agent knows what it gets without opening the schema. It also distinguishes itself from the sibling search_payees, making the two tools separable at a glance.

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

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

Names the alternative explicitly ('Prefer search_payees for name lookup') with the condition that selects it, and adds an exclusion rule ('never invented Transfer names') that prevents a known failure mode. Both when-to-use-an-alternative and a hard constraint are present.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds the useful data-scope caveat that only manual entries are returned, but says nothing about caching/freshness behavior or result size even though the schema exposes a freshness enum.

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, both earning their place, with the scope restriction front-loaded and the routing hint immediately after. No restatement of the title or annotations.

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

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

An output schema exists so return values needn't be explained, and the parameters are largely documented in the schema. What an agent still can't infer from the description is pagination or result-size behavior, but nothing essential to calling it correctly is missing.

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

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

Schema description coverage is 80%, with freshness, projection, includeFreshness and lastKnowledgeOfServer all documented inline, including enums and the delta cursor shape. The description mentions no parameter semantics of its own, so the baseline 3 applies.

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

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

States a specific verb and resource ('List ... scheduled transactions') plus a scope qualifier ('manually ... only'). It also names the sibling tools that cover the excluded case, so an agent can place it in the toolset without opening any schema.

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

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

Provides an explicit when-not rule and names the alternatives ('transaction history or detect_recurring_charges') for auto-imported recurring charges. It doesn't state prerequisites or whether budgetId is optional, but the routing guidance is clear.

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

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

Annotations already establish read-only, idempotent, non-destructive, closed-world behavior. The description adds useful context beyond those annotations: this reads a local write journal rather than making an API request, ordering is newest first, and non-undoable entries are audit-only.

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?

Compact and front-loaded: the core action and scope come first, followed by the no-API clarification, audit-only caveat, and undo routing. Every phrase contributes 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?

For a simple one-parameter read tool with full schema coverage, annotations, and an output schema, the description supplies what is missing: local journal semantics, newest-first ordering, audit-only entries, and undo usage. Nothing essential for correct invocation is omitted.

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 limit parameter is documented with default, maximum, and ordering. The description reinforces 'newest first' but adds no parameter-specific syntax or constraints 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?

States a specific verb/resource: reading the local write journal, newest first. It distinguishes itself from API-backed siblings by saying 'No API request' and clarifies it relates to undo capability, so an agent can identify it without ambiguity.

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

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

Gives clear usage context: use entry IDs with undo_operation, and undoable:false entries are audit-only. It does not explicitly contrast with sibling list_operations, but the local/no-API framing and undo routing provide actionable 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?

Adds substantial context beyond the annotations: the token's five-minute expiry, single-use nature, and binding to session, budget, entity IDs and values, plus hosted consent requirements. The 'never instructions' warning about bank memos flags an injection risk the annotations cannot express. All of this is consistent with readOnlyHint=true since the tool itself does not apply the write.

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

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

Four tight sentences, front-loaded with the core purpose, then token lifecycle, approval workflow, and a safety caveat. Nothing is redundant and each sentence carries distinct 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?

An output schema exists, so return values need not be explained, and the safety/workflow context is thorough. However, for a tool whose only real input is an unconstrained object, the description leaves the agent unable to determine how to populate `input` — a meaningful gap in an otherwise well-specified definition.

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

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

Schema coverage is 0% for two parameters, one of which is a free-form nested `input` object with additionalProperties. The description never explains what `tool_name` expects or how `input` must mirror the target tool's arguments, so an agent has no guidance for constructing the call. The mention of 'entity IDs and values' hints at the binding but does not document the 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?

States a specific verb and resource: reads fresh state and previews an exact write without applying it. That is clearly distinct from the execution siblings in the list, but no sibling (e.g. ynab_tool_execute) is named explicitly, so the agent must infer the pairing.

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

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

Gives concrete procedural guidance: present the plan to the user and obtain explicit approval before execution, which establishes this as the pre-write step. It does not explicitly name the tool to call afterwards, but the when-to-use context is otherwise 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?

Goes well beyond the annotations by disclosing dedup of up to 50 IDs, that 'orphan' is returned only for a 404 transaction, that 'found' includes a row for duplicate review but is not proof to delete it, and that other failures abort with an error. The 'Read-only' statement is consistent with readOnlyHint=true rather than contradicting it.

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?

Compact and front-loaded with the action, and every clause carries behavioral weight. The density of unexplained jargon makes it harder to parse than ideal, but there is 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?

Behavioral edge cases are well covered and an output schema exists, so return values needn't be spelled out. However, with 0% schema coverage the unexplained budgetId is a real gap for an agent trying to call it correctly.

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

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

Schema description coverage is 0%, so the description carries the full burden, yet it leaves budgetId entirely unexplained and only loosely references matchedTransactionIds. The '50 IDs' dedup limit is already encoded in the schema's maxItems, so it adds little parameter meaning.

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

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

The description names specific internal concepts (match_broken matched_transaction_id values, review_unapproved) and a resource, but the verb 'resolve' is vague and the jargon is opaque to an agent that doesn't already know these domain terms. It hints at a relationship to review_unapproved but doesn't clearly distinguish itself from that sibling.

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

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

Naming review_unapproved as the source of the IDs implies the workflow (call review_unapproved first), but there is no explicit when-to-use vs when-not or alternative-tool routing. Usage must be inferred.

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, and the description adds meaningful operational context: fallback from full rows to compact then summary above maxTransactions, mode reporting, mixed-group representation, and which identifiers are writable. The term 'writable' is slightly ambiguous but not contradictory to readOnlyHint.

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-loads the purpose, but it is a dense run-on of semicolon-separated jargon such as 'match_broken,' 'realized composite IDs,' and 'mixed groups.' Every clause carries information, but the structure makes it harder to parse than it needs to be.

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

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

For a complex review tool with an output schema, the description covers the key special cases: grouping, mixed categories, aggregate vs compact output, and threshold-based degradation. It is nearly complete, though it omits budgetId semantics and explicit alternative-tool guidance.

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 75%, so baseline is 3. The description reinforces compact/summary semantics and degradation around maxTransactions, but does not explain budgetId and mostly repeats schema-level parameter descriptions.

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

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

The description states a specific verb and resource: review all-history unapproved rows by payee, split into ready_to_approve and needs_category_first. That distinguishes it from generic transaction listing/search tools, though it does not explicitly name sibling alternatives.

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

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

It describes what the review returns and how output modes degrade, but gives no explicit guidance on when to use this instead of get_transactions, search_transactions, or other sibling tools. The usage context is implied by 'unapproved rows' rather than stated as a decision rule.

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