Yomio

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

readOnlyHint=true already establishes this as a safe read, so the description is not the sole carrier of the safety profile. It adds no further behavioral context, however: nothing about whether periods may overlap, must be equal length, or whether the result is a delta, ratio, or raw side-by-side totals. With annotations covering safety, a 3 is the right level.

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

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

A single sentence with no filler, and the core purpose is front-loaded. It is efficient, though borderline terse for a tool with four required date parameters.

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 comparison tool with no output schema, the description states the metric (spending) but not the shape of the comparison (delta vs. percentage vs. per-category breakdown) or constraints relating period 1 to period 2. Adequate to call it, but not complete.

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

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

Schema description coverage is 100% — all four date parameters are documented with format and role in the schema. The description adds nothing beyond this (no ordering rules, no equal-length requirement), so the baseline 3 applies.

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

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

The description names a specific verb (compare) and resource (spending) with a clear scope: two time periods. It distinguishes itself implicitly from list-style siblings like get_expenses or get_spending_summary, but never explicitly contrasts with them.

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

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

There is no guidance on when to choose this over get_spending_trends or get_spending_summary, nor any stated prerequisites or exclusions. The agent must infer that this is the two-period delta tool from the name and description 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?

The readOnlyHint annotation already establishes that this is a safe read operation, so the description is not carrying the safety burden. It adds a small amount of context by implying an unfiltered enumeration of all accounts with their balances, but says nothing about ordering, pagination, or currency handling.

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

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

A single front-loaded sentence that names the verb, resource, covered account types, and the included balance data with no filler. Every clause earns its place.

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

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

For a zero-parameter read-only listing tool with no output schema, the description conveys enough to call it correctly: what it returns (accounts plus balances) and that no filtering is applied. It lacks detail on return ordering or currency, but nothing essential for invocation is missing.

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

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

The tool takes zero parameters, which sets the baseline at 4. There is nothing further the description could reasonably document about inputs, so this dimension is satisfied by default.

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

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

The description gives a specific verb ('Get') and resource ('payment accounts'), and clarifies the scope by enumerating account types (cash, cards, bank accounts) and noting that balances are included. It is clear on its own, but it does not explicitly distinguish itself from nearby siblings such as get_balance_overview or get_income_summary, leaving the agent to infer the boundary.

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

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

There is no guidance on when to use this tool versus alternatives like get_balance_overview, nor any stated prerequisites or exclusions. The agent must infer usage purely from the resource 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, so the safety profile is covered. The description adds nothing beyond that: it does not say how the period is aggregated, whether the range is inclusive, or how income and expenses are compared, leaving the behavioral picture essentially empty.

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

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

A single front-loaded sentence with no filler or repetition. It is efficient, though its brevity stems partly from under-specification rather than disciplined editing.

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

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

For a two-parameter, read-only tool with full schema coverage the requirements are modest, and the description conveys the gist of what is returned. With no output schema, though, it should say more about the shape of the "overview" (totals only, per-category, per-period), which it does not.

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

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

Schema description coverage is 100% and both startDate/endDate are documented in the schema as YYYY-MM-DD. The description adds no format, boundary, or default information beyond the schema, which matches the baseline 3 for fully documented 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 ("Get income vs expenses balance overview"), so an agent can tell it apart from tools like get_top_merchants or search_expenses. However, it gives no hint of how it differs from near-neighbours such as get_income_summary or get_spending_summary, and "overview" leaves the granularity unspecified.

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 exclusions, and no named alternative among the 15 sibling tools. The income-vs-expenses framing only weakly implies the scenario (a combined balance view rather than a single-sided summary).

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

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

Annotations declare readOnlyHint=true so safety is covered. The description adds that it returns spending-vs-budget comparison for a month, a mildly useful behavioral detail, but says nothing about return format or how budget is compared.

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 clean sentence, front-loaded with the primary action. No wasted padding, though it is arguably too terse for the missing usage guidance.

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

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

For a simple read-only computed tool with no output schema, the description covers the core purpose but omits return shape and how status is derived, leaving gaps an agent would need to fill.

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

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

Schema coverage is 100% with all three params documented including examples. The description adds only the notion of 'specific month' scoping and currency context, no real meaning beyond the schema.

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

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

