Vouchernaut

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

Annotations already declare this a safe, idempotent, closed-world read, so the bar is low, yet the description still adds valuable behavioral context: it discloses the shape of results (transfer times, terminals, Safer Parking status, compulsory charges on the day, full price including known fees, tracked booking link). The one gap is that it does not address result count/pagination despite a `limit` parameter.

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

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

The tool's capabilities are front-loaded in a dense but information-rich opening sentence, followed by a short, high-value caveat about pricing scope. The first sentence is long and list-heavy, but no clause is filler.

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

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

With no output schema, the description carries the return-value burden well by enumerating the fields an agent should expect. It also clarifies the pricing precondition for from/to, which is the key nuance for a 5-parameter tool. Only the optional-date and limit behavior remain 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 coverage is 80%, so the schema already documents most parameters (including the London-local-time format for from/to and the IATA/name hint for airport). The description only reinforces that from/to define the priced stay and lists the `type` categories, adding marginal meaning over the schema; it says nothing about `limit`.

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 domain and resource (UK airport car parks from multiple providers) and enumerates the car-park categories returned, so an agent knows exactly what this tool aggregates. It does not need to differentiate from siblings, which are unrelated product/deal tools, but it also never states a crisp verb like 'compare prices' beyond the title.

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

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

Usage is only implied: 'for given drop-off and pick-up times, the full price' and 'Prices are only for a stay given by `from` and `to`' suggest when to supply dates, but the tool can be called with only `airport` required and the description never says what happens (or is returned) in that case. There is no explicit when-to-use/when-not guidance and no named 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 readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds real behavioral context beyond them: the annual calculation basis and its few-pounds-a-year divergence from a payslip, the regional coverage, and the 'information, not financial advice' caveat. It still doesn't state response shape beyond a high-level list, which keeps it at 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?

The opening sentence is long but front-loads what is computed and what is returned, and each subsequent sentence earns its place by adding a caveat, a coverage limit, or a disclaimer. Slightly dense punctuation over four sentences keeps it from a 5.

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

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

With no output schema, the description carries the return-value burden and does so ('by the year, month and week, with each tax band, the sources and a link to the worked answer'). Combined with the accuracy caveat, regional coverage and scope exclusions, an agent has everything needed 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 100%, so all ten parameters are already documented and the baseline is 3. The description adds only holistic context (NI category A, tax-calculated-on-annual-basis), and its 'year, month and week' phrasing omits the 'hour' enum value present in the schema.

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

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

The description states a specific verb and resource with full scope: net UK pay after income tax, National Insurance (category A), student loan and workplace pension, broken down by year/month/week. It is immediately distinguishable from siblings like student_loan_repayments or check_refund_rights.

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

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

It states the scope conditions and explicit exclusions (not K codes, benefits in kind, other income, or the self-employed) and clarifies the annual-vs-payslip calculation basis. It does not route the agent to a named alternative such as student_loan_repayments for loan-only queries, so it falls 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?

Beyond the annotations (readOnly, idempotent, non-destructive, closed-world), the description discloses real behavioral substance: the verdict taxonomy ('lowest we've recorded, no change, cheaper before and when'), that it surfaces rival shops cheaper today, that it returns a 'tracked link to buy', and its methodology limit ('Never uses shops' own "was" prices or RRPs'). The untracked-shop case is explicitly called out, which annotations alone could not convey.

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

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

