Whoppah

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), but the description adds behavior those flags cannot express: results are limited to listings currently buyable or biddable, and not_found means sold/expired/withdrawn rather than non-existent. That freshness constraint and error semantics materially change how an agent should interpret 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?

Four sentences, none of them filler, and the most important content (what comes back, where the id comes from) is front-loaded. It is denser than needed in the field enumeration, which partially duplicates the output schema, but it remains readable and purposeful.

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?

Given two optional identifier params, a rich output schema, and annotations covering the safety profile, the description supplies exactly the missing pieces: value provenance, freshness of results, and recovery on not_found. An agent has everything needed to select and call this 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 description coverage is 0% and neither id nor slug is documented in the schema, so the description carries the burden. It does this well by naming the source of the values (from search_catalog) and treating id and slug as interchangeable identifiers, but it does not state that both are optional, that they are mutually exclusive, or what happens if both are supplied.

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 ('Get the full public details of one listing') and enumerates the returned fields (description, price in EUR, condition, brand/designer, dimensions, materials, photos, seller, link). It is clearly distinguishable from search_catalog (broad listing retrieval) and similar_items (comparable pieces), so an agent can route correctly without opening sibling 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?

Explicitly says to pass the id/slug originating from search_catalog and to check an item here before recommending a specific piece, which is direct when-to-use guidance. It also handles the failure branch by naming alternatives (search_catalog, similar_items on a comparable listing) rather than leaving the agent to guess.

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 bar is lower. The description still adds genuine behavioral context beyond them: it discloses the return contents and a hard boundary ("Never returns contact details"), plus why contact is out of scope.

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: what it returns, when to use it, and a boundary. Purpose is front-loaded and there is no filler.

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

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

An output schema exists, so return values need not be re-explained, and the description nonetheless previews them. Combined with explicit usage context and a contact-details boundary, 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 0% and the description never explains the seller_id argument (format, source, or how to obtain it). With only one self-evident parameter, the gap is minor, but the description adds no meaning beyond the schema here.

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 ("Public profile of a Whoppah seller") and enumerates the exact fields returned (display name, seller type, biography, expert-seller status, review score with excerpts). No sibling tool touches seller data, so an agent can route unambiguously.

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 an explicit trigger: "Use it when the buyer asks whether a seller can be trusted." It does not name alternatives or exclusions, but no sibling overlaps the seller-trust use case, so the guidance is sufficient without them.

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, and destructiveHint=false, so the safety profile is fully covered. The description adds purpose context (grounding, spelling) but says nothing about pagination behavior, result limits, or what happens when a query matches nothing. That is adequate but not rich given the annotations carry the safety burden.

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, and the core purpose is front-loaded before the parameter guidance. Every clause earns its place.

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

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

With an output schema present, return values need no explanation, and the description covers the tool's purpose and its two semantically meaningful parameters. Pagination semantics for page/limit are the only notable gap for an otherwise simple lookup 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 0%, so the description must compensate. It does supply the key domain values for 'kind' (brand or designer) that the schema lacks as an enum, and notes that 'query' is optional. It says nothing about 'page' or 'limit', leaving half the parameters to inference, so it only partially compensates.

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: 'Look up Whoppah's brand and designer index.' An agent immediately knows this returns brand/designer entities rather than items or sellers. It does not name or contrast with any sibling tool, so it falls 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?

Gives concrete reasons to use it: spell names correctly, ground answers, build precise search filters. This is clear context for when the tool is appropriate. However, no when-not guidance or explicit alternative (e.g., list_categories or search_catalog) is offered.

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, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds only that the result contains slugs and titles; it says nothing about pagination, total counts, or ordering, so it adds modest value on top of 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?

A single front-loaded sentence with the purpose and the follow-on use case, with no redundant restatement of the title or annotations.

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-shape explanation is not required, and the description still sketches the payload (slugs and titles). The only material gap is paging behavior for a list endpoint, which an agent may need in order to retrieve all categories thoroughly.

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?