States a specific verb (get) and resource (budget status), plus clarifies it includes spending vs budget for a month. It is distinguishable from siblings like get_spending_summary, though it doesn't explicitly differentiate itself from get_balance_overview or get_spending_summary.

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

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

No guidance on when to use this versus analogous siblings such as get_spending_summary or get_balance_overview. The only context is the 'specific month' scoping, leaving alternatives implicit.

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 adds that both system and custom categories are returned, which is useful context beyond the annotation, but doesn't discuss caching, pagination, or ordering.

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

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

Two sentences, front-loaded with purpose, followed by return details and a usage instruction. Every sentence carries information with no filler.

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

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

For a zero-param, read-only reference tool without an output schema, the description covers purpose, scope, return fields, and how to use it before reclassify_item. Nothing an agent needs 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?

Zero parameters means no semantic burden; baseline is 4. The description's return-field list (code, name, description, color, icon) is extra value since there is no output schema.

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

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

States a specific verb and resource ('Get all available expense categories') and clarifies scope by naming both system defaults and custom categories. An agent can tell this apart from sibling list tools like get_accounts or get_expenses.

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 instructs to call this before reclassify_item when a valid category code is unknown. Names the downstream tool and condition that selects this tool, though it doesn't mention exclusions (which are unlikely for a reference-list tool).

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

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

The readOnlyHint annotation already conveys safety. The description usefully discloses the return payload (line items with prices, quantities, categories), which adds value beyond annotations, but it omits error behavior (e.g., what happens if the ID is not found) and any pagination or size considerations.

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?

One tight sentence that front-loads the action and ends with the most valuable detail (the return contents). No fluff.

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

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

For a simple one-parameter read tool with a clear annotation profile and no output schema, the description adequately explains what is returned. Minor gap: error behavior and whether the line-item list could be large are unstated.

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

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

Schema coverage is 100% and the single parameter (expenseId) is fully documented in the schema. The description adds no extra semantics about the ID format or source. Baseline 3 applies.

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

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

States a specific verb (get) and resource (expense detail by ID) and describes the return contents. It is clearly distinguishable from list-oriented siblings like get_expenses and search_expenses, though it doesn't name them 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 single-item/by-ID scope is implied but there is no explicit guidance on when to use this vs. get_expenses or search_expenses, nor any note on error behavior for invalid IDs.

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?

readOnlyHint=true already tells the agent this is a safe read, so the description's marginal burden is low, but it still adds nothing beyond the annotations and schema: no ordering, no pagination semantics (default limit 20, offset paging), and no indication of how multiple filters combine (AND vs OR) or how date ranges behave.

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 tight sentence with the resource front-loaded and the filter dimensions trailing. Nothing is wasted, though it is arguably under-specified rather than optimally economical.

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

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

For a 9-parameter, no-required-argument list tool with no output schema, the description covers filter intent but omits pagination behavior, result ordering, and how it relates to the overlapping search_expenses sibling. Adequate as a minimum viable definition, but with clear gaps.

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

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

Schema coverage is 67%, and the description's filter list (date, merchant, category, account, text) roughly mirrors the documented parameters. It adds no meaning beyond the schema descriptions and says nothing about the undocumented limit, offset, or transactionType 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 ("List expenses") and enumerates the filter dimensions, so an agent immediately knows what the tool returns. It does not, however, distinguish this from the sibling search_expenses, which appears to serve an overlapping purpose.

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

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

There is no guidance on when to use this versus search_expenses or get_expense_detail, nor any mention of prerequisites or exclusion conditions. The word "optional" is the only usage signal, which an agent could already infer from the all-optional schema.

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

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

readOnlyHint=true already establishes this as a safe read. The description adds return-field context (source, amount, date, account per entry), which is useful in the absence of an output schema, but it says nothing about ordering, pagination behavior beyond the limit, or empty-result handling.

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

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

Two tight sentences with the core action front-loaded and the return shape in the second. No filler or redundancy.

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

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

For a simple zero-required-parameter read tool, annotations cover the safety profile and the description covers the return fields that the missing output schema would otherwise carry. Minor gaps in ordering and pagination keep it from a 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?

