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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered; the description adds genuinely non-obvious context: balances are in milliunits and last_reconciled_at is never written by the API. It does not discuss auth or error behavior, but the domain-specific disclosure is valuable.

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

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

Front-loaded with the verb and resource in the first clause, zero filler, and the milliunits note is a compact, high-value unit clarification. The final sentence on last_reconciled_at is longer than needed but still earns its place as non-obvious behavior.

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

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

An output schema exists, so return values need not be described, and the read-only semantics are well covered. However, the unexplained plan_id parameter and absent account_id format leave a real gap for a two-parameter lookup 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 0%, so the description must carry parameter meaning, but it only says 'by ID'. account_id format and plan_id (nullable, default null, likely the budget selector) are left completely unexplained in both schema and 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 (Get) and resource (a single account) scoped by ID, and the singular framing clearly distinguishes it from the sibling accounts_list. An agent can route between accounts_get and accounts_list 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?

Usage is implied by 'single account by ID', but the description never names accounts_list as the alternative or states when to prefer one over the other. No prerequisites or exclusions are given, leaving selection 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 the read-only, non-destructive profile, and the description adds substantial non-obvious behavior: balances are in milliunits (1000 = $1.00), and last_reconciled_at is read-only everywhere in this API — reconciling via this server will not move it. The delta-sync mechanics are also explained. This is exactly the kind of context annotations cannot carry.

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

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

Front-loaded with the [READ] tag and the core purpose, and most sentences earn their place. The reconciliation point sprawls across three sentences ("marking transactions reconciled does not move it... Only reconciling in the YNAB app does...") that restate the same fact and could be tightened.

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

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

An output schema exists, so return values need not be described, and the description covers the key behavioral traits (units, reconciliation, delta sync) plus an alternative tool. The only real gap is the undocumented plan_id, which is minor for a two-parameter read tool.

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

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

Schema description coverage is 0%, so the description must compensate and only partially does. last_knowledge_of_server is explained well (it is "the server_knowledge value any earlier response returned"), but plan_id gets no explanation at all, leaving half the parameters undocumented in both schema and 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 and resource with scope: "List all accounts for a plan." This distinguishes it from the sibling accounts_get (single account) and from the various transactions_*/categories_* listers 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?

Gives clear usage context for delta sync ("pass last_knowledge_of_server ... and YNAB sends only what changed since") and names changes_since as the cross-resource alternative for categories/months/transactions. It never explicitly states when to choose accounts_list over the sibling accounts_get, so it stops short of full when/when-not coverage.

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/non-destructive/closed-world, but the description goes well beyond them: it quantifies the request cost (one YNAB request per month, 36-month cap, plus one for inflows), explains the false-positive case (deliberately self-funded categories), and clarifies that total_if_unintended is a signal metric, not a verdict. That is rich behavioral context the annotations cannot carry.

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 front-loaded with the [READ] marker and the core definition, then layers caveats and cost. Nearly every sentence earns its place, though the illustrative anecdote ('sixteen months... about $841') is color that a tighter version could drop.

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 description covers cost, interpretation, filtering, and date formats. The only gaps are the undocumented plan_id and include_hidden parameters, minor for a plan-scoped analysis tool.

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

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

Schema description coverage is 0%, so the description must compensate, and it does for four of six params: from_month/to_month get explicit accepted formats ('YYYY-MM', ISO date, 'current'), and group_ids/category_ids are explained as narrowing filters. plan_id and include_hidden are left undocumented, so it is not fully complete.

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 precise verb and resource: it detects categories whose monthly assignment equals a fixed base plus that month's inflows (interest double-counting). The opening [READ] tag and the concrete mechanism distinguish it immediately from sibling analysis_* tools like analysis_copied_forward_months or analysis_credit_funding.

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 how to narrow results (group_ids/category_ids), when to check cost (overview_request_budget before a long range), and how to interpret output ('a signal, not a verdict'). It lacks an explicit statement of when this analysis is preferable to a sibling like analysis_flow_trace, so it's a strong 4 rather than a 5.

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

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

Annotations already carry the safety profile (readOnly, non-destructive, closed-world), and the description adds substantial extra behavior: the per-month request cost, the 36-month limit, the pre-read of the month before the range, and the 12-month default. This is exactly the kind of cost/scope disclosure annotations cannot express.

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

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

Front-loads the definition and keeps the operational details (defaults, cost, limits) at the end where they belong. The $10,000 anecdote is illustrative but slightly restates the 'applied without review' idea already conveyed, costing a bit of 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?

With an output schema present, return values need no explanation, and the description covers scope, defaults, and request cost adequately for an analysis tool. The remaining gap is the silent treatment of plan_id and include_hidden, which an agent must infer from the schema.

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

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

