ALLR Motorcycle Gear Prices

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is fully covered. The description adds useful result semantics (what is returned: landed price, percent off, retailer, product URL) and the retailer-board ranking rule, but says nothing about pagination, empty-result behavior, or cost of a broad query without filters.

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, roughly 55 words, front-loaded with the core action and the board distinction before the return-value summary. The mode explanation partly restates the schema's mode description, a small redundancy, but the rest is dense 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?

For an 8-parameter, zero-required list tool with a full output schema and rich annotations, the description supplies purpose, mode semantics, ranking, and return fields. The remaining gap is sibling differentiation from search_gear and get_product_offers, which an agent would need to pick this tool confidently.

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%, including the landed-cost composition for country and the category/subcategory dependency, so the schema already carries the parameter burden. The description reinforces the mode parameter's two boards and adds the ranking rule for retailer mode, but contributes nothing new about size, limit, min_discount_pct, or retailer filtering.

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?

"List motorcycle gear currently discounted on ALLR" gives a specific verb and resource, and the two-board framing (default MSRP board vs mode='retailer') narrows the scope further. It never names the siblings it competes with (search_gear, get_product_offers), so an agent must infer the boundary from the catalog rather than from the text.

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 clearly routes between the two internal modes: default MSRP board for below-list pricing versus mode='retailer' for store-cut prices ranked by that store's percentage. That is genuine when-to-use guidance, but it stops at intra-tool selection and offers no exclusion or alternative for general gear searching or per-product offer lookup, which the sibling tools cover.

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

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

Annotations only cover the safety profile (readOnly, idempotent, non-destructive), and the description adds substantial behavior the agent could not infer: landed cost is item + shipping + duty + brokerage with tax excluded, results are sorted cheapest-landed-first and capped by limit with offer_count showing the total, and non-shipping retailers are still listed but flagged and sorted last. It also discloses the per-colorway availability model and the error behavior for an unmatched colorway.

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

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

Front-loaded with the core purpose, and the tax-exclusion and sorting rules appear early where an agent will read them. The prose is dense to the point of being a single wall of clauses, and the repeated re-explanation of landed-cost components in the country param is redundant, but no sentence is throwaway.

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 covers return shape, and the description supplies everything else an agent needs for a 6-parameter read tool: cost composition, sort order, pagination signals, out-of-market handling, and the colorway/size matching model. Nothing material is left to inference.

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 still earns credit by explaining the data model behind the parameters — that availability is per (retailer x colorway x size), that there is deliberately no offer-level size list, and that offers lacking a per-colorway breakdown are dropped rather than guessed at. It mostly restates limit and country semantics already in the schema, which keeps it off a 5.

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

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

States a specific verb and resource ("Get the full per-retailer offer table for ONE ALLR product in a buyer country") and immediately scopes it against a named sibling: "search_gear only carries the single lowest number." An agent can tell exactly what this returns versus a search result 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?

The alternative is named explicitly (search_gear for the single lowest price, this tool for the full per-retailer breakdown), and the product_id schema hints at the search_gear workflow. What's missing is an explicit "when not to use" statement, e.g. don't call this for browsing or for products not yet resolved to an id.

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

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

Annotations already cover the safety profile (readOnly, idempotent, closed-world), so the description is free to spend itself on behaviour an agent cannot infer: it uses the same charts and the same matcher as the ALLR product page, and it explicitly refuses to guess when a chart or measurement is missing. That refusal behaviour is the single most important thing to know before calling it.

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

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

A single dense paragraph that front-loads the core action and scope before moving to units, return values, and the failure mode — every sentence carries information. The unit/category mapping slightly duplicates the schema descriptions, which is the only wasted motion.

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

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

With an output schema present the description need not enumerate return fields, yet it usefully sketches them (label, EU/US/UK equivalents, snugness, chart link). For a tool with 8 optional parameters and no required ones, it makes the mutual requirement explicit. The only gap is telling the agent how to obtain a product_id when it has none.

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 each measurement, its unit, and the product_id/brand+category dependency. The description restates the centimetre convention and the category-to-measurement mapping, which is useful reinforcement but adds little beyond the structured fields; 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?

Specific verb (recommend) plus resource (a size) and precise scope (from body measurements, for a specific product or brand+category, using the manufacturer's own published chart). It is clearly distinguishable from siblings like search_gear or get_product_offers, which locate products rather than translate measurements into sizes.

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 two entry paths (product_id, or brand + category) and the fallback to known_size when no measurement is given, and it sets expectations for the failure case. What it lacks is routing guidance to siblings — e.g. telling the agent to call search_gear first when it only has a product name and no id.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety bar is covered. The description adds genuine context beyond them: 'cheap and static — it reads bundled catalog metadata, not the live price data,' which tells the agent about cost and staleness of results.

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

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

Two tight sentences with no filler. The purpose and the downstream filter contract are front-loaded, and the cost/staleness note trails as supporting context.

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 small static lookup with an output schema and full annotation coverage, nothing material is missing. Purpose, consumer contract, data source and cost profile are all stated, and return structure is delegated to the output schema as expected.

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 in-schema (case-insensitive brand substring match, include_brands default and list size), so the baseline applies. The description adds no parameter-level meaning beyond the schema — its extra detail is about output slugs, not inputs.

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

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

States a specific verb and resource (list catalog categories and brands) and immediately ties the output to the exact slugs used by the `category` and `brand` filters on search_gear and get_deals. That contrasts it clearly with the sibling tools it exists to support.

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?

Strongly implies the when: 'These are the only values the `category` and `brand` filters accept' tells an agent it must consult this before filtering on those siblings. It stops short of an explicit 'call this first' instruction or any when-not-to-use case, so it is clear context rather than a full routing rule.

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

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

Beyond the readOnly/idempotent/non-destructive annotations, it discloses that `lowest_landed_price` is a total including shipping, import duty and customs brokerage but excluding destination VAT, and that landed cost is computed for only four markets. It also flags the non-obvious behavior that products whose certification ALLR cannot derive are silently excluded by the certification filter.

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

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

Front-loaded with the search scope and immediately followed by what the results contain, which is the right ordering. It loses a little economy by restating twice that get_product_offers holds the per-retailer breakdown.

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

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

With an output schema present, the description need not enumerate return fields, and it still highlights the key ones (`id`, `lowest_landed_price`, retailer count, URL). Given rich annotations and full schema coverage, nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100%, so all ten parameters are already documented in structured form and the baseline is 3. The description reinforces the meaning of `country` and the landed-price fields but adds little parameter-level detail the schema does not already carry.

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 (search ALLR's motorcycle-gear catalog) and enumerates the covered product categories, so the agent knows the scope precisely. It also explicitly separates its role from get_product_offers by saying the returned `id` feeds that tool's per-retailer price table.

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 routing to get_product_offers for per-retailer breakdowns and to list_categories_and_brands (in the schema) for slugs gives clear context for choosing among siblings. It stops short of explicit when-not-to-use guidance, e.g. whether to query get_deals instead when hunting for discounts.

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