Schema description coverage is 100%, so limit, startDate, and endDate are already documented in the schema. The description only restates that date filtering is optional, adding no syntax or format detail beyond the structured fields, which matches 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 (List) and resource (individual income entries) plus the supported filter (date). The word 'individual' implicitly contrasts with the aggregated sibling get_income_summary, but no sibling is named explicitly, 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 explicit when-to-use, when-not-use, or alternative routing. With siblings like get_income_summary and get_expenses, the agent gets no help deciding between a detailed list and a summary view; usage is only implied.

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 adds useful context about what is returned (total amount and entry count), but discloses nothing about aggregation boundaries, currency, or pagination — acceptable given the low bar set by annotations.

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

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

Two compact sentences, front-loaded with the purpose and then the return shape. Nothing is padded, though the second sentence is arguably redundant since it describes return values.

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

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

For a simple two-parameter read tool with full schema coverage and readOnlyHint, the description covers purpose, scope, and the rough return shape — which matters since no output schema exists. Only the lack of guidance on choosing this over get_income_list keeps it from being fully complete.

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

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

Schema description coverage is 100%; both startDate and endDate are documented with YYYY-MM-DD format in the schema. The description only restates the existence of a date range, adding no format or boundary semantics beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource ('Get income summary') plus the scoping dimension (date range). It is distinguishable from siblings like get_income_list and get_spending_summary by resource, though it never names a sibling 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?

Provides no when-to-use guidance, no prerequisites, and no mention of alternatives such as get_income_list for individual entries versus this aggregate summary. Usage must be inferred from the tool 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?

The readOnlyHint=true annotation already tells the agent this is a safe, non-mutating read, so the description need not restate that. It adds nothing further, though: no pagination, sort order, or scope-limits context. With annotations covering the safety profile, this is an adequate but thin 3.

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?

One front-loaded sentence with zero filler; the resource and scope examples are stated immediately. It is efficiently sized for a trivial single-optional-param read tool, though it offers no structure beyond the single clause.

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

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

For a read-only tool with one optional enum parameter, no output schema, and no nesting, the description covers purpose and scope adequately. Nothing an agent needs to call it correctly is missing, though the absence of any filtering/return context keeps it short of excellent.

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

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

Schema description coverage is 100%, and the single status enum param is fully documented in the schema ('Filter by status (omit for all statuses)'). The description adds no parameter detail beyond it, so the baseline 3 for high coverage 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 clear verb (Get) and resource (recurring payments) and disambiguates the resource by enumerating what counts as recurring payments (subscriptions, bills, upcoming charges). It does not explicitly contrast with siblings, but the resource is distinct enough from the other list/summary tools to be selectable.

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 parenthetical scope note implies when this tool applies (recurring rather than one-off transactions), but there is no explicit when-to-use vs when-not, no mention of alternatives, and no prerequisites. Usage is inferable rather than stated.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds the meaningful nuance that this is an aggregation over multiple transactions rather than a narrative description. It does not disclose return shape, totals vs averages, or behavior when no transactions match the range.

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 what the tool does, and the second sentence is a legitimate exclusion rule rather than filler. The second sentence is slightly wordy ('not a narrative description of one') but earns its place by preventing misuse.

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 aggregation with three fully documented parameters and no output schema, the description covers purpose, scope, and the main misuse case. Minor gap: no indication of what the aggregate response contains (e.g. per-group totals), which would matter given there is no output schema.

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

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

Schema description coverage is 100%: startDate/endDate formats and the groupBy enum are fully documented in the schema. The description restates the date range and the category/merchant grouping without adding syntax or constraint details beyond the schema, so the baseline of 3 applies.

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

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

The description gives a specific verb and resource ('Get an aggregate spending total') plus the aggregation dimensions (grouped by category or merchant). It explicitly carves itself away from single-expense description, which helps against get_expense_detail. However, it does not differentiate from other aggregate siblings like get_spending_trends or get_top_merchants, so it falls short of full sibling differentiation.

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

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

There is an explicit when-not-to-use clause: for describing a single already-open expense, use the provided expense data instead. That is a real routing rule. It stops short of naming the alternative tool to use for trend or per-merchant breakdowns, which the sibling list suggests would be useful.

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

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

Annotations declare readOnlyHint=true, so safety is covered. The description adds no behavioral context beyond the annotation, such as aggregation method, timezone handling, or data scope. It does not contradict annotations.

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

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

Single sentence, front-loaded, no wasted words. It is efficient, though its extreme brevity leaves no room for structural aids like usage cues.

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

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

