ShopAIReady

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered; the description adds real value with an explicit capability limitation (WAF/User-Agent blocking cannot be verified) that an agent could otherwise misreport as a pass. It does not describe the report structure or severity/failure semantics, which keeps it at 4 rather than 5.

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 dense sentence that front-loads the scope ('one public product page') before the checklist, and ends with the one caveat that matters. No filler and nothing repeated from 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?

For a read-only, one-parameter tool with no output schema, the description gives enough about what is inspected to predict the findings. The notable remaining gap is the shape of the returned report (per-check status, severity, remediation hints), which an agent would have to discover at call time.

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 a single parameter and the schema already carries a full description covering the http(s) public URL constraint and the SHOPAIREADY_ALLOW_LOCAL escape hatch. The description adds no further semantics about the url argument, so this sits at the baseline 3 for high schema coverage.

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 ('Audits one public product page') and then enumerates the exact check categories: JSON-LD Product/Offer, price/currency/availability coherence, GTIN/MPN check digit, images, return/shipping markup, and bot accessibility. This is plainly distinguishable from the sibling feed validators and check_store_ai_readiness, which operate at feed/store level rather than on a single rendered page.

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?

'one public product page' establishes the unit of work, implicitly routing multi-page/store-level work to check_store_ai_readiness, and the closing 'Cannot verify WAF/User-Agent blocking' sets a clear expectation boundary. It stops short of naming a sibling alternative or stating an explicit when-not-to-use condition, 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds meaningful context beyond that: the score is heuristic, output is capped at ≤10 gaps, no login is required, and WAF/CDN blocking is outside its detection 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?

A single dense sentence that front-loads the action and scope, then the return value, then the caveats. Every clause earns its place with no padding.

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

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

With no output schema, the description carries responsibility for describing the return value, and it does so precisely (0–100 score plus ranked gaps and fixes with named check categories). The only missing item, a sample output shape, is not essential for correct invocation.

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?

Only one parameter (store_url) and schema coverage is 100%, including the local-path override detail, so the schema does the heavy lifting. The description adds nothing about the URL parameter beyond 'public store homepage', so 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?

Uses a specific verb+resource ('Audits a public store homepage') and enumerates exactly what is crawled (homepage, robots.txt, sitemap, one sampled product page) and what is returned (0–100 heuristic score, top ≤10 gaps and fixes). This scope is distinguishable at a glance from the product-page-focused sibling audit_product_page.

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

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

Clearly frames the tool as a read-only, no-login audit and states a limitation ('does not detect WAF/CDN bot blocking'), which tells the agent when results may be misleading. It never names a sibling or explicitly says when to prefer audit_product_page or the feed-validation tools instead, so the alternative-routing guidance is 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 declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description still adds real behavioral value beyond that: it never writes to Merchant Center or OpenAI, and unknown values are emitted as TODO rather than fabricated — the latter is a substantive disclosure an agent could not infer from 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?

Three tight sentences: purpose and input source first, output composition second, behavioral guarantees last. Every clause carries information — no restatement of the title, 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?

There is no output schema, but the description compensates by enumerating the CSV columns and stating the return is file content rather than a write. For a 5-parameter transform tool this is nearly complete; only the `language` parameter and the exact handling of a mixed/empty issue set remain unexplained.

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 60%, so the description must compensate somewhat, and it does: it identifies the `issues` parameter's source and ties Q&A template columns to `include_qa` and the seller_name column to `seller_name`. `language` is never mentioned and `target` is only implied by the column list, leaving a small residual gap.

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: converts the `issues` array into CSV text of suggested corrections, and enumerates the output columns (title, gtin, identifier_exists, product_type, availability, price, seller_name, Q&A). It also names the exact sibling tools that produce the input, so an agent can place it in the workflow 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?

The opening clause makes the trigger explicit — this is what you call with the `issues` array returned by validate_feed_for_google / validate_feed_for_chatgpt / audit_product_page, which clearly positions it downstream of those tools. It stops short of stating exclusions or what to do when issues is empty/invalid, but the sequencing guidance is unambiguous.

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

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

Annotations already cover read-only, idempotent, open-world and non-destructive, so the bar is lower; the description still adds real value by disclosing accepted input formats, the exact required-field ruleset, and the shape of the result (% SKUs OK, issue counts, sample issues). It does not cover failure modes (unreachable URL, oversized feed) or how many sample issues are returned, which keeps it below a 5.

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, front-loaded with the action, and the parenthetical field list is compact rather than padded. The required-fields enumeration is long but it is the substance of the check, so it earns its place; minor density cost only.

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

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

With no output schema, describing the return payload is essential and the description does it. Annotations carry the safety profile and the schema carries parameter docs, so the only gaps are error behavior and result limits — useful but not blocking for a correct call.

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% with only two parameters, so the baseline is 3. The description usefully implies the accepted feed formats behind feed_url (XML RSS/Atom, CSV, TSV, JSONL), but seller_name is never mentioned, so no meaning is added for that parameter.

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 pair ('fetches... and checks') and a concrete resource ('public product feed'), then names the exact spec being validated against (OpenAI Commerce products feed spec). The ChatGPT/OpenAI framing cleanly separates it from the sibling validate_feed_for_google without needing the name alone.

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

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

Usage is implied by the spec name — an agent can infer this is the ChatGPT-side validator — but there is no explicit when-to-use statement, no mention of when to prefer validate_feed_for_google or draft_supplemental_feed, and no prerequisites. It falls to inference rather than 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 cover the safety profile (readOnly, openWorld, idempotent, non-destructive), yet the description still adds real context: it fetches over the network, enumerates which attribute groups are checked, and explicitly flags the May-2026 conversational attributes as only a stub — a caveat an agent would otherwise miss. It stops short of covering feed-size limits, fetch failures, or how issues are ranked.

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-loads the action and the checked attribute set, then closes with the return value. The parenthetical attribute list with ellipses is long but earns its place by telling the agent what is validated; only the trailing '…' items add minor noise.

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 one parameter, no output schema, and annotations covering safety, the description does enough: it explains scope of checks, the stub caveat for conversational attributes, and the shape of the result. Missing only error/limit behavior for unreachable or oversized feeds.

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?

Single parameter with 100% schema description coverage, so the schema already documents feed_url including the SHOPAIREADY_ALLOW_LOCAL escape hatch. The description confirms the feed must be public but adds no syntax or format detail beyond that, which is the baseline for full schema coverage.

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: fetches a public product feed and validates it against Google Merchant Center required/recommended attributes, and names the output shape (% SKUs OK + issues). It does not differentiate itself from the sibling validate_feed_for_chatgpt, so an agent must infer the split from the name alone.

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

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

Usage is only implied by the Google-Merchant-Center framing; there is no explicit 'use this when' statement and no exclusion pointing to validate_feed_for_chatgpt or audit_product_page. The one actionable constraint (public http(s) URL) lives in the schema, not the description.

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