AirShelf Catalog

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

The description reveals important behaviors beyond the readOnlyHint: slug normalization with examples, the branch on commercial_data.actionable before using price/stock, staleness handling, and not_found response with did_you_mean. This gives the agent actionable behavioral context.

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 dense but efficient: it leads with the primary purpose, then covers slug acceptance, output shape, actionability, error behavior, and security bonus in focused sentences. 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?

Given an output schema exists and annotations already declare read-only, the description still meaningfully covers the remaining context an agent needs: slug format rules, pricing/staleness caveats, not_found behavior, and provenance semantics. It is arguably complete for correct invocation and result use.

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 schema already covers both parameters at 100%, so baseline is 3. The description adds value by explaining slug case-insensitivity and dash-tolerance with concrete examples, plus the provenance behavior, which enriches the parametric meaning beyond the raw 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 opens with a specific action and scope: "Compare 2-10 catalog products side-by-side on their datasheet specs." This clearly identifies the tool as a multi-product comparison and distinguishes it from siblings like get_product and explain_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?

It gives clear context by stating slugs come from search_catalog and that the tool handles 2-10 products. It stops short of explicitly saying when not to use this tool versus alternatives, such as when a single product comparison is needed.

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 and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral detail beyond annotations: it discloses that processing stages are returned only 'when available' while the golden-record field summary is always returned, setting accurate expectations about conditional output.

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 with no filler. The core purpose is front-loaded, and the second sentence efficiently explains return behavior and guarantees. Every word 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 a single-parameter read-only tool with a full output schema, the description is complete. It explains what the tool does, what it returns, and the conditional nature of part of that return, leaving no critical gap for an agent 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% and the single parameter 'slug' is documented as a 'Composite slug to explain.' The description does not add further detail about slug format or construction, but with full schema coverage, the baseline of 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 states a specific verb ('explain') and resource ('evidence behind a catalog row'), and clarifies the unique value proposition: stored processing stages plus a golden-record field summary with source coverage. This clearly distinguishes it from siblings like get_product, which would return product data rather than provenance.

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 implies when to use the tool: when you need the evidence or provenance behind a catalog record. However, it does not explicitly state when not to use it or name alternatives among the sibling tools, so the agent must infer the appropriate context.

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?

Even with readOnlyHint and openWorldHint annotations, the description discloses additional behaviors: it prioritizes catalog over live discovery, explains statuses (top-level and per-candidate), clarifies that the list is a sample, and defines 'available' relative to market. It also describes cache scoping and the meaning of statuses like 'unavailable'. No contradiction with 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?

The description is organized with bullet points and front-loads the core purpose. Every sentence adds value, distinguishing behavior, outcomes, and statuses. No redundancy or 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?

Given the tool's complexity (multiple statuses, fallback behavior, cache scoping), the description fully covers operational details: explains catalog-first strategy, live discovery fallback, result fields, and failure modes. The output schema likely covers return structure, but the description adds necessary context.

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?

Despite 100% schema coverage, the description adds meaningful semantics: it explains how `market` biases discovery and scopes cache, and clarifies that availability is not a stock guarantee. It also elaborates on `need` with examples and the max of 3 candidates (implied). This goes beyond the schema's field descriptions.

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 states this tool 'List ALL candidates' and explicitly differentiates it from siblings: it is the 'quick candidate-list tool' while research_shopping is a 'full job' and search_catalog handles specific brand+model. The verb 'list' and resource 'candidates' are specific and 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?

The description provides explicit guidance on when to use this tool versus alternatives: it is for natural-language needs, checks the catalog first, and only falls back to live discovery if necessary. It also directs users to search_catalog for specific models and to research_shopping for deeper research.

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?

The annotations already indicate read-only and non-destructive behavior, but the description adds substantial behavioral context: older observations are withheld from latestPrice, null price is expected for quote-gated B2B, and related product relations have direction/source quote semantics. No contradiction with annotations exists.

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 long but front-loaded with the core action and then spends each section on important operational nuances: provenance, pricing branching, quote-gated expectations, and the related_products relation semantics. A few return-value details are likely redundant with the output schema, but the structure is organized 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?

The description covers the input contract, the distinguished product record, the price-related caveats, the intended handling of B2B quote null pricing, and the meaning of related product relations. For a one-parameter tool, this leaves little ambiguity about how it operates and what the returned data represents.

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 schema already documents slug with an example, so the baseline is 3. The description adds the slug convention ('<manufacturer>-<model>'), which provides meaningful but minimal additional clarity beyond the schema's 'Composite slug' 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?

The description opens with a specific verb and resource: it 'get[s] the full golden record' and 'latest price for one catalog product by slug.' It adds a precise identifier format and product context, so it is clearly distinct from sibling discovery/compare tools.

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 the tool's context clear: it is for retrieving a specific catalog product by slug, not for search or comparison. It does not explicitly name alternatives or exclusions, but the scope is specific enough that an agent should know when to invoke 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 declare readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds meaningful behavioral details: it returns each merchant's name, slug, and product count, and explicitly links the slug to the `merchant` argument of request_quote. It also clarifies exclusion criteria, which goes beyond what annotations 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 concise sentences cover the full scope: the main action, filtering criteria, exclusions, and return values, plus a practical cross-reference to request_quote. Every word earns its place, with no redundancy.

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 parameterless list endpoint with an output schema and read-only annotations, the description fully covers purpose, filtering, exclusions, return contents, and downstream usage of the slug. Nothing an agent needs to understand or invoke this 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?

