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?

Beyond the readOnlyHint and destructiveHint annotations, the description discloses the meaning of evidence_sha256, clarifies that AirShelf does not serve archived bytes, and distinguishes record.scraped_at from per-claim capture time. These are significant behavioral details that prevent misinterpretation.

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 adding a distinct piece of information: purpose, output, hash semantics, and timestamp clarification. It is front-loaded with the core purpose and avoids redundancy, making it efficient and well-structured.

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 output schema exists, the description does not need to list return fields, but it adds critical clarifications about hash usage and timestamp interpretation. It covers the key behavioral aspects thoroughly, though it omits potential error conditions, which is minor.

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 provides a description for the single parameter slug ('Composite slug to explain'), so coverage is 100%. The description does not add further parameter-specific meaning beyond referring to the catalog row, 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?

The description clearly states the tool explains the evidence behind a catalog row, and specifies it returns processing stages and a golden-record field summary with source coverage. This distinguishes it from sibling tools like get_product or compare_products, which focus on retrieval or comparison 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 usage when evidence or provenance is needed, but it does not explicitly compare with alternatives or state when not to use it. It gives context on what the tool returns, but no direct routing guidance, so it is adequate but not explicit.

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?

Annotations already mark this as read-only, and the description goes well beyond them: it explains evidence_sha256 semantics, that AirShelf does not serve archived bytes, the commercial_data.actionable gate for price/stock, the expected null price for quote-gated B2B pricing, and related_products direction semantics. These are non-obvious behaviors an agent needs to interpret results correctly.

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 well-structured: core purpose, return semantics, pricing caveats, and related_products are presented in logical order. Every sentence adds a distinct behavioral or interpretational point, though some sentences are dense and could be tightened.

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 all essential behavioral caveats an agent needs: evidence hashes, source document availability, price actionability, quote-gated pricing, product card rendering, and relation direction. With an output schema present and annotations covering the safety profile, nothing critical 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 schema already documents slug with an example, and the description adds the composite format '<manufacturer>-<model>', which is useful semantic detail. With 100% schema coverage, the baseline is 3; the description's format clarification pushes it to 4.

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: 'Get the full golden record ... and latest price for one catalog product by slug.' It clearly distinguishes this single-product lookup from sibling search/compare tools by emphasizing 'one catalog product' and the slug-based access pattern.

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 strongly implies use when the caller already has a product slug and needs the verified record, but it never explicitly names alternatives like search_catalog, find_products, or compare_products, nor does it state when not to use this tool. The usage context is clear but not contrasted with siblings.

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 provide readOnlyHint=true and destructiveHint=false, so the read-only nature is known. The description adds meaningful behavioral detail: filtering rules (internal/demo/empty catalogs excluded), the exact returned fields (name, slug, product count), and the cross-tool relationship of the slug. This goes beyond the annotations without contradicting them.

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 tightly written sentences. The first states what is listed and the filters; the second states the return fields and connects the output to a sibling tool. Every sentence carries information, and the core purpose is front-loaded.

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 zero-parameter list tool with annotations covering safety and an output schema available, the description is complete. It specifies the exact population, the expected fields, and the practical use of the output. No additional context is 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?

The tool has zero parameters)Skip, and schema coverage is 100% vacuously; the baseline for 0 params is 4. The description adds no parameter-specific detail because none exists, but it does mention the relevance of the returned slug to request_quote, which is a useful adjacent semantic hint.

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 starts with a specific verb-resource pair ('List public AirShelf merchants') and further narrows the scope with precise inclusion criteria (assigned slug, at least one active product). It distinguishes the tool by explicitly excluding internal/demo and empty catalogs, and clarifies the output's role (slug as merchant argument for request_quote), making it easy to differentiate from sibling 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 gives clear context: this is the tool to use when you need publicly available merchants with active products)Skip, and it even ties the output to request_quote. However, it does not explicitly compare to alternatives like search_catalog or find_products, nor state when not to use it, leaving a small gap in routing.

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 flag it as a non-read-only, open-world, destructive write. The description adds substantial context beyond that: the double opt-in flow, that no lead exists and no merchant is contacted until confirmation, and the exact status strings ("confirmation_required", "awaiting_confirmation", "received") plus the reference_number returned. This is exactly the extra behavioral detail annotations cannot 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?