Two dense sentences that front-load the purpose and then the return contents; nearly every clause carries information. It is slightly run-on — the input enumeration and the output enumeration are packed into the same sentence — but nothing is padding.

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 full burden of describing returns, and it does: verdict categories, competitor pricing, and the buy link. It also covers the degraded case (untracked shop) and the data provenance, leaving no material gap for a single-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 coverage is 100% and there is a single parameter, so the baseline is 3. The description earns a point above baseline by documenting the `ref` format as "<store>/<product>", a syntactic detail the schema description ('or a ref') omits, plus the barcode digit range context.

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 and resource ('whether a product's price at a UK shop is a real deal') and pins the data source ('Vouchernaut's own record of that shop's prices'), which cleanly separates it from generic siblings like get_product or search_products. It also enumerates exactly what the answer contains (today's-price verdict, cheaper shops, buy link), so an agent knows the shape of the result before calling.

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 makes clear what inputs to pass (product page link, barcode, name, or ref) and states a boundary condition — it 'says plainly when the shop isn't one whose prices are tracked' — so the agent knows the failure mode. It never names an alternative tool or says when to prefer price_drops / get_product instead, so it stops short of full routing guidance.

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

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

Annotations already declare a safe read (readOnlyHint, idempotentHint, destructiveHint=false), so the safety bar is low. The description still adds genuine behavioral context: it is informational only, never adjudicates a claim, ranks results by strength, and folds in payment-remedy layers (section 75, chargeback, PayPal, BNPL) and onward guidance.

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 a single dense sentence, but it is front-loaded with the resource and output contents and every clause earns its place (ranking, date, statute names, payment layers, next steps, disclaimer). No filler or restatement of the name.

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

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

With 13 parameters, 6 required, and no output schema, the description carries the return-value burden and does so: it explains the ranked-rights list, the last-day date, the cited statutes, and payment-derived options. Only minor gaps remain around required inputs and result limits.

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 92%, so the schema already carries the parameter documentation and the baseline is 3. The description adds some conceptual meaning to 'paid' (what section 75/chargeback/BNPL add) but does not clarify formats or the roles of parameters like nation or exceptions beyond what the schema states.

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 (UK consumer rights applying to a purchase) and enumerates the exact output: rights ranked strongest first, each with its last day as a date and the governing law, plus payment-method extras and next steps. This is precise enough to distinguish it from every sibling (all shopping/deal tools) 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 implied by the name and by the disclaimer 'Legal information, not legal advice: it never decides a claim', which sets expectations about what the tool will and won't do. However, there is no explicit when-to-use statement, no prerequisites (e.g. that ordered_on/price/paid must be supplied), and no named alternatives. 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 the safety profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint=false), so the bar is lower. The description still adds genuinely non-obvious behavior: a code is returned only where the brand has approved AI assistants, otherwise the store's vouchernaut.com page is returned instead — a data-gating condition an agent cannot infer from the schema. It doesn't discuss error behavior for an invalid/expired id, hence 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?

A single front-loaded sentence leading with what is returned, followed by a compact enumeration of result shapes. The parenthetical about AI-assistant approval is dense but it is load-bearing information rather than filler; no sentence 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-value explanation is technically optional, yet the description uses that space to explain the shape variants and the AI-approval gating, which aids tool selection. For a one-parameter read-only tool this covers what an agent needs; only the relationship to detail-oriented siblings is 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 coverage for the single `id` parameter is 100% and the schema already states it is 'An id from search' with length bounds. The description echoes the same constraint ('one result from search') without adding format, validity window, or expiry semantics. Baseline 3 applies when the schema fully carries parameter meaning.

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

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

The description specifies exactly what is returned: the full text of a single search result, with a concrete enumeration of result types (store codes/deals, product price and code, phone deals, buying guide). It implicitly positions itself against the `search` sibling by framing the input as 'one result from search'. The verb itself ('fetch') is only carried by the name/title, not restated, which keeps this just 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 only implied: 'one result from search' tells the agent this is the drill-down step after `search`, and the schema's 'An id from search' reinforces that sequence. There is no explicit when-to-use vs. when-not, and no mention of the closer siblings like `get_store_offers`, `get_product`, or `check_deal` that also retrieve detail for a single entity.

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

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

Annotations already declare this is a safe, idempotent, non-destructive, closed-world read. The description goes beyond them by disclosing what the results contain, notably total cost with announced price rises itemised in pounds and month, plus tracked retailer links. It does not discuss pagination or result ordering, but that is minor given the annotation coverage.

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

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