The tool has zero parameters, so the schema provides no parameter information. The description does not attempt to document parameters because none exist. Following the baseline for 0 parameters (4), this score reflects that no further parameter semantics are needed or expected.

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 ('List') and clearly identifies the resource (public AirShelf merchants) and the exact filters (assigned slug, at least one active product). It does not explicitly contrast with sibling tools, but the enumeration of exclusions (internal/demo, empty catalogs) adds precision beyond a generic description.

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 implies when to use the tool by specifying that only public merchants with active products are returned, and it notes exclusions (internal/demo, empty catalogs). However, it does not name any alternative tools or provide an explicit 'use X instead' guidance, leaving the comparison to siblings implicit.

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 indicate mutation/destructive/external effects, but the description goes far beyond: it details the double opt-in flow, states that no lead exists and no merchant is contacted until confirmation, explains the statuses returned ('confirmation_required', 'awaiting_confirmation', 'received'), and clarifies that a later call with the same arguments is required. This rich behavioral context is essential for correct invocation and is not contradicted by 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?

The description is four sentences, each earning its place: purpose first, then the critical two-step flow, then merchant routing. No filler, front-loaded with the core action, and structured logically. It is concise yet comprehensive.

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 the tool's complexity (multi-step, double opt-in, special routing case) and the existence of an output schema, the description covers all operational details: the status flow, the need for a second call, and the merchant routing rules. Nothing an agent needs to call it correctly is missing, and the output schema presumably covers return format.

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 input schema has 100% parameter description coverage, so baseline is 3. The description adds meaningful context for the 'merchant' parameter (source via list_merchants, and the special 'airshelf-network' plus brandSlug combination) and clarifies that products are catalog slugs. This extra guidance for two parameters raises the score above baseline.

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+resource: 'Send a quote request for catalog products to a merchant's sales team on behalf of a named buyer.' This clearly distinguishes it from sibling tools like search_catalog or list_merchants, which are about discovery, not requests. The special 'airshelf-network' routing clause further sharpens the scope.

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 actionable guidance: merchant slugs come from list_merchants, and explains the fallback mechanism for network-catalog brands. It also describes the two-step double opt-in flow, telling the agent what to expect on first call vs subsequent calls. It does not explicitly mention when not to use this tool or name alternatives, but the sibling set has no overlapping tool, so this is adequate.

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 are minimal (readOnlyHint=false, openWorldHint=true, destructiveHint=false), so the description carries the burden of behavioral disclosure. It rises to the occasion: async execution and polling with research_id, 'refused' status for unsafe requests before work is queued, clarification flow for missing decision details, and the market semantic ('available in <market>' does not imply stock guarantee). All credit beyond what annotations provide.

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 long (~140 words) but each clause earns its place. It front-loads the most important info first (purpose and sibling distinction), then lifecycle, then safety refusals, then market nuance, and closes with an example. It forms a single dense paragraph that could benefit from a line break or two, but it's appropriately scoped for the tool's complexity.

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 tool with this much complexity (async background jobs, polling, safety refusals, clarification flows, market nuance, personas), the description covers the critical call paths thoroughly. The output schema handles return-value documentation. The main gap is not addressing the other siblings (compare_products, get_product, etc.) or edge cases like timeout/error states, but what's here is cohesive and complete enough to call 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%, so the schema already documents each parameter. The description adds genuinely useful semantics on top: the market parameter biases discovery but not stock, research_id enables polling for the async run, and the example answer key ({'budget': '500 USD', 'market': 'US', 'category': 'espresso machine'}) clarifies the answers object shape. Valuable, though some of this is also in the schema's descriptions.

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 the specific function: 'research_shopping is the full verified-research job', and immediately distinguishes its scope from sibling find_products, calling it the 'quick candidate-list tool'. It also specifies the resource (considered purchase) and the output (verified research with per-claim receipts). An agent can unambiguously tell this from the alternatives.

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 explicitly contrasts with find_products (quick candidate lists vs. full research), which is the single most likely point of confusion, and outlines the polling lifecycle (running → poll with research_id). However, it doesn't address the other six siblings or give an explicit 'use this when...' rule beyond the find_products dichotomy, so some routing decisions are left 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?

The description goes far beyond the readOnlyHint/openWorldHint annotations with detailed, non-contradictory behavioral guidance: unverified_specs caveats, weak-match semantics, no-match handling, tier3 lookups, cached lookups, and market-verification limitations. It clearly discloses the behavioral nuances an agent needs to interpret results safely.

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 long, but the complexity is high and the structure is effective: scope, examples, result fields, tier3 states, market caveats. It is front-loaded with the main purpose and practical query guidance, and it earns most sentences through concrete warnings and field-level semantics, even if slightly dense.

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 the tool's complex output semantics, 5 parameters, and output schema, the description is unusually complete. It covers retrieval behavior, ranked match accounting, result field caveats, miss/near-miss handling, tier3 resolution states, and market-dependent verification. Very little is left for an agent 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 documentation is complete, so the baseline is solid, but the description adds meaningful parameter context: query style and brand/part-number reliability, how specs are limited for certain catalog rows, and the detailed market argument effects. Supporting parameter meaning is strong, though limit and category receive little extra 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?

The description clearly states that this tool searches the AirShelf cross-vendor product catalog via natural-language queries, with concrete examples and category coverage. It is specific about what it does, but it does not explicitly differentiate itself from sibling tools such as find_products or research_shopping, so it misses the highest bar.

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 gives strong usage context: natural-language querying, category scope, manufacturer part-number behavior, and how market filtering changes results. It doesn't explicitly state when not to use this tool or which alternative to prefer for different tasks, but the context is clear enough for most selection cases.

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