Three tight paragraphs, front-loaded with purpose followed by flow and edge-case routing. Every sentence carries information, though the density is high and could be marginally trimmed.

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 tool with nested objects and an output schema, the description covers the flow, status states, required identifier sourcing, and the network-brand edge case. Since an output schema exists, return values need not be explained, and nothing an agent needs to call it 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 baseline is 3. The description adds real meaning beyond the schema by explaining the merchant/brandSlug relationship for airshelf-network and clarifying the merchant slug source, though it does not elaborate on reference, quantity, or products syntax.

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 and actor: 'Send a quote request for catalog products to a merchant's sales team on behalf of a named buyer.' It is clearly distinct from the read-oriented siblings (find_products, get_product, list_merchants) and references list_merchants as the source of merchant slugs.

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 strong conditional guidance: merchant slugs come from list_merchants, and network-catalog brands absent from that list must use merchant:"airshelf-network" with brandSlug. It also explains the two-step opt-in sequence. It stops short of stating when NOT to use this tool versus an alternative, so it does not reach a 5.

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 annotations by disclosing async execution, polling via research_id, 'running'/'refused' statuses, per-claim source receipts, explicit refusal on insufficient evidence, and clarification-before-research behavior. It also clarifies the market semantics as 'seller page serves that market, not that stock is guaranteed.' This adds substantial behavioral context beyond readOnlyHint, openWorldHint, and destructiveHint.

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?

Every sentence in the description carries signal: purpose contrast, async lifecycle, refusal policy, completion output, clarification flow, market caveat, and example answer keys. It is front-loaded with the tool's purpose and contains no filler or repetition.

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 complex 5-parameter async job, the description covers the full lifecycle: starting research, polling by research ID, receiving a completed recommendation, handling refusals, and getting clarification questions. It also explains nested and market-dependent semantics. Since an output schema exists, not restating the full return shape in prose is acceptable.

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%, so the parameters are already well documented. The description adds extra meaning by explaining the market bias and by providing an example answer key for the answers object ({budget, market, category}), which helps an agent structure a nested free-form parameter. It does not redundantly re-explain need or persona.

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 by stating a specific verb, resource, and scope: 'research_shopping is the full verified-research job,' and immediately contrasts it with 'find_products is the quick candidate-list tool.' The title 'Research a considered purchase' reinforces the intended use case. An agent can distinguish this tool from siblings without opening other 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?

The description explicitly positions research_shopping against find_products, signaling that it is the slower, more thorough alternative. It also clarifies when research will not proceed: unsafe domains are 'refused' and missing decision details produce clarification questions. It does not explicitly route the agent among the other siblings like compare_products or request_quote, so some usage context is left 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?

Even though the annotations already mark this as safe and read-only, the description adds substantial behavioral nuance: unverified_specs must not be treated as decisive, null prices can be expected for quote-gated B2B pricing, data older than 24 hours is withheld, tier3 lookup statuses are explained, and market availability semantics are detailed. No contradiction with 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?

The description is long but well-structured, front-loads the purpose, and uses bullet-style field explanations that are easy to scan. Some result-field detail may overlap with what the output schema already conveys, but the behavioral caveats around unverified data and tier3 statuses justify most of the length.

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 search tool with 6 parameters, nested outputs, and subtle edge cases, this description is remarkably complete. It explains query construction, result interpretation, no-match behavior, unavailable-price semantics, market verification, and the tier3 fallback path, leaving an agent well equipped to call the tool and interpret responses 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 baseline is 3; the description then adds value by explaining that brand/part-number queries retrieve more reliably for certain rows, that the specs filter does not apply to those rows, and by providing example queries and deeper market-parameter behavior. It does not add much for limit or category, but the schema already describes those adequately.

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: 'Search the AirShelf cross-vendor product catalog by natural-language query.' It distinguishes the cross-vendor catalog from the merchant-specific shelf described in the merchant parameter, but it does not explicitly differentiate this tool from sibling search-like tools such as find_products or research_shopping.

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 clear context for use: cross-vendor search is the default and 'the right choice for "what should I buy"'. It also explains when the merchant-specific shelf is reached and the conditions around tier3 live lookups. However, it does not state explicit 'use this instead of X' exclusions for sibling tools.

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