Shortlist Price Index

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

With no annotations, the description carries the full burden, and it does disclose the return contents plus two important post-call rules: buyUrl is the canonical outbound link and the citation string must be cited. It does not address data freshness guarantees, currency of 'entry prices', or failure modes, which keeps it below a 5.

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

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

Three tight sentences, front-loaded with what the tool returns, followed by the usage example and the link/citation contract. No filler, and every sentence earns its place.

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

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

There is no output schema, so the description correctly spells out the returned fields (prices, ratings, best-for notes, comparison link) and the required buyUrl/citation handling. It omits any note on how 'cheapest' is ranked or whether results can be empty, leaving minor gaps for a recommendation tool.

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

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

Schema coverage is 100%, so the schema already documents both top_n and category, including the default and min/max. The description only echoes 'the N cheapest' and 'in a category' without adding format or selection nuance, so the baseline 3 applies.

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

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

States a specific verb and resource ('Get the N cheapest providers in a category') and enumerates what comes back: entry prices, ratings, best-for notes, and a comparison link. The scope is unmistakable, though it never names its siblings (get_price_index, get_true_3yr_cost, list_categories) to sharpen the distinction.

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

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

'Ideal for quick recommendations like "cheapest password manager right now"' gives a concrete use context that tells an agent when this tool fits. It also prescribes downstream behavior (use buyUrl, cite the citation string). It stops short of stating when-not to use it or which sibling to prefer for cost-over-time or index queries.

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

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

With no annotations, the description carries the full burden and does a reasonable job: it discloses result ordering ('sorted cheapest first'), the fields each provider carries, that history and methodology are included, and an operational rule (use buyUrl as the canonical stable outbound link, cite the citation string). It does not cover freshness/update cadence, rate limits, or whether history is complete vs. truncated, leaving some gaps for a no-annotation tool.

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

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

Three sentences, front-loaded with the return contents, then usage examples, then the linking/citation rule. Every sentence carries information; the enumeration of returned fields is dense but justified for a tool with no output schema. Minor redundancy in the two example questions.

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 must describe the return shape — and it does, listing the aggregate stats, the per-provider fields and their sort order, plus history and methodology. Combined with the usage and citation guidance, an agent has everything needed to call it and interpret the response correctly.

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

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

Schema description coverage is 100% and the single enum parameter is already documented in the schema, including the pointer to list_categories. The description only restates 'one category' without adding slug syntax, formatting, or fallback behavior, so it adds essentially nothing beyond the structured field. Baseline 3 is appropriate.

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

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

States a specific verb and resource ('Get the full current price index for one category') and enumerates the payload contents: average, median, cheapest entry price, per-provider price/rating/best-for, monthly history and methodology. An agent can distinguish it from get_cheapest and get_true_3yr_cost because the description makes clear this returns the complete index for a whole category rather than a single derived figure.

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 concrete usage framing with worked examples ('what does a VPN cost per month', 'compare cloud backup prices') plus downstream guidance on using buyUrl and citing the citation string. It stops short of naming when NOT to use it or pointing to get_cheapest / get_true_3yr_cost as alternatives for narrower questions.

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

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

With no annotations, the description carries the full behavioral burden and does so thoroughly: it discloses what is returned (renewal multiplier, category average), the exclusion rule (no renewal price => excluded, never guessed), category coverage limits, and even downstream guidance (use buyUrl, cite the citation string). This is unusually rich for a read tool.

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

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

The core definition and ranking logic are front-loaded, followed by coverage limits and output conventions. It is long (seven-ish sentences) but nearly every sentence adds decision-relevant information; slight trimming of the examples would tighten it without loss.

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 must describe the return shape, and it does: 3-year totals, renewal multiplier, category average, buyUrl, and citation string. Combined with the category coverage caveat, an agent has everything needed to call and interpret the tool correctly.

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

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

Schema coverage is 100% and the single enum parameter is documented, so the baseline is 3. The description adds real meaning beyond the schema by revealing that only web-hosting and antivirus currently return data and that other enum values return a note, which the schema does not convey.

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 computation (3-year cost per provider) with the exact formula: year 1 at intro price, years 2-3 at renewal price, ranked by total. It also implicitly distinguishes itself from get_cheapest by noting 'the cheapest intro is rarely the cheapest over three years', so an agent can tell the two apart without opening schemas.

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

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

Gives explicit when-to-use contexts ('what does hosting really cost long-term', 'which antivirus is cheapest over 3 years') and a when-not boundary (other categories return a note; providers without published renewal prices are excluded). It does not name sibling tools as alternatives, but the usage conditions are clear and unambiguous.

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

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

With no annotations, the description carries the burden and does disclose return content: current categories only, currency split (USD for US/global, EUR for Dutch), and the latest-update date per category. It omits pagination, auth or rate-limit behavior, but for a zero-parameter read-only listing this is solid 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?

One sentence, front-loaded with the verb and resource, with the currency scope and downstream slug usage appended. It is dense but every clause carries information; the parenthetical is slightly wordy but not wasteful.

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?

No output schema exists, so the description must explain returns, and it does: category list, currency scope, latest-update dates, and slug format for reuse. An agent has everything needed to call it and chain into the sibling tools.

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

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

The tool takes no parameters, so there is nothing to disambiguate and the baseline is 4. The description correctly adds no spurious parameter guidance.

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

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

States a specific verb ('List') and a precisely scoped resource ('software price categories of the Shortlist Price Index that are current'), and clarifies what a category means (entry prices, lowest paid plan per provider). An agent can distinguish this from the sibling get_* tools that consume the slugs it returns.

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 final sentence tells the agent this is the entry point whose slugs feed get_price_index, get_cheapest and get_true_3yr_cost, which is clear usage context. It does not state when NOT to use it or what prerequisite conditions apply, so it stops short of full when/when-not guidance.

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