For a simple read-only tool with fully documented params and readOnly annotation, the description is adequate but incomplete. It doesn't explain return values (no output schema) or distinguish itself from similar siblings like get_spending_summary and compare_periods.

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

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

Schema coverage is 100% with all three parameters documented, so baseline is 3. The description's parenthetical (daily, weekly, monthly) loosely maps to the period enum but adds little beyond the schema's 'day/week/month' values and date format descriptions.

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

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

States a specific verb 'Get' and resource 'spending trends over time', with granularity options. It clearly identifies the tool's function but does not differentiate from siblings like get_spending_summary or compare_periods.

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

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

No when-to-use guidance or alternative selection criteria are provided. The description merely states what the tool does, leaving the agent to infer when trends are preferable to summaries or period comparisons.

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, covering safety. The description adds the ranking criterion ('total spending'), which is useful behavioral context, but omits whether ranking is scoped to the date range, how ties are handled, or the return format.

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

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

A single, front-loaded sentence with no wasted words. It is appropriately sized for a simple read-only ranking tool.

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

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

For a simple, read-only tool with full parameter coverage and no output schema, the description is mostly complete. It omits the fact that results are constrained by the required startDate and endDate, which is a minor gap given the schema already marks them 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 description coverage is 100%, so all three parameters are fully documented (dates and limit) in the schema. The description adds no additional meaning or syntax beyond what the schema provides, so this is the expected baseline.

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

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

States a specific verb ('Get') and resource ('top merchants') plus the ranking metric ('total spending'). It is distinguishable from most siblings, though it does not explicitly differentiate itself from the similar get_top_products tool.

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

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

No when-to-use guidance, no alternatives, and no prerequisites are mentioned. The description only restates the tool's output, leaving the agent to infer that it should be used for merchant ranking.

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?

readOnlyHint=true already covers the safety profile, so the description's remaining job is to disclose behavior beyond annotations — it does so with the top-5 cap and the product-name merging rule ('MANGO' + 'MANGO FRESH' = one), which materially changes results and is easy to misread. It stops short of stating default time window behavior, but the merging quirk is the higher-value disclosure.

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

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

Two sentences, zero filler, with the core behavior and the ranking rule front-loaded and the disambiguation clause second. Every clause earns its place.

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

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

With no output schema, the description carries the burden of describing the return, and it does: five products ranked by total cost with merged names. The only gap is the unspecified default date range for an all-optional param set, which an agent choosing to call it would benefit from knowing.

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

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

Schema coverage is 100% and both parameters are documented there, so the baseline is 3. The description mentions no date semantics at all and never says what happens when startDate/endDate are omitted (all-time?), which is the one parameter behavior an agent might need to reason about.

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), resource (top products/items), ranking basis (total cost), result count (top 5), and a non-obvious normalization rule with an example. An agent can distinguish it immediately from get_top_merchants, get_spending_summary, or search_expenses.

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

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

Explicitly names the alternative it should displace ('not search_expenses') and enumerates the triggering intents ('what they buy most', 'suggesting a recipe from frequently-bought ingredients'). This is exactly the when-to-use/when-to-use-something-else guidance the dimension asks for.

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 read-only safety is clear. The description adds that results include actual purchased item names for matching expenses, which is useful return-content context, but doesn't mention pagination, default limit behavior, or sort order beyond the schema hints.

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

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

Two sentences, front-loaded with the core action and keyword scope, followed by return-value guidance. Minor wordiness but no filler.

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

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

For a read-only search with a fully documented schema, the description covers purpose and the key output characteristic (item names). It omits sibling differentiation and result-ordering/pagination context, which 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 coverage is 100%, so all four parameters (query, limit, startDate, endDate) are documented in the schema. The description clarifies query matches merchant or item name but adds no meaning about limit, dates, or keyword behavior beyond that.

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 (search) and resource (expenses) and clarifies the keyword matches merchant or item name. It distinguishes itself somewhat by emphasizing 'what products/groceries' via returned item names, but does not explicitly contrast with siblings like get_top_products or get_expenses.

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?

Implies usage for finding purchased item names by keyword, but offers no explicit when-to-use vs alternatives (e.g., get_top_products, get_top_merchants, get_expenses). The agent must infer selection from the brief context.

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