Schema description coverage is 0%, so the description must compensate, and it does explain from_month/to_month semantics (widen or shift the window) plus the effective default. However, plan_id and include_hidden are never addressed, leaving half the parameters undocumented anywhere.

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+resource ('find months whose assignments are an exact copy of the month before') and frames the diagnostic meaning of that pattern. It is clearly distinguishable from sibling analysis tools such as analysis_assignment_patterns or months_range.

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-to-use context (detecting unreviewed 'assign last month's amounts'), states the default window, and points to overview_request_budget before running a long range. It never names an explicit alternative or a when-not-to-use condition, so it stops short of a 5.

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

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

Annotations already establish the safe read-only profile, and the description adds genuinely useful behavior beyond that: one request per month of history, name-based matching because YNAB exposes no linking identifier, and explicit reporting of unmatched accounts/categories rather than silent dropping. It does not state rate-limit or failure behavior in detail, keeping it at a 4.

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

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

Front-loaded with a [READ] tag and the core purpose, then the diagnostic value, then the parameter detail. Every sentence is substantive, though the two 'problems' enumeration and the parenthetical explanation of the historical-negative case run slightly long.

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

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

Output schema exists so return values need not be explained, and the description covers matching semantics, the months default/cost, and the unmatched-handling edge case. The only real gap is the undocumented `plan_id`, which slightly detracts from an otherwise complete picture for this complexity level.

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

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

Schema coverage is 0%, so the description has to carry both parameters. It fully documents `months` (default 6, one request per month, 0 to skip) including the cost tradeoff, but `plan_id` is never mentioned, leaving half the parameters undocumented in both schema and 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?

Names a specific analysis resource (credit card / line-of-credit funding) and enumerates exactly what it reports: what each card owes, what its payment category holds, the difference, uncovered debt, and stranded money in closed-account payment categories. The line 'two problems live here and nowhere else in YNAB's interface' cleanly separates it from siblings like analysis_overspent_history and analysis_target_funding_gaps.

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

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

The description gives clear context for when this tool is the right one — detecting debt with no money set aside and funds stranded in a closed account's payment category — and effectively rules out other tools by stating those diagnostics exist nowhere else. It stops short of explicitly naming an alternative tool or a when-not condition, so it is a 4 rather than a 5.

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

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

Beyond the read-only annotations, the description discloses substantial operational traits: cost of one YNAB request per month in the range, a 36-month limit, an extra two requests for movements and transactions, and a suggestion to check the request budget first. This goes well beyond what the annotations provide.

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

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

The description is front-loaded with purpose, then rationale, parameter formats, and cost warning. Every sentence roughly earns its place, though the middle explanatory sentence about three YNAB resources is slightly verbose for the value it adds.

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

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

Given the tool's complexity, the presence of an output schema, and read-only annotations, the description covers purpose, parameter formats for two key fields, and cost/limits well. It still omits what happens if 'to_month' is omitted and does not explain 'plan_id', which are notable gaps for a 4-parameter tool with zero schema descriptions.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It usefully documents the format for 'from_month' and 'to_month' ('YYYY-MM', ISO date, or 'current'), but 'category_id' is only implied and 'plan_id' is entirely unexplained, leaving two of four parameters without clear 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: 'Follow one category's money through a range of months', and enumerates the resulting flow components (assigned in, moved in, moved out, spent, refunded, balance left). This scope distinguishes it from sibling tools that operate on groups, single months, or raw movements, without needing to open a schema.

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

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

It gives a clear usage context ('where did the holiday money go') and notes the need to check 'overview_request_budget' before long ranges. However, it does not name alternative tools or specify when-not to use it versus e.g. 'transactions_list_by_category' or 'money_movements_list_by_month'.

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

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

Beyond the readOnly/openWorld annotations, the description discloses real operational behavior: the cost model (one YNAB request per month), a hard 36-month limit, and the fixed gap sign convention. Pointing at overview_request_budget for budget checking is genuine guidance an agent can act on.

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

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

Front-loaded with the [READ] tag and the core comparison, and every sentence carries weight (framing, sign convention, id source, month format, cost). Slightly dense, 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?

An output schema exists, so return values need no explanation, and the description still supplies the pieces an agent needs: id provenance, month syntax, sign convention, and rate-limit/cost constraints. Complete for a 6-parameter, 36-month-capped analysis tool.

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

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

Schema description coverage is 0%, so the description must carry the load: it defines the month format ('YYYY-MM', ISO date, or 'current'), sources group ids from categories_list, and pins down which group is subtracted from which. It does not explain plan_id or include_hidden, leaving those to inference, so not quite 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 (compare) and resource (two category groups month by month), and enumerates the compared metrics (assigned, activity, balance, gap). The 'group A minus group B' convention and the 'split money between two people' framing make it unmistakable against siblings like category_groups_summary_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?

Explicitly scopes when to use it — plans that split money between paired groups where the question is even funding/spending — and gives a prerequisite (get group ids from categories_list) plus a pre-flight step (check overview_request_budget for long ranges). Nothing is left to inference about when this tool applies.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered (the '[READ]' prefix merely restates it). The description does add a genuine behavioral trait beyond annotations: results are sorted by most-overspent first. Field listing (budgeted, activity, balance) is likely redundant with the output 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?

Front-loaded and compact: purpose, then sort order, then fields, then the month parameter. Every sentence earns its place, with only the redundant '[READ]' tag as minor waste.

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

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

An output schema exists, so return values needn't be explained, and with zero required parameters the call is easy to make. However, plan_id is entirely unaddressed, leaving a real gap for a two-parameter analysis tool.

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

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

Schema description coverage is 0%, so the description must compensate. It documents month well (ISO date, first day of month, example, defaults to current month) but says nothing about plan_id, leaving half the parameters undocumented in both schema and 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 resource and scope: categories with negative balances for a given month, sorted most-overspent first. An agent can tell what the tool returns, though it never names or contrasts with the close sibling analysis_overspent_history, so differentiation is left to inference.

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

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

No when-to-use guidance and no mention of alternatives such as analysis_overspent_history. The only usage context is the month default ('defaults to current month'), which is behavioral, not a selection guideline.

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 only cover the safety profile (readOnly, non-destructive, closed-world), and the description goes well beyond that: the cash-vs-credit inference and why YNAB cannot report it, the downstream effect on next month's Ready to Assign, and the per-month request cost model. This is exactly the extra behavioral context annotations cannot carry.

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 '[READ]' and the core return shape, followed by the conceptual cash/credit explanation and then the cost caveat. Dense but every clause carries information; the cash/credit mechanism paragraph is the only mildly padded part.

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 helpfully summarizes them anyway. Cost, limits, and date formats are covered; the only real gap is the semantics of plan_id and include_hidden for a 4-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 0%, so the description must compensate. It does document accepted formats for from_month/to_month ('YYYY-MM', ISO date, or 'current'), but says nothing about plan_id or include_hidden, leaving half the parameters undocumented in both schema and description. Minimum-viable rather than complete.

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 (overspent/inference history) and explicitly scopes it 'across a range', which implicitly separates it from the single-period sibling analysis_overspent_categories. It also enumerates what is returned (negative month-end balances, cash/credit flags, running total, most-overspent categories). It misses an explicit disambiguation sentence naming the sibling, so it falls 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?

Gives a concrete operational precondition ('check overview_request_budget before a long range') and states the 36-month cap, which tells the agent when the call is expensive. However it never states when to prefer this over analysis_overspent_categories or the month-scoped 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 cover the safety profile (readOnly, non-destructive, closed-world), and the description adds substantial context beyond that: grouping is by payee id rather than name, outflows-only filtering, transfer exclusion, the 3-charge recognition threshold, per-result fields (occurrences, amount_changed, days_since_last), and the milliunits unit convention. This is exactly the operational detail an agent needs to interpret results correctly.

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

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

The definition is front-loaded: '[READ]' plus the core purpose lead, followed by parameters, grouping semantics, filtering rules, and result interpretation. It is dense and runs long, but nearly every clause (cadence threshold, occurrences weighting, milliunits) earns its place rather than repeating structured fields.

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 is not required, and the description still helpfully interprets the key result fields. The gap is the two unexplained parameters (plan_id, since_date), which for a 3-parameter tool with 0% schema coverage leaves an agent unsure how to scope the query beyond the default window.

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 of parameter explanation. It defines 'months' well ('how far back to look, default 12'), but plan_id and since_date — which scope the query to a plan and a date bound — are never mentioned. Two of three parameters are left undocumented in both structured data and prose.

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

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

The description opens with a specific verb and resource — 'Find repeating charges (subscriptions, memberships, regular bills) and estimate what each costs per year.' This is unambiguous and immediately distinct from siblings like analysis_overspent_history or analysis_copied_forward_months. An agent can route to this tool 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?

Scope conditions are stated clearly: only outflows count, transfers between own accounts are excluded, and a series needs at least 3 charges on a recognizable cadence to be reported. This gives strong implicit guidance on when results will and won't appear. It does not name a sibling alternative or an explicit 'use this instead of X' rule, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so the '[READ]' prefix largely restates structured data. The description does add useful context that the result measures the shortfall against each goal target, but says nothing about scope limits, permissions, or result size.

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

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

Three tight sentences, front-loaded with the read tag and the core resource, then the output meaning, then the parameter detail. 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?

An output schema exists, so return values need not be explained, and the month semantics are covered. However, with two parameters and zero schema coverage, leaving plan_id entirely unexplained is a real gap for a tool whose results are presumably plan-scoped.

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

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

Schema description coverage is 0%, so the description must compensate. It documents 'month' well (ISO first-of-month format, example, current-month default), which genuinely exceeds the schema, but 'plan_id' is completely undocumented in both schema and description.

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

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

The description names a specific resource (categories with unmet funding goals) scoped to a given month, plus what the output means (how much more must be budgeted). It separates itself from sibling analyses only implicitly, though — no sibling such as analysis_credit_funding is named as 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 '[READ]' tag and 'for a given month' framing imply this is a read-only inspection of goal shortfalls, but there is no explicit when-to-use vs. when-not, and no routing to related analyses like analysis_credit_funding or analysis_overspent_categories.

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

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

Annotations already cover readOnly/non-destructive/closed-world, but the description adds a genuinely useful behavioral detail beyond them: the request cost ('two requests, plus one per month when group_ids is given'). It does not discuss permissions or failure modes, but the cost disclosure is real added value.

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 [READ] and the core purpose, and the parameter guidance is actionable. However, the anecdotal backstory ('Seven months of that went unnoticed on the plan this was written for') is not needed for an agent to select or invoke the tool and inflates the 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?

With an output schema present, return values need no explanation, and the description covers the important input semantics plus request cost. The unaddressed plan_id and the unstated optionality/defaults for to_month are the only shortfalls.

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 load, and it does for most params: group_ids meaning and effect, account_ids narrowing behavior, and from_month/to_month accepted formats ('YYYY-MM', ISO date, 'current'). plan_id and to_month's default/optionality are never mentioned, leaving one clear 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 states a specific verb+resource scope: transfers between two on-budget accounts reviewed month by month against category-group assignments. It explains why the analysis exists (on-budget transfers move no category money while looking like normal transactions). It does not explicitly differentiate itself from siblings like analysis_flow_trace or money_movements_list_by_month, so it stops 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?

It gives concrete conditional guidance: pass group_ids to get flagged months where money moved with no assignment, omit them to get the transfers alone, and it names categories_list as the source of group ids. It also documents accepted date formats. It lacks explicit 'do not use this when...' framing relative to sibling analyses, so 4 rather than 5.

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

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

Annotations already declare readOnlyHint/openWorldHint/destructiveHint, so the bar is lower, yet the description adds real behavioral detail: it discloses the exact criterion that sets is_risk=true (insufficient category balance) and the default/ceiling for the scan window. It omits any note on cost or result volume, so it is not a 5.

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

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

Three compact sentences, front-loaded with the core purpose and capability. The '[READ]' prefix partially duplicates the readOnlyHint annotation, which is minor waste but not enough to hurt readability.

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 is not required. For a read-only two-parameter analysis tool, the description supplies the risk criterion and window guidance; only the unexplained plan_id leaves a small gap.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It explains lookahead_days well (default 30, max recommended 90), but plan_id is never mentioned, leaving one of two parameters undocumented in both schema and prose.

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: scheduled outflows within a lookahead window that may exceed category balances, plus the is_risk flagging behavior. This clearly distinguishes it from sibling list tools like scheduled_transactions_list, which merely enumerate scheduled transactions without risk assessment.

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

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

The phrase 'may exceed category balances' implies the analytic use case, but the description never says when to prefer this over scheduled_transactions_list or analysis_overspent_categories, nor any prerequisite for plan_id. Usage is inferable but not explicit.

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

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

Annotations already establish readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavioral context: the confidence tiers (high >=80%, medium >=50%, low <50%) derived from payee history, which shapes how an agent should treat each suggestion.

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, all load-bearing, with scope and the read/write boundary front-loaded. No filler.

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

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

For a simple read-only suggestion tool with an output schema and full annotation coverage, the description supplies purpose, confidence semantics, and the handoff to the write tool. The only real gap is the undocumented plan_id parameter, which is minor relative to everything else covered.

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 (plan_id) with 0% schema description coverage, and the description never mentions it or what scope it controls. The schema provides only a title and null default, so the description leaves the parameter 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?

States a specific verb and resource ('Suggest categories for uncategorized transactions') and the mechanism ('using payee history'). The [READ] prefix plus the explicit pointer to transactions_update cleanly separates it from the write-side 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?

Usage is scoped to 'uncategorized transactions' and the description explicitly states 'Does NOT write — use transactions_update to apply suggestions', naming both the when-not condition and the alternative tool.

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

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

Annotations already declare readOnlyHint/openWorldHint/destructiveHint, so the safety profile is covered. The description adds genuinely useful behavioral detail beyond that: the $50 large-transaction threshold and the split-line flagging rule, which tell the agent what counts as 'probably needs one'.

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 compact sentences, front-loaded with the action and scoping heuristic, then the one parameter hint. 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?

Output schema exists so return values need no explanation, and annotations cover safety. The remaining gap is the unexplained plan_id and the absence of any note on scope/default behavior when since_date 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 description coverage is 0%, so the description must carry parameter meaning. It documents since_date with an ISO format example, but plan_id — a nullable parameter — is not explained at all, leaving half the parameters undocumented.

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

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

States a specific verb and resource ('find transactions missing memos') plus the heuristic that decides inclusion (>= $50, splits without memos). This clearly separates it from siblings like bookkeeping_categorization_suggestions, so an agent can route 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?

The scope ('transactions missing memos that probably need them') implies when it applies, but there is no explicit when-to-use/when-not guidance and no named alternative among the many bookkeeping/triage 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 and destructiveHint=false, so safety is covered. The description adds real behavioral context beyond that: it returns aggregated inflow, outflow, and net totals in addition to the transaction list, and enforces single-filter selection. It does not mention pagination or result limits, 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?

Four sentences, front-loaded with a [READ] tag and the core action, then filters, then the date parameter detail. No filler. Slightly dense around the filter list, but every sentence carries 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 detailed, and the description usefully names the aggregate totals anyway. The gap is plan_id, which is undocumented in both schema and description, leaving an agent unsure how it interacts with the filter 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 description coverage is 0% across 5 parameters, so the description must compensate. It does partially: since_date gets a format and example ('2024-01-01'), and the mutual exclusivity of the three *_id filters is conveyed. But plan_id is never explained, and the filter params get no ID-format guidance. Baseline is above 1 only because of the real added 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 uses a specific verb and resource ('Retrieve recent transactions') and states the scope: filters plus inflow/outflow/net totals. It is clear what the tool does, but it does not explicitly distinguish itself from the many sibling list tools (transactions_list, transactions_list_by_account, etc.), so an agent must infer the difference.

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 provides the key usage constraint that only one of payee_id, category_id, or account_id should be used at a time, which is useful filtering guidance. However, it never says when to prefer this tool over the sibling transactions_* list tools, nor does it state any exclusions or prerequisites.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the '[READ]' prefix is largely redundant. The description does add one genuinely useful behavioral detail not in structured fields: amounts are reported in milliunits (1000 = $1.00), which prevents misinterpretation of returned values.

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 the operation and followed by the unit convention. Nothing is wasted and no filler is present.

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

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

An output schema exists, so return values need not be described, and the milliunits note covers the main interpretive risk. However, for a tool whose schema has 0% parameter documentation, leaving plan_id entirely unexplained makes the definition only minimally complete.

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

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

Schema description coverage is 0% and neither parameter is documented in the schema. The description clarifies that category_id is an ID lookup and introduces the milliunits convention, but the optional plan_id parameter is never mentioned, leaving a real gap in a 2-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 specific verb and resource ('Get a single category by ID'), which is clearer than the sibling list tools and distinguishes the single-item fetch. It does not, however, name the alternatives (categories_list, categories_get_for_month, category_groups_summary_by_month) to route the agent 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?

There is no when-to-use guidance at all: nothing explains when to prefer this over categories_list, categories_get_for_month, or categories_list. The agent must infer usage 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 establish readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful non-schema context: the milliunits convention (1000 = $1.00) and the ISO first-of-month requirement, both of which affect correct interpretation of results. No rate limits or auth notes, but the added unit semantics justify a 4 against an already-covered safety profile.

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

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

Two sentences, zero filler, with the operation and the critical formatting rule (month) and unit scale front-loaded. Every clause carries information an agent needs.

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

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

An output schema exists, so return values need not be described, and the milliunits note covers interpretation anyway. The remaining gap is that two of three parameters (category_id, plan_id) are undocumented in both schema and description.

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

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

Schema description coverage is 0%, so the description must compensate for all three parameters. It does document month's format with a concrete example, but category_id and plan_id remain entirely unexplained, so compensation is only partial.

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

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

States a specific verb and resource ('Get a category's budgeted, activity, and balance') and scopes it to a month, which is enough to distinguish it from the all-time categories_get and the list-oriented categories_list. It stops short of explicitly contrasting with those siblings, so it is clear but not sibling-differentiating.

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 when-to-use guidance, no prerequisites, and no named alternative. The month scoping implies a use case, but the agent must infer on its own that categories_get is the non-month-scoped counterpart.

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 only cover the safety profile (readOnlyHint=true, destructiveHint=false); the description adds substantial operational context beyond that — milliunits convention (1000 = $1.00), current-month scope, roughly a quarter payload size for compact mode, that hidden categories are where credit-card payment categories live, and that deleted categories are never returned.

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

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

Front-loaded with the read verb and resource, and nearly every clause earns its place (units, hidden categories, delta semantics). It runs as one dense unbroken block, which makes it slightly harder to scan than a short structured list would 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?

An output schema exists, so return shape needn't be described, and the description still covers scope (current month), units, hidden/deleted handling, compact mode, and incremental sync. For a four-parameter read tool this leaves nothing an agent needs unresolved.

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

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

Schema description coverage is 0%, so the description carries the full burden, and it delivers: compact, include_hidden, and last_knowledge_of_server are each explained with effect and intended use, including that the value comes from a prior response's server_knowledge. Only plan_id is left implicit, a minor gap given the rest.

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 and scope: '[READ] List all categories grouped by category group.' The note that group listing is embedded here distinguishes it cleanly from categories_get (single category) and the group-summary/money-movement siblings 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?

Gives concrete when-to-use guidance per mode: compact=true 'enough to find an id or read the shape of a plan', include_hidden=true for credit-card payment categories, and delta sync to keep a long session current. It also nudges toward the changes_since sibling for cross-resource sync, but never states explicit exclusions against the other listing 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 readOnly/non-destructive, but the description adds substantial non-obvious context: hidden categories are included by default and why (dropping the credit-card payment group), milliunits convention, and the cost model (one request per month, 36-month cap). This is behavior an agent cannot get from the schema or annotations.

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

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

Front-loads a [READ] tag and the core purpose, then layers format, defaults, cost. Every sentence earns its place with no filler; density is high but not padded.

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; given the tool's complexity, the description covers inputs, defaults, units, cost limits and sibling relationship. Nothing essential to a correct call 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?

With 0% schema description coverage the description must carry parameters, and it does for three of four: from_month/to_month accept 'YYYY-MM', ISO date, or 'current', to_month defaults to current month, and include_hidden defaults true with a rationale. Only plan_id is left 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?

State a precise verb+resource: per-group, per-month totals of budgeted, activity and balance. It explicitly contrasts with a category-level view ('a group view is small enough to read whole where a category view is not'), so an agent can distinguish it from sibling aggregation 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?

Names the question class it serves ('is this budget healthy' at group level), states the default for to_month, and warns to check overview_request_budget before a long range. It routes the agent toward the right scenario and away from costly misuse.

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

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

Annotations already declare read-only, non-destructive, closed-world behavior, and the description adds real context beyond that: deleted records are omitted, a delta only reports that a record changed (not how) so values shown are current, and the call costs three requests regardless of volume. It stops short of describing pagination/limit behavior against the default of 200.

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

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

Front-loads the purpose and the calling protocol, and most sentences earn their place. The cost point is stated twice at the end ('this costs three no matter how much moved' and 'Costs three requests'), which is a minor redundancy.

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

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

With an output schema present, return values need not be described, and the description covers the incremental-sync workflow, deletion behavior, and cost model well. It is only slightly incomplete in not addressing what limit and plan_id do.

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 has to carry the load, and it does explain server_knowledge thoroughly (baseline, then passed back each call). However, limit and plan_id are never mentioned, leaving two of three parameters without any semantic guidance.

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 — what changed in the plan since a given server_knowledge value — and names the entities returned (categories, months, transactions). It is clearly distinguishable from the list/get siblings because it is framed as an incremental delta rather than a full read.

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

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

Gives explicit when-to-use (after the user edits their budget in the app instead of re-reading everything), an explicit calling protocol (call with no arguments first for a baseline, then pass the value back), and an alternative it outperforms (re-reading a range costs one request per month vs. three here).

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds genuine behavioral context beyond that: each entry reports revertability, and history is persisted across restarts even when writes are disabled. It does not describe volume or pagination behavior.

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

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

Three short sentences, front-loaded with the read-only marker and the core behavior, then usage, then a persistence caveat. No sentence 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?

An output schema exists, so return values need not be explained, and the description covers ordering, revertability, usage routing, and persistence. It stops short of documenting parameter semantics or result volume, which is the only meaningful gap for this tool.

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

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

Schema description coverage is 0% and the description never mentions either parameter. The meaning of 'limit' (default 25) and especially 'plan_id' scoping is left entirely to inference, 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 ('List writes this server has made'), plus the ordering ('newest first') and the [READ] tag. An agent can distinguish this from history_show and history_revert siblings 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?

Explicitly says to use this before history_revert or history_revert_to in order to choose an entry, naming the alternatives and the condition that selects this tool. That is a complete when-to-use statement.

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/destructive/openWorld, so the safety profile is covered. The description earns credit for adding semantic context beyond that: the entry contains before and after state, and the before state is what a revert would restore — a real behavioral insight for an agent reasoning about undo.

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, zero filler, with the read-only tag and the core scope front-loaded. Every sentence carries 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 shape needs no explanation, and the description covers what the entry contains and its revert relevance. The only real gap is omitting how the required entry_id is sourced.

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

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

Schema description coverage is 0% and the single entry_id parameter is undocumented in the schema. The description never mentions entry_id, its format, or where to obtain it, so it 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 (Show) and resource (one history entry), plus the distinguishing content: full before/after state. It contrasts adequately with history_list via the 'one ... in full' framing, though it never names 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?

Usage is implied — call it when you have an entry_id and need the complete entry — but there is no explicit when-to-use, no prerequisite (e.g., obtain entry_id from history_list first), and no stated exclusions.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the bar is lower, and the description still adds meaningful non-obvious behavior: groups carry no amount, movements join on money_movement_group_id, and last_knowledge_of_server must be fed the server_knowledge value from a prior response. It does not mention pagination or rate limits, but the delta-sync contract is the important disclosure here.

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

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

Three sentences, front-loaded with the read tag and the core action, then the domain model, then the sync mechanics. Every sentence carries information. The closing clause about changes_since is slightly tangential for a list endpoint but earns its place as sibling routing.

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, and the description covers the object semantics, the join key, and the incremental-read contract. The gaps are minor: what happens when plan_id is omitted (all plans vs. error) and whether results are paginated are not addressed.

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

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

Schema description coverage is 0% and there are no descriptions on either property, so the description must compensate — and it does for the harder parameter, explaining exactly what last_knowledge_of_server expects ('the server_knowledge value any earlier response returned') and why. plan_id is only implied by the phrase 'for a plan', and its null default is never explained.

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 money movement groups for a plan') and then defines the domain object itself: 'A group ties together the movements made in a single action; it carries no amount of its own.' That definition cleanly separates it from money_movements_list and money_movement_groups_list_by_month, which an agent cannot infer from the name alone.

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

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

It gives real guidance for the delta-sync path ('pass last_knowledge_of_server ... YNAB sends only what changed since') and names changes_since as the cross-entity alternative. But it never says when to pick this tool over money_movement_groups_list_by_month or money_movements_list, nor whether plan_id is required in practice, leaving the core routing decision 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, destructiveHint=false and openWorldHint=false, so the '[READ]' prefix is largely redundant. The description does add genuine domain context — that a group is a container with no amount of its own — but says nothing about pagination or the incremental-sync behavior implied by last_knowledge_of_server.

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

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

Three short sentences, front-loaded with the core action, then the domain clarification, then the parameter format. Efficient overall, though the '[READ]' tag duplicates the annotations and is minor 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 values need not be described. However, for a 3-parameter tool with no schema descriptions, the two optional parameters — plan scoping and the server-knowledge cursor — are undocumented, leaving real gaps for correct invocation.

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

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

Schema description coverage is 0%, so the description carries the full burden. It documents month well (ISO date string, first day of month, example), but plan_id and especially last_knowledge_of_server — a sync cursor whose semantics are non-obvious — are left completely 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?

States a specific verb and resource with a clear scope qualifier ('List money movement groups for a specific month'), and the definition of what a group is distinguishes it conceptually from money_movements_list. It does not explicitly name the sibling money_movement_groups_list (all-months) as the alternative, so it stops 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 by the 'by_month' scope and the required month parameter, but there is no explicit when-to-use/when-not-to-use guidance or reference to the unfiltered sibling. An agent must infer that this tool is for month-scoped retrieval versus money_movement_groups_list.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description goes well beyond that by disclosing null-semantics for from/to_category_id (Ready to Assign), the milliunits unit convention, and the stateful sync contract of last_knowledge_of_server — real behavioral context an agent needs to interpret results.

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

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

Front-loaded with purpose and concept definition before the sync mechanics, and every sentence carries information. The final changes_since sentence is slightly tangential for a listing tool, but it is one sentence and it does route the agent correctly.

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

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

An output schema exists, so return values need not be described; instead the description covers the domain concept, unit interpretation, null handling, and sync semantics. For a 2-parameter, zero-required, read-only list tool, that is everything an agent needs 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% and the schema only supplies titles, so the description must carry the load. It does: last_knowledge_of_server is explained as the server_knowledge value from an earlier response, and plan_id is contextualized as the plan being listed. This is meaningful added semantics, though it doesn't state plan_id's type/format or what happens when it is omitted.

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

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

States a specific verb and resource ('List all money movements for a plan') and then defines the domain concept precisely: budgeted funds moved between categories within a month, explicitly not a transaction with no payee or account. That definition cleanly separates it from the many transactions_* and money_movement_groups_* siblings.

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

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

Gives concrete when-to-use guidance for delta sync ('pass last_knowledge_of_server ... and YNAB sends only what changed'), which selects this tool for incremental refresh. It also names the alternative changes_since for cross-resource sync. It stops short of stating when to prefer money_movements_list_by_month or money_movement_groups_list, so it is clear context rather than full 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 establish readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the barrier is low; the description still adds real value with the '[READ]' marker, the milliunits convention (1000 = $1.00), and the rule that a null category id means Ready to Assign. It omits pagination/sync behavior tied to last_knowledge_of_server, keeping 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 compact sentences, front-loaded with the operation, and each sentence adds distinct information (scope, month format, unit conventions). No filler or 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?

An output schema exists, so return values need no explanation, and the required month parameter is fully specified. The only gap is the two optional parameters (plan_id, last_knowledge_of_server), which an agent cannot interpret from either the schema or the description.

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

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

Schema description coverage is 0% across 3 parameters, so the description must carry the load: it documents the required 'month' format thoroughly (ISO first day of month, with example) and explains category semantics, but plan_id and last_knowledge_of_server are never mentioned. The month coverage is good, the rest is undocumented in both places.

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+resource+scope ('List money movements ... for a specific month') and even defines the domain term ('budgeted funds moved between categories'), so an agent knows exactly what comes back. It does not explicitly distinguish itself from close siblings like money_movements_list or money_movement_groups_list_by_month, so it stops 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?

There is no when-to-use, when-not-to-use, or alternative routing guidance. The agent is left to infer from the name alone whether to prefer this over money_movements_list or the groups variant. The only contextual help is about parameter semantics, not tool selection.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description nonetheless adds real behavioral context beyond the annotations: deleted categories are never returned, hidden categories are where credit-card payment categories live, and amounts are in milliunits (1000 = $1.00). It stops short of describing pagination or error behavior, but adds meaningful value.

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

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

Front-loads the core action and payload, then packs format, compaction, hidden-category, and unit notes into tight clauses. Every sentence adds information, though the milliunits and hidden-category asides make it slightly dense for a single-resource getter.

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 structure needn't be re-explained, yet the description usefully covers units (milliunits) and what fields compact returns. Combined with the format guidance for 'month' and the sibling routing, an agent has everything needed to invoke 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 0%, so the description carries the full burden. It fully documents the required 'month' param (three accepted ISO/YYYY-MM/'current' forms), the compact flag's effect and size tradeoff, and include_hidden's semantics. The 'plan_id' parameter is never mentioned, which is the one clear gap for a 4-param 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 specific verb ('Get') and resource ('one month's categories') with the exact payload contents (budgeted, activity, balance). It also names the sibling months_range and the condition that distinguishes them, so an agent can disambiguate 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?

Explicit when-to-use guidance for each mode: compact=true for month-over-month review, full form only when goal fields or notes are needed, include_hidden=true specifically to surface credit-card payment categories. It also routes multi-month comparison to months_range (up to 36 months), naming the alternative directly.

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, but the description adds substantial context: milliunits convention, the default omission of empty months, the omitted_month_count field, the caveat about pre-plan months carrying stray assignments and large negative to_be_budgeted, and the delta-sync mechanism via server_knowledge. This is well beyond annotation coverage.

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

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

Dense but front-loaded: the read nature and payload come first, followed by omission behavior and delta sync. The final changes_since sentence is slightly tangential but earns its place by routing to the correct alternative.

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, yet the description still surfaces key response fields (omitted_month_count, server_knowledge). Combined with the omission caveat, an agent has everything needed to call and interpret this tool correctly.

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

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

Schema description coverage is 0%, so the description carries the burden. It explains include_empty and last_knowledge_of_server meaningfully (including the server_knowledge source), but plan_id is never mentioned, leaving one of three parameters undocumented.

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

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

'[READ] List budget months with summary data' gives a specific verb, resource, and payload fields. This clearly distinguishes it from months_get (single month) and months_range among the siblings.

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

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

Explicitly documents when months are excluded by default, when to use include_empty, when to use last_knowledge_of_server for delta sync, and names changes_since as an alternative that spans categories/months/transactions. Provides concrete 'why' context for the omission behavior.

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

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

Beyond the readOnlyHint/destructiveHint annotations, it discloses real operational traits: the as_of snapshot nature and caching hazard, one request per month consumed, and a 36-month cap. These are exactly the behavioral facts annotations cannot carry.

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 [READ] tag and core purpose are front-loaded, and nearly every sentence carries distinct information. It is a long single paragraph, so the cost/limit and milliu nit details could be split for scannability, costing a point on structure rather than content.

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 shape need not be explained, yet the description still adds the one piece the schema can't convey: that as_of makes the result a point-in-time snapshot. Combined with cost limits, milliunit units, and filter semantics, it is complete for a 7-param 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?

With 0% schema description coverage, the description carries the full burden and does: from_month/to_month accepted formats ('YYYY-MM', ISO date, 'current'), to_month default, category_ids vs group_ids precedence, the meaning of fields and its cost trade-off, and include_hidden behavior. Only plan_id goes undocumented.

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

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

The description opens with a specific verb+resource: '[READ] Budgeted, activity and balance for every category across a range of months, as one matrix.' It explicitly distinguishes itself from months_get ('one call instead of one months_get per month') and points to changes_since for staleness, so an agent can route 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?

It names the use case ('any month-over-month question'), the alternative it replaces (per-month months_get), and the escalation path for stale data (changes_since), plus a prerequisite check (overview_request_budget before a long range). When-to-use is explicit rather than 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 declare readOnlyHint=true, so safety is covered; the description goes beyond them by disclosing that the response carries conventions such as how amounts are expressed, which reads cost a request per month, and hidden categories. That is genuinely useful pre-call context, though return shape details are left to the output 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?

Three sentences, front-loaded with the [READ] marker and the primary action, then the routing advice, then the extra payload. Efficient, though the middle and last sentences could be tightened slightly.

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 enumerated, and the description supplies the routing rationale and the notable extra content the overview returns. Complete enough for an agent to decide to call it first, with only minor room for detail.

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 takes zero parameters, so there is nothing for the description to disambiguate; baseline for a no-param tool is 4. No param-level value could be added here.

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

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

States a specific verb and resource ('List all available tools grouped by family, with classification and summary') and its scope is unambiguous. As the meta/overview tool it is inherently differentiated from every domain sibling like payees_get or transactions_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?

Explicitly directs the agent: 'Start here to understand what the server can do before running other tools.' That is clear when-to-use guidance, though it gives no when-not condition or named alternative (the schema itself has no competing sibling).

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

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

Annotations already cover the read-only/safe profile, but the description adds genuinely non-obvious behavioral context: the check is health-independent, so a failure signals data inconsistency (stale read, missing category, uncounted account), and it discloses cost ('Costs three requests'). That is real added value beyond the 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?

Front-loads the [READ] tag and the purpose, then adds interpretation and cost in tight sentences. No sentence is filler; each adds a distinct piece of 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 needn't be explained, and annotations plus the description cover safety, cost, and interpretation. The only shortfall is the silent handling of plan_id, which an agent must guess.

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 one optional parameter at 0% schema description coverage, the description carries the burden but never mentions plan_id or what happens when it is omitted (default null). The name is fairly self-explanatory in a 'plan' domain, but the semantics of the default are left to inference.

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 precise verb (check) and resource (the plan's balance identity) and spells out the exact arithmetic relation it verifies (category balances + Ready to Assign = on-budget account balances + credit-card debt). This is specific enough to distinguish it from siblings like overview_cash_position or overview_budget_snapshot.

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

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

Gives explicit when-to-use guidance ('Run it first in a review') and, crucially, tells the agent how to interpret the result — a tie means downstream numbers can be trusted, a mismatch means inconsistent data rather than bad budgeting. This steers invocation order and interpretation clearly.

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, openWorldHint=false, destructiveHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: it is a 'single-call' aggregate and, crucially, 'Costs three requests,' a cost disclosure an agent needs before invoking. This is the kind of non-obvious trait the description should carry.

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

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

Front-loaded with the '[READ] Single-call budget health snapshot' lead, then outputs, then unique fields, then cost. Every sentence earns its place, including the cost note, with no redundancy or filler.

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

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

An output schema exists, so return values needn't be explained in prose, and annotations cover the safety profile; the description still adds selection value by naming the aggregate contents and the unique fields. The only material gap is the unexplained plan_id, which keeps it from a full 5.

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

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

The single parameter plan_id has 0% schema description coverage and is not mentioned anywhere in the description. With low coverage the description must compensate for the ambiguity (what plan_id means, whether it defaults to a primary plan), and it does not; the agent must infer behavior from the nullable default alone.

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

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

States a specific verb+resource ('single-call budget health snapshot') and enumerates the concrete outputs (income, spending, to-be-budgeted, age of money, overspent categories), which lets an agent predict the payload. It also flags value nothing else surfaces (unfunded_card_debt, trapped_funds), aiding disambiguation. It stops short of naming which sibling overview_* tool it replaces, so it's clear but not fully differentiated.

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?

'Good first call for any budget session' gives explicit positive context for when to reach for it. It does not, however, name alternatives (overview_month_health, overview_balance_identity, overview_cash_position) or state when-not to use it, so an agent can't fully route between the sibling overview 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=true, destructiveHint=false, and openWorldHint=false, so the '[READ]' tag is largely redundant. The description adds that the breakdown is cleared vs uncleared for on-budget accounts only, which is genuine behavioral context beyond the annotations, but says nothing about whether plan_id changes scope or about pagination/limits.

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

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

Three short sentences, front-loaded with the operation and then the return contents. The '[READ]' prefix is redundant given the readOnlyHint annotation, but otherwise 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?

An output schema exists, so the enumeration of returned values is not strictly necessary and the description needn't explain returns. However, the one input parameter is left unexplained and there is no guidance on when to reach for this tool among the many overview siblings, leaving the definition minimally adequate rather than complete.

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

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

One optional parameter (plan_id) with 0% schema description coverage, and the description never mentions it. It does not explain what plan_id selects or what happens when it is omitted (default null), leaving the single parameter's semantics entirely undocumented.

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

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

States a specific verb ('Summarize') and resource ('account balances') and enumerates what it returns (on-budget total, off-budget total, net worth, per-account detail), so the agent knows exactly what this produces. It does not, however, explicitly distinguish itself from near siblings such as overview_balance_identity or overview_budget_snapshot, which is the only thing keeping it from a 5.

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

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

There is no statement of when to choose this over the many other overview_* tools (budget_snapshot, month_health, balance_identity). Usage is only implied by the name and the 'cash position' framing. No prerequisites or exclusions are given.

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

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

Annotations already declare read-only, non-destructive, closed-world, so the safety profile is covered. The description goes further with non-obvious behavior: it costs two requests, it reports the previous month's overspending by group because it is settled before this month, and only cash overspending comes out of Ready to Assign. That is genuine 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?

The purpose and returned fields are front-loaded in the first sentence, and the default behavior follows immediately. The middle explanation of previous-month overspending is a long, dense clause, but it conveys a real semantic trap rather than 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 the description is not obliged to enumerate return values, yet it does. With annotations covering safety and cost/behavior quirks disclosed, the main remaining gap is the undocumented plan_id 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?

Schema description coverage is 0%, so the description carries the full parameter burden. It defines month precisely ('ISO date string for first day of month, e.g. 2024-01-01') but says nothing about plan_id, leaving one of two parameters undocumented in both places.

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?

[READ] Summarize a budget month' is a specific verb+resource, and the description enumerates the returned measures (income, budgeted, activity, to-be-budgeted, overspent categories, underfunded goals) plus the previous-month overspending report. It separates itself from analysis_overspent_history by name. It does not, however, distinguish itself from close overview siblings like overview_budget_snapshot, so it falls 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?

The only routing guidance is implicit: 'Defaults to current month' and the pointer to analysis_overspent_history when the cash-vs-card split of overspending matters. There is no statement of when to prefer this over overview_budget_snapshot, months_get, or months_range, so 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?

Goes well beyond the readOnlyHint/destructiveHint annotations by disclosing that the tool costs no API requests, that the quota belongs to the access token and is shared with the user's own YNAB apps, and that the reported figure reflects this server's spend rather than YNAB's true remainder.

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

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

Four sentences, each earning its place, with the direct answer ('how many requests remain') front-loaded before the caveats about scope and cost.

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; the description supplies the quota semantics, the approximate limit, and the zero-cost trait that an agent needs to use the result 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?

There are zero parameters, so the schema carries no semantic burden and the description has nothing to add; baseline 4 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 (read) and resource (remaining API request budget in the current rolling hour) and distinguishes itself from every sibling by noting they already return requests_used_this_hour and requests_remaining.

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 scopes when to call it: 'call this one only for the rest: the limit, the window, and when an exhausted budget reopens', and tells the agent not to call it for data already present in other tools' responses.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description's '[READ]' tag merely repeats readOnlyHint and it adds no new behavioral context — no not-found/error behavior, no permission requirements, no note on whether it is scoped to plan_id.

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 the operation and the resource, with no redundant filler. The '[READ]' prefix is wasted space given readOnlyHint already conveys it, slightly costing efficiency.

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

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

An output schema exists, so return values need not be described, and the core lookup is adequately conveyed. Still, the unaddressed plan_id parameter and lack of any not-found/scope behavior leave gaps for a tool whose schema provides zero description coverage.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning, and it largely does not: it covers the required payee_location_id only implicitly ('by ID' and 'lat/lon data') while the optional plan_id parameter is left entirely unexplained in both schema and 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 and resource ('Get a single payee location by ID') and clarifies the data is geographic lat/lon, which distinguishes it from the list siblings (payee_locations_list, payee_locations_list_for_payee). It does not name those siblings explicitly, so an agent still has to infer that 'single by ID' is the differentiator.

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 'Low priority: rarely useful for AI budget workflows' note is a genuine when-not signal that helps an agent deprioritize this tool. However, it never points to an alternative (e.g., use payee_locations_list_for_payee to enumerate) or states the condition under which this lookup *is* 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 declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered, and the '[READ]' prefix only restates that. The description adds real value by explaining the data's origin (bank imports), but says nothing about result volume, pagination, or scope limits.

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

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

Two tight sentences, front-loaded with the operation and its data meaning. The '[READ]' tag is redundant with readOnlyHint but costs only a few characters.

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

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

An output schema exists, so return values need not be described, and the priority warning covers routing. The remaining gap is plan_id, undocumented in both schema and description, which leaves the agent guessing about scoping.

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

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

Schema description coverage is 0% and the single parameter (plan_id, nullable, defaulted to null) is never mentioned in the description. With no schema-level documentation, the description carries the burden here and fails to explain what plan_id scopes or what happens when it is omitted.

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

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

States a specific verb+resource ('List all payee locations') and disambiguates with a parenthetical defining what a payee location is ('geographic lat/lon data from bank imports'). It does not explicitly distinguish itself from close siblings like payee_locations_get or payee_locations_list_for_payee, so it stops 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?

Explicitly flags priority ('Low priority: rarely useful for AI budget workflows'), which steers the agent away from over-calling and is genuine when-to-use guidance. It does not name the alternative tool to use instead, so it isn't fully prescriptive.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds only the '[READ]' tag, the lat/lon nature of the payload, and a priority hint — some value, but no detail on pagination, auth, or result volume.

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 the action and scope, with the caveat trailing deliberately. Nothing is redundant or padded.

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

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

An output schema exists, so return values need not be described, and annotations carry the safety profile. The gap is the undocumented plan_id parameter, which an agent cannot resolve from description or schema.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. 'Specific payee' loosely implies payee_id, but plan_id is never mentioned and no format or filtering semantics are given for either 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?

States a specific verb and resource ('List all locations') scoped to 'a specific payee', with the parenthetical clarifying the data is geographic lat/lon. The scope phrase implicitly separates it from the sibling payee_locations_list, though that sibling is not named.

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

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

Provides an explicit negative-use signal ('Low priority: rarely useful for AI budget workflows'), which is genuine when-not-to-use guidance. It does not, however, route the agent to a better alternative for the task it is discouraging.

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

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

The '[READ]' prefix simply restates the readOnlyHint=true annotation, adding no new behavioral context. Nothing is said about what happens for an unknown payee_id, whether the optional plan_id changes the result scope, or any authorization requirements. With annotations covering the safety profile, the description was free to spend its words on behavior and chose not to.

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, front-loaded with the verb and resource; no padding. The redundant '[READ]' tag is the only wasted token, but the description is otherwise tight.

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 return shape need not be described, but with 0% schema coverage the description should at minimum explain plan_id and error behavior for a missing payee. Two parameters, one of them unexplained, leaves the agent guessing before invocation.

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

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

Schema description coverage is 0%, so the description carries the full burden, yet it only implies payee_id ('by ID') and never mentions plan_id at all. The meaning of a nullable plan_id — whether it scopes the payee to a plan or defaults globally — is undocumented in both places.

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

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

States a specific verb and resource ('Get a single payee') and scopes it to one record versus a collection. It does not name payees_list as the alternative, so sibling differentiation is left to inference.

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

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

There is no statement of when to use this versus payees_list or payee_locations_list_for_payee, and no prerequisites (e.g. does payee_id need to come from a prior list call?). The agent must infer all of this from the 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=true, openWorldHint=false and destructiveHint=false, so safety is covered. The description adds genuinely non-obvious behavior: incremental/delta retrieval semantics and the meaning of the server_knowledge token, which an agent could not infer from 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?

Front-loaded with the core action and the delta-sync mechanic immediately after. The closing sentence on changes_since is somewhat tangential for a payees tool but earns its place as a routing hint; otherwise the text is tight.

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 still usefully ties last_knowledge_of_server back to the server_knowledge value in responses. Only the plan_id default and behavior when omitted are left unaddressed.

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% with 2 parameters, so the description carries the burden. It compensates well for last_knowledge_of_server (origin of the value, effect on the response), but plan_id is never mentioned and its null default is unexplained. Partial compensation justifies the 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 ('List all payees for a plan') with the [READ] marker, which is enough to distinguish it from payees_get, payee_locations_list, and transactions_list_by_payee. It does not explicitly name the sibling it is not, so it stops 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?

Explains the condition for using the delta-sync parameter ('pass last_knowledge_of_server ... and YNAB sends only what changed since') and points at changes_since as the cross-resource alternative. It gives clear context but no explicit exclusions or a when-not-to-use statement.

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

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

Annotations already declare readOnlyHint/openWorldHint/destructiveHint, but the description adds behavior those annotations cannot convey: zero API calls, no token validation, no budget read, and the deliberate quota-free design intent. It also previews the payload (version, whether write tools are registered, request budget), which is real disclosure 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?

Front-loaded with the [READ] tag and the core question, then rationale and return contents. The rate-limit rationale sentence is longer than strictly necessary, but it is the tool's raison d'être and each sentence carries 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-parameter ping with an output schema, the definition supplies everything an agent needs: what it does, why it exists, its cost profile, and a preview of the return. Nothing material 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?

There are zero parameters and 100% schema coverage, so the baseline is 4. The description correctly treats this as a no-argument call and spends no words on non-existent 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 — a health/ping check on the server — and immediately scopes it ('answers from the process alone'). It is clearly distinguishable from data-reading siblings like overview_request_budget or transactions_list because it explicitly performs no YNAB request, token check, or budget read.

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 when-to-use scenario: an agent that has been rate limited and needs a reachability check that does not spend quota or fail for unrelated reasons. It effectively describes when-not-to-use (anything that touches the API/token). It stops short of naming a specific alternative sibling, so it is clear context rather than full routing.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the description is free to add the delta-sync behavior — a genuinely useful trait not derivable from structured fields. It stops short of error behavior or what 'full data' resolves to when plan_id is null.

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

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

Three tight sentences, front-loaded with the [READ] tag and the core action, then the optional delta-sync mechanism. Every sentence earns its place and none repeats the schema.

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

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

An output schema exists, so return values need not be spelled out, and the delta-sync loop is fully explained. The remaining gap is the null/omitted plan_id case, which is left undefined for a tool where that parameter is not required.

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

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

Schema coverage is 0%, so the description carries the burden. It explains last_knowledge_of_server well (delta sync semantics and the server_knowledge handshake), but says nothing about plan_id, which is optional with a null default — an agent cannot tell what omitting it does.

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

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

The description states a specific verb and resource ('Get a single plan') plus the scope of returned data ('full account, category, and month data'), which implicitly separates it from plans_list. It never names plans_list or plans_get_settings explicitly, so sibling differentiation is inferred rather than stated.

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

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

It gives one concrete usage condition: pass last_knowledge_of_server for delta sync. But it never says when to prefer this tool over plans_list or plans_get_settings, nor when plan_id should be omitted (its default is null). Usage context is implied but incomplete.

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, so the safety profile is covered. The description still adds real value by disclosing scope limits — it says the endpoint deliberately returns only formatting preferences, which prevents an agent from expecting budget data. It omits any note on permissions or failure modes, 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?

Two sentences, front-loaded with the read verb and the payload description, followed by the scope caveat. 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?

An output schema exists, so return values need no explanation, and the read-only nature is covered by annotations. The only real gap is the undocumented plan_id parameter and what happens when it is omitted, which leaves the agent guessing at the call shape.

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

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

Schema description coverage is 0% and plan_id carries no documentation in the schema. The description never mentions plan_id, its optionality, or the effect of its null default, so it does not compensate for the coverage gap on the one parameter that exists.

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 plan settings') and enumerates the returned content ('currency format and date format'). The explicit exclusion of budget data separates it from the sibling plans_get, which a reader can distinguish 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 note that the endpoint is 'intentionally narrow' and returns formatting preferences rather than budget data implies when this tool is the right pick, but it never names an alternative or states a triggering condition. Usage is inferable rather than spelled out.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered and the bracketed "[READ]" tag is largely redundant. The one piece of added context is the auth-scoped visibility ("available to the authenticated user"), which is modest value over 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?

A single front-loaded sentence with no filler, so an agent can read it instantly. The only slight waste is the "[READ]" prefix, which merely restates the readOnlyHint annotation.

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 list tool with an output schema that documents the return shape, the description supplies identity and access scope adequately. It could note relationship to plans_get, but nothing essential to invoking it is missing.

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

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

The tool takes zero parameters, so there is nothing for the description to clarify and the baseline of 4 applies. No parameter-level detail is needed or missing.

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

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

States a specific verb ("List") and resource ("YNAB plans (budgets)") with a clear scope ("available to the authenticated user"). The plural "all" implicitly distinguishes it from the sibling plans_get, though no sibling is named 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?

The description offers no when-to-use or when-not-to-use guidance and never mentions the sibling plans_get for retrieving a single plan. For a discovery-style list tool, a note like "use this first to obtain plan IDs" would be the natural place to route the agent, but none is 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 cover the safety profile (readOnlyHint=true, destructiveHint=false), yet the description adds real incremental context: it costs two requests, it changes nothing, and the cleared balance is computed as of the given date so it can legitimately differ from YNAB's current figure. It also explains what the four output queues represent, which is behavioral substance the annotations cannot carry.

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

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

Front-loaded with the question it answers and marked [READ]; the parameter notes and closing resource-cost line are compact and each earns its place. The opening sentence is somewhat run-on with its four-queue enumeration, but no sentence 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?

An output schema exists, so return values need not be spelled out, and the description still goes further by characterizing what those outputs mean. Combined with the safety annotations, the alternative-tool pointer, and the parameter units, an agent has everything needed to select and 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?

With 0% schema description coverage the description must compensate, and it does for the two required/central params: statement_balance is documented with units and sign convention (milliunits, 1000 = $1.00, negative for money owed) and as_of_date with format and default. stale_after_days is only obliquely implied by "old enough to be suspect" and plan_id/account_id get no mention, so it is strong but not complete.

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 with scope: it answers whether an account agrees with its statement and enumerates exactly what it returns (cleared balance, statement balance, difference, four explanatory queues). It explicitly distinguishes itself from the sibling write path by naming reconcile_apply, so an agent can route 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?

"This is what YNAB's reconcile screen does, and nothing else here answers it" gives clear when-to-use framing, and "reconcile_apply is the write" names the alternative for the mutation case. No explicit when-not or prerequisite conditions beyond that, so it falls short of 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 readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds genuine value beyond them with the '[READ]' marker and the milliunits convention (1000 = $1.00), which prevents misreading returned amounts; it omits auth requirements and error behavior for a missing ID.

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 the operation and followed by the unit convention. Nothing is wasted.

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

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

An output schema exists, so return structure need not be described, and the milliunits note covers the one ambiguous output convention. However, the unexplained optional plan_id parameter leaves the definition short of complete for a 2-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 description coverage is 0% for two parameters, so the description must compensate. It clarifies scheduled_transaction_id implicitly ('by ID') but says nothing about the optional plan_id, leaving half the parameters undocumented in both schema and description.

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

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

The description gives a specific verb+resource+scope ('Get a single scheduled transaction by ID'), which cleanly separates it from the sibling scheduled_transactions_list. An agent can pick the right tool 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?

Usage is only implied by 'by ID' — the description never states when to prefer this over scheduled_transactions_list or analysis_upcoming_scheduled_risks, nor any prerequisite such as needing an ID from the list call first. Adequate but with clear gaps.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds real context beyond that: amounts are in milliunits (1000 = $1.00), each record carries date_next, and the server_knowledge delta-sync contract is explained. No rate limits or error semantics, but strong for a list tool.

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

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

Front-loaded with the operation and its [READ] marker, then date_next prefix, units, and delta-sync. Every sentence earns its place, though the closing sentence about changes_since is more about routing than about this tool and could be trimmed.

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

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

For a 2-parameter list tool with an output schema (so return shape need not be described), the description covers the operation, the delta-sync contract, units, and an included field. The only hole is the undefined plan_id, which is minor given the surrounding plans_* tools.

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

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

Schema coverage is 0%, so the description must carry the burden, and it does for the non-obvious parameter: last_knowledge_of_server is defined as the server_knowledge value returned by an earlier response. plan_id is never mentioned, which keeps this from 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?

Opens with a specific verb and resource plus scope: "[READ] List all scheduled transactions for a plan," and flags the [READ] nature up front. It does not, however, differentiate itself from the closely-named sibling scheduled_transactions_get or from the broader changes_since, so the agent must infer the list-vs-single distinction.

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 when-to-use rule for delta sync ("pass last_knowledge_of_server … YNAB sends only what changed") and names changes_since as the broader cross-entity alternative. It stops short of an explicit when-not-to-use or a direct either/or against scheduled_transactions_get.

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/non-destructive, so the bar is lower, yet the description still adds real domain context: split transactions return subtransactions, transfer_account_id flags transfers, and amounts are in milliunits. It doesn't cover not-found/error behavior, which would be the remaining useful addition.

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, front-loaded sentences with the read marker first and zero filler. Each sentence contributes distinct information an agent needs.

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-value documentation is unnecessary, and the description covers the notable edge cases (splits, transfers, units). The gap is the undocumented plan_id, but otherwise complete for a simple getter.

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

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

Schema description coverage is 0%, so the description must compensate, but it only indirectly gestures at transaction_id ('by ID') and says nothing at all about plan_id — its meaning, default, or whether it is required. The milliunits note describes values in the response, not 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 ('Get') and resource ('a single transaction by ID'), and the phrase 'single transaction' cleanly distinguishes it from the many transactions_list* siblings. An agent can pick this over transactions_list 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?

The 'by ID' framing clearly implies this is the tool to use when a transaction_id is already known, versus list/search tools for discovery. It never explicitly names alternatives or states when-not-to-use, so it stops short of a 5.

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

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

With readOnlyHint and destructiveHint already declared, the description adds substantial behavioral context: milliunits, inclusion of subtransactions, pagination envelope, delta-sync mechanism, filter-before-paging, field projection, and the semantic implications of omitted null fields. This goes well beyond what annotations cover.

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

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

The description is dense but every clause carries operational information, and the core purpose is front-loaded. It is a run-on block without structural breaks, which slightly reduces readability.

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

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

For a tool with 11 optional parameters, delta sync, pagination, and an output schema, the description covers filters, paging, sync, field projection, and null-field semantics thoroughly. The main gap is not routing to the by-account/category/payee/month siblings, but the tool's own behavior is well specified.

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