AirShelf Catalog

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

Far exceeds the annotations: it discloses the per-product return shape (canonical_name, spec_absence_note), the actionable/stale-observation gating on commercial_data, what commercial_disclosure signals about the seller relationship, and the not_found/did_you_mean failure mode. Nothing here contradicts readOnlyHint=true, destructiveHint=false — it is a pure read.

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 comparison behavior and cardinality, then progressively de-risks with slug formatting and response branching. It is dense but each sentence carries information; the final provenance sentence is the one piece that largely repeats the schema and could be 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 two-parameter, read-only comparison tool with an output schema, this covers everything an agent needs: valid inputs, failure handling, and how to interpret the commercially sensitive fields before acting on them. The spec_absence_note and golden-record framing also pre-empt misreading absent specs as zeros.

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 earns above that by explaining slug normalization and tolerance with concrete examples that the schema's 'Catalog slugs to compare' does not convey. The provenance option is only restated from the schema, so it adds no new meaning there.

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 — compare 2-10 catalog products side-by-side on datasheet specs — with an explicit cardinality bound. It is clearly distinguishable from siblings like get_product and search_catalog, which fetch rather than compare across multiple items.

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 tells the agent where slugs come from (search_catalog) and how to format them (case-insensitive, dash-tolerant, with three worked variants), which is the practical prerequisite for calling the tool. It does not explicitly say when to prefer get_product or explain_product instead when only one product is of interest, so it falls short of full when/when-not 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?

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?

Goes well beyond the readOnly/openWorld annotations: it discloses that each call sends the need text to web-search providers (a real privacy/egress signal), that live results are a sample not a ranking, and how fallback behaves when discovery is rate-limited, unavailable, fails, or finds no fit.

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 opening two sentences and the sibling routing are well front-loaded, but the large bulleted response-fields block largely restates a return contract that an output schema already declares, making the definition noticeably heavier than needed for the decision it supports.

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 three-parameter, open-world, live-network tool the description is nearly complete: degradation states, candidate status semantics, and egress are all covered. It is slightly over-complete on return values that the output schema already carries, which is redundancy rather than a gap.

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 earns an extra point by clarifying what market actually means ('Available in <market>' means the seller page serves that market, not a stock guarantee) and by explaining the cap on max via 'Returns up to 3 candidates'.

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 (discover) and resource (candidate products) plus the input form (natural-language need, market). It also positions itself precisely against siblings: 'find_products is the quick candidate-list tool; research_shopping is the full verified-research job' and search_catalog for a specific brand+model.

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?

Explicit alternatives with selection conditions are given for both siblings (research_shopping for full research, search_catalog when a specific brand+model is known and cheaper). The description also names exclusions — out-of-scope needs, live discovery off, rate-limited — so an agent knows when the tool degrades or does not run.

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

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

Beyond the readOnly/non-destructive annotations, the description discloses provenance hash semantics, that AirShelf does not serve or guarantee the archived bytes, the 24-hour latestPrice withholding rule, quote-gated null behavior, commercial_disclosure conditions, MCP Apps card rendering, and related_products direction semantics. These are substantive behavioral traits not covered by 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 purpose is front-loaded and most sentences carry meaningful caveats, but the description is very long for a one-parameter read tool. It spends substantial text explaining return-shape details even though an output schema exists, and the single-block format makes later caveats harder to scan.

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 catalog lookup with rich output, the description covers provenance, price staleness, quote-gated nulls, merchant disclosure, and related-product relations, so an agent has enough context to invoke and interpret it. The main gap is explicit sibling routing rather than missing operational 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?

There is one required slug parameter with 100% schema description coverage, and the schema already gives a composite slug example. The description restates the '<manufacturer>-<model>' format but adds no syntax, constraints, or edge cases 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 first sentence names a specific verb ('Get'), resource ('full golden record... latest price'), and scope ('one catalog product by slug'), and gives the slug shape. This clearly separates it from catalog search/find/compare siblings, even without naming them 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?

It explains how to interpret returned commercial data, including branching on commercial_data.actionable and expecting null quote-gated prices. However, it never states when to choose this tool over find_products, search_catalog, or explain_product; the requirement for a composite slug only implies that discovery happens elsewhere.

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 readOnly and non-destructive annotations already make the safety profile clear. Beyond them, the description discloses the exclusion rules that matter for interpreting results: no internal/demo catalogs, no empty catalogs, and no catalog makers lacking an AirShelf account. It says nothing about pagination or ordering, but in all other respects it is richer than 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?

Four short sentences, and the sentence that states the tool's core scope comes first. The sentence about the return fields and the sentence about the request_quote link each carry distinct information, so nothing is wasted.

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 field-level return documentation is not required. The description still fills the remaining gaps: which merchants appear in that schema, which are filtered out, and how a returned slug is consumed by a sibling tool, so an agent has everything it needs 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 takes no parameters, so the baseline is 4 and there is nothing to document. The description correctly imposes no argument burden on the caller and instead documents the one output field that is an input elsewhere (slug feeding request_quote).

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 gives a specific verb and resource ('List public AirShelf merchants') plus the exact inclusion criteria: assigned slug and at least one active product. This is enough to separate it from every sibling, all of which operate on products or quotes rather than merchants.

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

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

It states the downstream use case clearly: 'the slug is the `merchant` argument for request_quote', which tells an agent when this tool is the right first step. It does not name an alternative or an explicit case where this tool should be avoided, but no sibling lists merchants, so there is nothing to route against.

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?

The description adds substantial behavioral context beyond the annotations: quote-gated pricing, stale commercial observations, `unverified_specs`, `weak_match`, `no_match`, and the three `tier3` statuses. These details warn the agent about interpretation and fallback behavior that annotations alone do not cover.

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 front-loaded with purpose and structured with bullets, but it is very long and includes extensive return-field documentation even though an output schema exists. Much of that detail is useful, but it weakens conciseness by duplicating structured output 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?

For a complex search tool with six parameters, nested `specs`, market-dependent behavior, and tier3 fallback logic, the description is thorough. It covers the main edge cases an agent needs to interpret results and avoid overclaiming from weak or unverified data.

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 baseline is 3. The description adds meaningful semantics beyond the schema, especially how `market` affects weak-match status and tier3 lookup/cache, why `specs` does not apply to certain rows, and how `merchant` switches to a separate substrate.

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 and resource: search the AirShelf cross-vendor product catalog by natural-language query. It also clarifies the catalog's coverage and some row-indexing behavior. It does not explicitly differentiate itself from sibling tools such as find_products, 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?

It gives concrete usage context: omit `merchant` for default cross-vendor search, use it only when the cross-vendor catalog returns nothing, and note that `specs` does not apply to industrial-automation and wiring-device rows. However, it does not explicitly name or exclude sibling alternatives, so it is clear but not fully comparative.

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