Two sentences, front-loaded with the returned payload before the filter list. Dense but every clause carries information; the parenthetical about price rises is long but is the tool's differentiating detail.

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 12 parameters and no output schema, the description carries the return-shape burden and does so with a concrete field inventory (monthly price, upfront, contract length, total cost, data, network, seller, tracked link). Only sorting/limit behaviour and result ordering 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 92%, so the schema already documents nearly every parameter. The description restates the filter dimensions (storage, colour, condition, budget, network, contract length, data) without adding format or value constraints beyond what the schema supplies, 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 ('every deal UK retailers list for one phone'), names the service (Vouchernaut's phone finder), and implicitly separates itself from the SIM-only sibling by scoping to deals 'for one phone'. It stops short of naming the alternative, so an agent must infer the SIM-only 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?

Usage is only implied: the filter list ('Filter by storage, colour, condition, budget, network, contract length and data') tells the agent what the tool can be narrowed to, but there is no when-to-use guidance and no mention of when to prefer sim_only_deals or price_drops instead.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and a closed world, so safety is covered. The description adds meaningful behavioral detail beyond that by disclosing the return contents (price, free plan, trial, platforms, review scores, deals, and the vouchernaut.com page) and the slug-identity rule, which matters because there is no 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?

The content is front-loaded with the covered categories and return fields, but it is delivered as one long run-on sentence with a colon list, and the closing clause about covering every category when `category` is absent is mildly redundant. It is information-dense but not cleanly structured.

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

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

With no output schema, the description does the right thing by enumerating returned fields and the slug rule, and it explains the category default. It leaves gaps around the `limit` parameter (default 10, max 25) and result-count behavior, which an agent invoking it would need to reason about.

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% (query and category are documented, limit is not). The description adds real meaning beyond the schema: category is described as a category slug drawn from the listed set, the no-category default is spelled out, and the note that a tool's slug is also its store's slug clarifies cross-referencing. It still says nothing about the `limit` parameter's role.

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

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

The description clearly identifies the resource (software and AI tools covered by Vouchernaut) and enumerates the returned attributes: price, free plan, trial, platforms, review scores, live deals, and the tool page. However, it never distinguishes itself from close siblings like search_products, get_product, or search_stores, which an agent could easily confuse it with.

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 usage-relevant statement is that omitting `category` covers every category, which is a conditional behavior rather than a when-to-use rule. There is no guidance on when to prefer this tool over search_products, get_product, or search_stores, and no exclusions.

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

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

Annotations already establish the safety profile (readOnly, idempotent, non-destructive, closed-world). The description adds genuinely new behavioral context: the two operating modes, the numeric threshold before shares become quotable, and the concrete fields returned. It does not discuss rate limits or result sizing, which is the only notable gap.

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

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

The definition is essentially two sentences, front-loaded with the return contents, followed by the quotability rule and the list-vs-detail fallback. Dense but every clause carries information; the parenthetical on poll provenance is the only slightly expendable element.

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 shape and does so concretely (question, votes, share, citation page). It also covers the optional-parameter fallback and a data-quality caveat, leaving nothing an agent needs in order to call it correctly.

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

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

Schema coverage is 100% and the schema already says the parameter is a slug drawn from the list. The description goes slightly beyond that by explaining the consequence of omitting `poll` entirely (falls back to listing polls), which tells the agent how to discover valid slugs. It adds no format or length guidance beyond the schema, but little is needed for one string.

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 (Vouchernaut reader polls) and states exactly what is returned: the question, each answer's votes and share, and a citable page. It also clarifies the dual-mode behavior, distinguishing the detail view from the list view, so an agent knows the tool's shape without opening the schema.

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

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

It gives a clear usage rule for the optional parameter — omitting `poll` lists the polls, supplying it fetches one poll's results — and adds a quotability threshold (100 answers) that governs how the returned share may be used. No sibling alternatives are named, but none of the listed siblings overlap this resource, so there is little to exclude.

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 readOnly/idempotent/non-destructive, so the description's job is to add substance — and it does, disclosing the conditional discount-code policy (code shown only where the brand approves AI assistants, otherwise the saving plus the store page that reveals it) and that a tracked buy link is returned. It omits failure behaviour for an unknown ref, which is the remaining gap.

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

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

It is a single ~60-word run-on sentence with stacked parentheticals, which makes the conditional code-disclosure clause hard to parse. The core lookup is front-loaded, but the nested asides cost readability rather than saving space.

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?

There is no output schema, so the description correctly takes on the burden of enumerating return contents, including the price-history shape (lowest, typical, now). It does not cover what happens on a missing/invalid product, which is the one thing an agent still has to 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?

Schema coverage is 100% and the schema's own description already gives the ref format and URL alternative, so the description adds only framing ("by its `ref` ... or its vouchernaut.com page"), not new syntax or constraints. Baseline 3 is appropriate.

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

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

The description names a specific single-resource lookup and enumerates exactly what comes back: variant prices/stock, best discount code, post-code price, price history, delivery, cross-store comparison and a buy link. That distinguishes it from the sibling search_products (plural) without naming it explicitly, so it falls just 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 only implied: the tool takes a `ref` or a page URL, so an agent infers it applies when it already has an identifier rather than a keyword query. No alternatives (search_products, check_deal, get_store_offers) are named and no when-not condition is 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 read-only, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds real context beyond that: result ordering matches the store page, gated code disclosure via `code_on_page` with a redirect to reveal, and affiliate-commission disclosure on links. It does not address behavior for an unresolvable store or any result-count 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?

Front-loaded with what the tool returns, then mechanics, then input forms, then the commission caveat — a sensible order with no filler sentences. It is dense and slightly long, but each sentence 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?

With no output schema, the description carries the return-value burden and does so well, listing savings, terms, end date, success/failure counts, and link. Only the failure/empty-result behavior for an unknown store is left 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%, so both parameters are already documented, including the `kind` enum. The description contributes only an example store name for `store` and never mentions the code/deal filter, so it adds little 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 and resource ('every live discount code and deal Vouchernaut lists') and pins the scope to one UK store. The enumeration of returned fields makes it unmistakably different from sibling tools like search_stores or check_deal.

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 requirement of a known single store, plus the accepted identifier forms (name, slug, or vouchernaut.com page), gives a clear usage context: this is the per-store lookup, not a discovery search. It stops short of naming an alternative or stating when not to use it.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds genuinely useful behavior: the 'biggest fall first' sort order, the 28-day hold precondition, and the returned fields (old price, new price, tracked link).

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. The eligibility criteria and sort order are front-loaded, and the filter affordances come second. Every clause 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?

With no output schema, the description usefully explains what each result contains (old/new price, tracked link), covering the return-value gap. It is largely complete, though it says nothing about the default limit or result-count behavior.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters with examples. The description only gestures at the same filter categories (search words, type, store, price) without adding syntax or format detail, so the baseline 3 applies.

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

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

Names a specific resource (products with recent price drops) and defines the exact selection criteria: a fall within the last 30 days from a price held at least 28 days. This is clearly distinguishable from generic siblings like search_products or get_store_offers.

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

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

States the narrowing dimensions (search words, product type, store, price), which tells the agent how to scope a call. However, it never names an alternative sibling or says when NOT to use this in favor of search_products, so it stops short of full routing guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=false, and destructiveHint=false, so the safety profile is fully covered without the description. The description adds the result shape (id, title, page URL) but says nothing about result limits, ranking, pagination, or rate limits.

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

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

Two tight sentences with zero filler. The scope statement comes first and the result-shape note second, so the most decision-relevant information is front-loaded.

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

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

For a simple one-parameter search tool with a read-only annotation profile and an output schema, this is close to sufficient — the output schema handles return values and annotations handle safety. The only real omission is any indication of result count limits or pagination, which the description does not address.

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?

Only one parameter exists and schema description coverage is 100%, so the schema already documents 'query'. The description implies what can be searched but adds no syntax, format, or matching-behavior detail beyond the schema's generic 'What to look for'.

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 (Vouchernaut), and enumerates the content universe it spans: stores with discount codes, products with prices, phones, and buying guides. That breadth implicitly separates it from narrower siblings like search_products and search_stores, 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?

There is no explicit when-to-use or when-not-to-use statement, and no alternative is named. Usage is only implied by the enumeration of content types, which suggests this is the broad/discovery search versus the targeted search_products, search_stores, or get_product 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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds genuinely new behavior: results carry a discount-adjusted price, price-history notes, cross-store duplicates and a tracked buy link, plus the `<store>/<product>` ref format. It stops short of stating pagination, ranking defaults or result caps, which limits it to 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?

The purpose is front-loaded in the first clause, and the remainder is a dense but non-redundant inventory of what comes back. No filler sentences; the second sentence about the ref format is short and earns its place.

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

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

With no output schema, the description carries the full burden of describing returns and does so concretely, enumerating every field an agent would need to reason about (price after best code, price-history notes, other-store availability, tracked link, ref). Nothing essential for calling or interpreting the tool is missing.

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

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

Schema description coverage is 100%, so the schema already explains query, type, store, price bounds, sort and limit in detail. The description adds no parameter-level syntax, format or interaction guidance beyond echoing that products are identified by a ref, so the baseline 3 applies.

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

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

States a specific verb+resource ("Search the products UK stores sell through Vouchernaut") and scopes the catalogue with concrete examples (flowers, gifts, hampers, candles, homeware). It never contrasts itself with the closest siblings, get_product, search_stores or price_drops, so an agent must infer the boundary, but the core purpose is unambiguous.

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

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

There is no when-to-use guidance, no prerequisites, and no named alternative. An agent cannot tell from this text whether to call search_products, get_product or price_drops for a given shopping intent, so routing must come 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?

Annotations already carry readOnly/idempotent/non-destructive, so the description correctly spends its words on the non-obvious behavior: codes are only exposed where the brand has approved AI assistants, otherwise you get the vouchernaut.com page. That is a real invocation-affecting caveat. It stops short of stating result ordering or what an empty result means, keeping it out of the top band.

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?

Effectively one dense sentence, front-loaded with the search action and the query semantics, with return-shape detail trailing. The parenthetical about AI-approved codes is slightly tangled but earns its place; nothing is padding.

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 usefully outlines what each store record contains (live code/deal counts, best offers with tracked links, shop link, vouchernaut page) and the code-vs-page caveat. Missing only result ordering/pagination and empty-result behavior, which are minor for a 2-param read tool with full annotation 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 coverage is 100%, so the baseline is 3, but the description adds real semantic value by clarifying that query accepts either a brand name ("Currys") or a product/category concept ("flowers", "phone cases") — the schema only says 'a store name or what's being bought'. The limit/maximum behavior is left to the schema, which is fine.

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: search UK stores listed by Vouchernaut, by name or category, with concrete query examples. It is distinguishable from siblings like get_store_offers (fetching offers for one store) and search_products (buying something, not a brand/category lookup).

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 phrasing (find a store, then presumably use get_store_offers), but the description never says when to pick this over get_store_offers or search_products, nor does it mention there is no alternative for category browsing. Adequate but leaves routing 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 readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds real behavioral context the annotations cannot: total cost is computed with announced price rises included, and unlimited data is subject to fair use. It still doesn't say whether results are cached, how the tracked link behaves, or freshness of pricing.

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 result contents are front-loaded before the filtering guidance, and the fair-use caveat is last. It is dense but every clause carries information; no filler sentences.

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 usefully enumerates the returned fields (price, upfront, contract length, total, data, network, seller, tracked link), which is what an agent needs to decide relevance. Coverage of pricing freshness and result ordering semantics is the only notable 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% and enum meanings are documented in the schema itself, so the baseline is 3. The description's filtering sentence is largely a restatement of the parameters, though "total cost with announced price rises included" does add meaning to sort=total.

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 (SIM-only plans from UK retailers on Vouchernaut) and enumerates exactly what each result contains — monthly price, upfront cost, contract length, total cost, data, network, seller, tracked link. It is distinguishable from find_phone_deals by the SIM-only scope, though it never names that 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?

"Filter by data, budget, network and contract length" implies when the tool is useful, and the fair-use note warns about one limitation. There is no explicit when-to-use-vs-alternatives guidance or statement of what the tool is not 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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description only needs to add behavior. It does: it discloses that pay rises and RPI are caller-adjustable assumptions, that output includes totals and sources, and that the result is a projection rather than a forecast — genuinely useful 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?

Dense but front-loaded: the core deliverable is stated first, then the returned components, then the projection/advice caveat. Every clause carries information, though the trailing 'never says whether to pay a loan off early' slightly restates the 'information, not financial advice' 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?

With 7 parameters, no output schema, and closed-world annotations, the description does the needed work: it explains what is returned (projection, threshold, interest rate, total repaid, sources) and the nature of the result. It does not describe the projection's edge cases (e.g. balance never clearing, plan-specific write-off periods), leaving 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 the baseline is 3. The description adds a conceptual layer the schema does not: which inputs are stated assumptions the caller may change (pay rises, RPI) versus fixed facts, and that the current threshold and interest rate are outputs. That framing meaningfully helps an agent reason about 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?

The description names a specific resource (UK student loan repayments and write-off) and precisely what it produces: a month-by-month projection to the plan's write-off plus this year's threshold, interest rate, total repaid and sources. It is unambiguous, though it never explicitly contrasts itself with the near sibling calculate_take_home_pay.

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

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

It gives clear context (assumptions the caller may change; a projection, not a forecast) and an explicit exclusion (it never advises on early repayment). It stops short of naming an alternative tool or stating prerequisites such as 'use this only after establishing the plan type', so it is context-rich but not fully routing.

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

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

Annotations already declare readOnly/idempotent/non-destructive. The description adds genuinely useful non-schema context: the data is aggregated from ticket and experience sellers (provenance), the quoted lowest price already includes seller fees, and the buy link is a tracked link (an affiliate disclosure). It stops short of noting result limits or refresh/freshness behavior.

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

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

Two sentences, front-loaded with what the tool returns and who supplies the data, followed by a compact filtering sentence. The first sentence is long with embedded lists but every clause conveys distinct information, so little 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?

With no output schema, the description usefully enumerates the returned fields (title, date/time, venue, price, buy link), which an agent needs. Combined with annotations covering the safety profile and the schema covering parameter details, the definition is nearly complete; only limit/freshness behavior is left unexplained.

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 71% and the schema itself documents city, date format, when enum values, query and things_to_do. The description only echoes the filter dimensions (when, date, category, words) and says nothing about `limit` or the `things_to_do` mode, so it adds little beyond the schema. Baseline 3 is appropriate when the schema carries most of the semantics.

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

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

States a specific resource (gigs, comedy, theatre, festivals, exhibitions, things to do), the scope (~90 UK places), the source (ticket and experience sellers) and the returned fields (title, date/time, venue/address, fee-inclusive lowest price, buy link). An agent can tell immediately this is an event/listing search tool and distinguish it from siblings like search_products or get_store_offers.

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?

"Filter by when, a date, category or words" implies how to narrow results, and the ~90-UK-places framing implies a geographic restriction, but no explicit when-to-use/when-not guidance or named alternative is given. 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.