There are two parameters (page, limit) with 0% schema description coverage, so the description carries the full burden of explaining them and does not mention them at all. Their defaults (1 and 50) are visible in the schema but the paging semantics for a category listing are left to inference.

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 the marketplace categories') and even names the returned fields (slugs and titles). It also names the sibling search_catalog, so an agent can distinguish it from get_item, list_brands_designers, and the other siblings without opening a 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 phrase 'to build precise search_catalog filters' gives a clear when-to-use condition and points at the downstream alternative. It stops short of explicit exclusions (e.g., when you already know the slug, or use list_brands_designers instead), so it is clear context rather than 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, idempotentHint and openWorldHint=false, so safety is covered. The description adds genuinely useful behavior beyond that: only currently buyable/biddable listings appear, sold/reserved/expired are excluded, each item carries a whoppah.com link, and payment occurs off-tool on whoppah.com.

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 single paragraph is dense and front-loaded: catalogue identity first, then usage trigger, then filter mechanics, then availability/freshness, then the buyer-facing link. No sentence 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 an output schema present, return shape need not be explained, and annotations cover the safety profile. The description supplies everything else an agent needs to call this correctly: usage trigger, filter strategy, freshness guarantee, and the critical post-call instruction to hand the buyer the whoppah.com link.

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% across 13 parameters, so the description must carry the load, and it names most filter dimensions (category, brand, designer, price range in EUR, condition, colour, material, seller country) plus the free-text query concept. It leaves page, sort and limit undocumented, including valid sort values or pagination behavior, so it is strong but not complete.

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 Whoppah's live catalogue') and scopes the domain concretely (furniture, lighting, art, decor, designer bags). It is distinguishable from siblings like get_item and similar_items without opening any 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?

'Use it whenever someone wants to find, compare or buy a design piece' gives a clear trigger condition and the description explains how to combine free-text with filters plus facet counts. It does not, however, name alternatives or exclusions (e.g. when to prefer get_item, list_categories or list_brands_designers for browsing facets).

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, destructiveHint=false and a closed-world hint, so the safety profile is covered. The description adds useful non-structured context that these are exactly the checkout prices on whoppah.com, but says nothing about pricing volatility, geographic limits, or what happens when no shipping is available.

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

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

Two tight sentences with the resource and the invocation details front-loaded, and no filler. The example country code is compact and directly actionable.

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 values need not be spelled out, and the description tellingly enumerates the option types (courier, parcel, pickup). The only real gap is the unmentioned optional postal_code argument, which is minor for a quote 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 description coverage is 0%, so the description must carry the load. It clarifies product_id and country with a format example ('de'), which is genuinely useful, but it entirely omits postal_code, one of three parameters, leaving that argument undocumented.

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 resource and scope: shipping options and prices for one listing to the buyer's country, including the carrier formats (courier, parcel, pickup). It is clearly distinct from siblings like get_item or search_catalog, though it never explicitly names an alternative.

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 the concrete invocation recipe (product id plus a country code with a lowercase example) and ties the result to what checkout shows on whoppah.com. However, it offers no when/when-not guidance relative to the other retrieval tools, so usage is only implied.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds that similarity is based on how listings 'look and read,' but omits any behavioral detail like how many results are returned or how the default limit behaves. With annotations carrying the safety burden, this is adequate but thin.

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, purpose front-loaded and the argument-source hint following. Appropriately sized for the tool's simplicity, though not maximally economical given the unexplained limit parameter.

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 values need not be explained. For a 2-parameter read-only tool the description covers purpose, use case, and argument provenance; the only real gap is the undocumented limit parameter, which the schema also leaves undescribed.

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%, so the description must compensate. It explains where product_id comes from (search_catalog or get_item), which adds real value for that parameter, but the 'limit' parameter (default 8) is left entirely unexplained in both schema and description.

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: 'find listings that look and read like a given one.' The phrase 'look and read like' distinguishes it from search_catalog (query-based) and get_item (single fetch), giving the agent a clear sense of what makes this tool unique.

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 use case ('to offer alternatives or comparisons') and tells the agent where the argument comes from ('a product id from search_catalog or get_item'), which is genuinely helpful. However, it offers no explicit when-not guidance or comparison against siblings like search_catalog.

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