Swervie

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

Beyond the readOnlyHint/openWorldHint annotations, the description discloses non-obvious behavior: deduplication of seller listings, hard-filter exclusion semantics for missing attributes, soft-preference ranking that never excludes rows, price filters applying to the live offer price in cents, and that responses carrying buy_url also include a commission disclosure field. These are exactly the traits an agent could not infer from structured fields.

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

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

One dense paragraph, front-loaded with the core purpose, then return shape, then filter/preference semantics, then sort and price-filter clarification. Every sentence adds information and none repeats the schema or title.

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

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

With no output schema, the description steps up by enumerating returned row fields (price, price_band, buy_url, buy_seller, image_url, ratings, spec values, card_specs, disclosure), which is what an agent needs to interpret results. The main gap is pagination behavior for `cursor`/`limit`, which is unaddressed for a browse tool that can return up to 50 rows.

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 only 29%, so the description must carry weight and it does: it explains the sort enum values, the hard-semantics of `filters` (including Price dimension min/max in cents), and the soft semantics of `preferences` with worked examples. It leaves `limit`, `cursor` (pagination) and `user_signature` unaddressed in prose, so it is not fully compensating.

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 opening sentence gives a specific verb and resource ('return a category's consolidated, ranked shelf') plus the key differentiator: one row per product with duplicate seller listings collapsed. That dedup/ranking behavior separates it implicitly from search_products and get_products, though no sibling is named explicitly, which keeps it below a 5.

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

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

It clearly frames when to use filters versus preferences ('Filters are hard... Preferences are soft... none are excluded'), with concrete examples (Rated Noise prefer low, pet-hair rating prefer high). That is solid usage context, but there is no explicit exclusion or routing guidance against sibling tools like find_category or search_products.

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 and openWorldHint, so the safety profile is covered. The description adds real value beyond that by disclosing the return payload in detail: filterable specifications with type, units, allowed values and importance, plus budget/mid/premium price bands. It stops short of noting open-world matching behavior or what happens when no category matches.

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; the purpose comes first and the payload detail follows. It is dense but every clause carries information an agent needs.

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

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

With no output schema, the description correctly takes on the burden of describing return values and does so thoroughly. The main gap is routing context relative to siblings (browse_category, search_products) and no-match behavior for an open-world lookup.

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 50%: user_signature is well documented in-schema, but query only carries minLength=2. The description supplies the missing meaning — query is a natural-language shopping intent rather than an exact category name — which is the key semantic an agent needs. It says nothing about the personalization effect of user_signature, but that is already covered by 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: map a shopping intent to a Swervie product category and return its filter contract. The 'matches a shopping intent' phrasing sets it apart from a plain category lookup, though it never names or distinguishes browse_category or search_products directly.

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

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

Usage is only implied by 'matches a shopping intent' — an agent can infer it is the discovery step before search_products/get_products. No explicit when-to-use, when-not-to-use, or alternative tool (browse_category) is named, and the failure case (no matching category) is unaddressed.

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 read-only and open-world, and the description adds real behavior beyond them: group/shelf row ids are silently substituted with the row's top_pick_id, substitutions are surfaced in resolved_groups, and any response with buy_url carries a commission disclosure field. It stops short of stating error handling for unresolvable ids or missing items.

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 verb and scope, then layered with resolution and disclosure rules — no filler sentences. The long compound final sentence is dense but each clause carries distinct 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?

There is no output schema, and the description compensates by describing the returned sections, the standard spec ordering, provenance, and the disclosure field. Gaps remain around failure modes for invalid or unresolvable ids and whether fewer than requested items can come back.

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

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

With 50% schema coverage and no description on 'ids', the description carries the load by explaining that ids accepts both product ids and shelf row ids and how group rows resolve. It gives no guidance on ordering, duplicates, or partial-failure behavior, and does not touch user_signature (which the schema documents).

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 plus scope ('Full detail for up to 25 products') and enumerates the returned sections (specs, ratings, offers, provenance). It is unmistakably a bulk detail fetch, though it never names lookup_product or search_products to say how it differs.

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 through the id-resolution rules and the 25-item cap, but there is no explicit statement of when to prefer this over lookup_product or search_products, nor any prerequisites or exclusions. The agent must infer the batch-detail use case.

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 and openWorldHint, but the description adds substantial behavior beyond them: it explains match outcomes ('exact', 'likely', 'ambiguous', 'none'), what each means for the response, that misses are recorded as demand, that products[0] carries full detail, that shelf_context includes rank, variants and alternatives, and that products lacking live price/image are flagged under readiness. It also discloses the commission disclosure field for buy_url links.

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

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

The description is a single dense paragraph that front-loads the core lookup behavior and then explains outcomes. Every sentence carries useful information, though the density and length keep it from being maximally crisp.

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 explaining return behavior and does so thoroughly: match statuses and their meanings, the structure of products[0], shelf_context contents, readiness flags for stale price/image, and the commission disclosure field. An agent has enough information to 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 high (80%), so the schema already documents most parameters. The description adds useful examples for query and identifier modes and clarifies brand/model resolution, but it does not add much parameter-specific meaning beyond what the schema provides.

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

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

The description uses a specific verb and resource ('Look up one specific product') and enumerates exactly which identifier forms it accepts (product name, ASIN, UPC/EAN/GTIN, brand plus model). This makes clear it is the precise single-item lookup tool, distinguishable from broader siblings like search_products or get_products.

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 establishes the usage context clearly: use it when you have a specific product in mind and can supply a name, identifier, or brand/model. It does not explicitly name alternatives or exclusions, so it falls short of the full when/when-not/alternatives standard, but the context is clear.

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 flag readOnlyHint=false, idempotentHint=false, and destructiveHint=false; the description adds real value beyond them by disclosing append-only semantics ('appends one event per product id') and mutation scope ('changes nothing else'). This clarifies repeat-call behavior and blast radius, which the annotations alone cannot express.

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

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

Three tight sentences with no filler, leading with the action and following with the payoff. The append/scope sentence earns its place as the highest-value 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?

Mutation semantics and non-idempotency are adequately covered given the annotations, and no output schema means no return-value burden. However, with every parameter undocumented in the schema and 'category' plus the singular/plural id distinction unexplained, an agent cannot reliably construct a call from this definition alone.

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

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

Schema description coverage is 0% for 5 parameters, so the description must carry the load. It hints at product id/addressing ('one event per product id') and user_signature ('returning user_signature'), but leaves 'category' entirely undefined and never clarifies the product_id vs product_ids (max 25) relationship or the valid 'action' values beyond the words 'considered or chose'.

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: 'Record which product the user considered or chose.' The recording semantics clearly distinguish it from read-oriented siblings like get_products, lookup_product, and search_products, though it never names an alternative 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?

Gives a rationale for calling it ('Selections improve future ranking, especially for a returning user_signature') but no explicit when-to-use/when-not guidance or routing to siblings such as submit_feedback. Usage is implied rather than directed.

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

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

Goes well past the readOnlyHint/openWorldHint annotations: explains that weak/none results return no rows and instead queue demand (queued_for_creation / queued_product_request), that soft preferences exclude nothing and surface as preference_boost, and that buy_url responses carry a commission disclosure. Also discloses the interpretation envelope (method, fit_note, match_quality, unparsed_tokens) that governs result trust.

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 query-shape examples are front-loaded and earn their place, but the rest is a single dense paragraph that mixes result-structure documentation, match_quality semantics, and side-effect disclosure with no structure. Much of the return-shape detail is usable but would read far better as separate sentences or bullets.

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 and does so: it specifies products[0] holding all seller offers, shelf_context, interpretation fields, card_specs, and the disclosure field. An agent can predict both success and no-result responses from this text alone.

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 only 20%, and the description compensates strongly for `query` by describing its accepted shapes and how constraints vs. wishes are parsed. It says nothing about `sort`, `limit`, `cursor`, or pagination behavior, leaving three of five parameters to a bare 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 ('Answer one free-text shopping query') and immediately enumerates the query shapes it handles (single product, 'A vs B' comparison, category-with-constraints), each with concrete examples. The product/comparison/category branch descriptions implicitly separate it from lookup_product and browse_category without needing to open either schema.

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

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

Usage is clearly implied by query shape: name one product -> mode 'product'; 'A vs B' -> mode 'comparison'; otherwise category resolution with hard filters and soft preferences. It never explicitly says when to prefer a sibling (e.g. browse_category for navigation or lookup_product for a known SKU), so no true exclusions are given.

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

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

Annotations already declare non-read-only, non-idempotent, non-destructive, open-world, so the description's added value is the operational detail: 2000-character cap with hard rejection rather than truncation, and the one-issue-per-call constraint. It does not say what the caller receives back (ticket id, confirmation) or any rate limit, so it stops short of full transparency.

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 purpose, then the enumerated examples, then the hard constraints. The length limit and rejection behavior arrive before the agent starts composing, and nothing is redundant with the schema.

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

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

For a 7-parameter mutation tool with no output schema, the description covers purpose, scoping, and the key failure mode (oversize rejection). The remaining gap is post-submission behavior — whether a ticket id is returned and what follow-up is possible — which an agent would reasonably want to know.

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 already documents kind, tool, query, category, and user_signature in detail. The description only reinforces the feedback length limit and that product_ids/category optionally scope the issue, adding little semantic value 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 ('Report a problem or observation') and resource ('Swervie results') and names the destination (human review). The enumerated issue types (wrong specs, stale price, bad category match, unmerged duplicates, missing product, off ranking) make it unmistakable against the read-oriented siblings like search_products or lookup_product.

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?

Clearly establishes the triggering condition: something about a returned result looks wrong and needs human review. 'Each call holds one issue' implicitly steers the agent to file multiple calls rather than bundling, but no explicit exclusions or named alternatives (e.g., when to re-query instead of reporting) are given.

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