AI Commerce Intelligence

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

With no annotations, the description carries the behavioral burden, and it does disclose meaningful traits: the decision vocabulary, the 'free bounded' nature, and continued legacy support. However, it omits whether the operation is read-only, what 'bounded' limits actually are, whether external providers get consulted, and what happens when limits are hit or a claim comes back UNVERIFIABLE.

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 compact sentences with the 'free bounded' qualifier front-loaded and no wasted bulk. Minor blemish: 'remains the product-level decision surface' is prose-y and partially restates the tool's own name.

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?

This is a complex tool (16 parameters, a 12-field claims array, no output schema, no annotations) yet the description is one short paragraph. It names the verdict vocabularies but does not explain claim verification semantics, limit behavior, or how this tool relates to the decision-adjacent siblings, so an agent lacks enough context to invoke it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% across 16 parameters, so the description must compensate, but it only notes that required_terms is legacy. The remaining 15 parameters (claims structure, closed_world, max_age_seconds, auto_compile_claims, providers, price bounds, etc.) receive no explanation in either the schema or the description, forcing the agent to guess at their semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific resource ('ACE Check') and the output taxonomy: a product-level APPROVE/REJECT/UNKNOWN decision plus per-claim verdicts (PROVED/CONTRADICTED/SOURCE_CONFLICT/STALE/VERIFY_MORE/UNVERIFIABLE). This makes the tool's function reasonably clear, though 'ACE' is undefined jargon and the description does not differentiate it from siblings like route_commerce_decision or commerce_preflight.

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?

No guidance on when to use ace_check versus its siblings. It never names alternatives, conditions, or exclusions; the only usage-adjacent note is that legacy required_terms remain supported, which is a compatibility remark, not a selection guide. An agent cannot tell whether to pick this over commerce_preflight or verify_global_offer.

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?

With no annotations, the description carries the full burden and does disclose 'read-only,' a key behavioral trait. However, it does not state what the tool outputs, how it accomplishes the description, or that it will not execute any real commerce operation beyond the description.

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 a single concise sentence with no filler, front-loading the core action and read-only nature. The colon-style compression is efficient, though it slightly sacrifices clarity for brevity.

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 no-parameter, no-output-schema tool, the description is mostly adequate, but it leaves the exact return value unstated and relies on the model interpreting 'Describe ACE' as the tool's behavior. Explicitly saying the tool returns a description of ACE's capabilities would make it complete.

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 and the schema is empty, so there are no parameter semantics to document. The description correctly avoids inventing parameter details, and the baseline of 4 applies because no parameters exist.

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 an imperative 'Describe ACE' rather than stating precisely what the tool returns, creating ambiguity between a model instruction and a tool definition. It does name the resource (ACE) and its functional domains, which helps distinguish it from execution-focused siblings, but the exact purpose is not crisp.

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 this tool is for read-only discovery and description of ACE's capabilities, but it gives no explicit guidance on when to call it versus sibling tools such as ace_check or product_discovery. The usage context is inferred rather than stated.

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, openWorldHint, and destructiveHint, but the description adds meaningful behavior beyond those: verdicts stay APPROVE/REJECT/UNKNOWN, conflicts/staleness/unverifiable claims are preserved, and query wording is never treated as proof. This helps an agent understand key non-obvious behaviors, though it still doesn't fully disclose response structure or side-effect semantics. No annotation contradiction is present; 'batch-refreshes' reads as recomputation rather than state mutation.

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 only three sentences and avoids excessive padding, but the first sentence is branding ('ACE's flagship') and the second contains version-specific noise ('v5.0'). The most actionable operational behavior is in the final sentence, so it is not front-loaded. It could be tightened while preserving clarity.

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 16 undocumented parameters and no output schema, this description is insufficient for correct invocation. It provides high-level semantics around verdicts and finalists, but omits response format, how claims are structured, provider behavior, regional parameters, and relationship to sibling tools. The warning about query wording is valuable, but it doesn't compensate for the missing operational detail.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description must compensate, but it only references 'finalists,' 'claims,' and 'query wording' at a high level. It leaves the meaning of region, providers, price bounds, candidate_ids, auto_compile_claims, excluded/required/preferred terms, and the claims sub-fields unexplained. An agent cannot reliably construct a valid request from this description alone.

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 identifies the tool as a pre-purchase decision product and names its output verdict values (APPROVE/REJECT/UNKNOWN), plus a batch-refresh behavior for up to five finalists. It is understandable, but it reads more like a product pitch than a crisp verb+resource statement and doesn't distinguish it from sibling tools such as ace_check.

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 context ('pre-purchase decision product') and mentions batch-refreshing finalists, but it never states when to use commerce_preflight versus alternative sibling tools. No exclusions or condition-based routing is provided despite a large sibling set including ace_check, compile_commerce_claims, product_discovery, and route_commerce_decision.

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 discloses meaningful behavioral constraints: the graph is bounded, evidence can cross providers only through a strong product-identity bridge, and provider-bound offer/policy claims are excluded. With no annotations provided, this is helpful, but it still omits whether the operation has side effects, what the returned graph contains, or how failures are handled.

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 a single dense sentence with the primary action front-loaded. Each clause adds a relevant constraint without excessive filler. It is concise, though slightly jargon-heavy and could benefit from a brief parameter mapping.

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?

...

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It maps 'candidate IDs' to the candidate_ids parameter and adds the 'authorized provider-qualified' qualifier, and 'evidence' likely maps to claims. However, the claims object and country parameter receive no meaningful explanation, leaving much of the parameter semantics ambiguous.

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 action ('Build') and resource ('bounded multi-source ACE Trust Graph'), and it identifies the input source ('authorized provider-qualified candidate IDs'). The constraints about cross-provider evidence help distinguish it from likely single-source siblings such as ace_check, though the acronym 'ACE Trust Graph' is not explained.

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 the tool is appropriate: when building a multi-source trust graph from provider-qualified candidate IDs. It also includes an exclusion for provider-bound offer/policy claims. However, it never explicitly names sibling alternatives or gives clear when-to-use versus when-to-use-another-tool 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?

With no annotations, the description carries full responsibility for behavioral disclosure. It says 'Return', implying a read-only operation, but does not explicitly state that it is safe or non-mutating. It also does not mention potential size, latency, or error behavior. The reference to a rule about truth authority is content, not tool behavior.

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 a single, efficient sentence that front-loads the core action and resource, then covers the key components. There is no verbosity or redundancy—every phrase 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 zero-parameter tool with no output schema, the description effectively lists what the manifest contains, which covers the primary information an agent needs to understand the result. It could briefly note when this tool is intended to be used (e.g., for network overview), but the current detail is adequate for a simple fetch operation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There are zero parameters, and the schema coverage is trivially 100%. The baseline for 0 params is 4, and the description correctly avoids discussing parameters that don't exist, adding no unnecessary semantic burden.

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's function: 'Return the public ACE Commerce Trust Network manifest' and enumerates its contents (participants, protocol interoperability state, extension points, and the rule about truth authority). This specific verb+resource combination differentiates it from the sibling 'commerce_trust_graph', which implies a graph-based query rather than a manifest fetch.

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?

No guidance is provided on when to use this tool versus alternatives like 'commerce_trust_graph' or 'commerce_capabilities'. The description only explains what it returns, leaving the agent to infer the appropriate context or prerequisites without any explicit 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?

There are no annotations, so the description carries the burden of behavioral disclosure. It does disclose a key invariant: commercial relationships and commissions can never alter ACE Check, ACE Verdict, claim status, source authority, or organic truth. However, it does not state whether the tool is purely read-only, what it returns, or whether it describes policy in prose, structured form, or something else.

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 two sentences with no filler. The first sentence states the scope and the version context; the second gives the substantive policy rule. Every clause adds meaning, and the information is efficiently 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, no-output-schema policy tool, the description is nearly complete. It tells the agent what subject the policy covers and states the central rule. A minor gap is that it does not indicate what form the returned policy information takes or whether there are related constraints beyond the one stated, but the low complexity keeps this from being a major omission.

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 there is no schema burden for the description to compensate for. The baseline is 4 for zero-parameter tools, and the description appropriately provides policy context without needing to document parameter behavior.

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 identifies the resource ('v4 commercial attribution rules') and the tool's purpose ('Describe...preserved by ACE v5.0'). It explains the core policy constraint about commercial relationships. However, it does not explicitly differentiate this tool from commerce-related siblings like commerce_capabilities or commerce_trust_graph, relying on the name and subject matter rather than stating what this tool is not.

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 this tool should be used when someone needs the attribution policy or needs to confirm that commercial relationships cannot affect ACE outcomes. It provides no explicit 'when to use' or 'when not to use' guidance, and it does not name alternative tools or exclusions. The usage context is reasonable but 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?

With no annotations provided, the description carries the full burden. It does a good job of clarifying what the tool does NOT do ('never turns a suggestion into truth'), which is important context. However, it does not disclose any side effects, return format, or whether it modifies state, leaving some behavioral ambiguity.

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 two sentences with no redundant words. It front-loads the primary purpose and quickly adds the critical boundary ('does not verify'). Every sentence 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 tool with no output schema, this description is reasonably complete. It tells the agent what to pass and what the tool will not do. However, it omits what the output should look like and doesn't clarify how 'reviewable structured ACE claims' are returned, which could matter for an agent relying on this tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate for explaining the 'query' parameter. The description defines what 'query' should contain (high-confidence natural-language commerce requirements) but provides no details about format, constraints, or examples. This is useful but minimal compensation for the lack of schema-level documentation.

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 ('Convert') and a clear resource ('high-confidence natural-language commerce requirements' into 'reviewable structured ACE claims'). It distinguishes itself from verification tools by explicitly stating it does not verify claims, which helps separate it from siblings like ace_check and verify_global_offer.

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 it (when you have high-confidence natural-language requirements) but provides no explicit guidance about when not to use it or what alternatives to prefer. It does not mention that ace_check or verify_global_offer should be used for verification, which is a missed opportunity given the sibling list.

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?

With no annotations available, the description carries the full burden of behavioral disclosure. It reveals a nontrivial trust and safety trait: caller-supplied verdicts will never be accepted as eligibility proof, and the decision_ref is short-lived and server-side. It does not cover expiry/failure behavior, idempotency, or authorization, but it provides meaningful behavioral context beyond the action itself.

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 two sentences with no redundancy or filler. The main action is front-loaded, and the second sentence adds a crucial policy constraint that 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?

The core invocation is covered: the required parameter and how to obtain it are clear. However, the optional parameters are unexplained, no output or result shape is mentioned, and with no output schema or annotations an agent is left to infer post-creation behavior and failure semantics. It is sufficient for a straightforward call but not fully complete.

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 has 0% parameter description coverage, so the description must compensate. It does explain the required decision_ref parameter well, noting its source and short-lived nature, but event_id and record_click receive no semantic guidance. Coverage is therefore partial, and the optional parameters remain underspecified.

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 and object ('Create an ACE referral') and precisely scopes the input to 'a short-lived server-side decision_ref returned by ACE Check'. It also explicitly distinguishes itself from tools that might accept caller-supplied verdicts, making its purpose 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 clearly positions this tool as the follow-up to ACE Check: use it when you have a decision_ref from that call. The phrase 'Caller-supplied Verdicts are never accepted' functions as a when-not boundary, ruling out direct verdict input. It does not explicitly name alternatives, but the upstream relationship is clear.

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?

No annotations are provided, so the description carries full behavioral disclosure burden. The caveat 'This is a bounded readiness sample, not a claimed full-catalog lost-revenue estimate' is a meaningful limitation disclosure that prevents misuse, and 'Summarize' implies a read-only operation. However, it does not disclose output shape, failure behavior, or how evidence gaps are computed, so transparency is only partial.

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 two sentences with no filler. The main action and scope are front-loaded, and the caveat is placed immediately afterward. Every sentence 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?

Given six parameters, zero schema descriptions, no annotations, and no output schema, the description is far too sparse to give an agent enough context to invoke the tool correctly. It does not cover paramater semantics, expected output, or operational constraints beyond the bounded-sample caveat.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate for undocumented parameters. It provides general context about up to five merchant candidates and ACE eligibility, which loosely maps to candidate_ids and possibly claims, but it does not explain the meaning of claims, terms, country, excluded_terams, required_terms, preferred_terms, or operator semantics. This is not enough for reliable parameter construction.

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 ('Summarize') and resource ('ACE eligibility and evidence gaps') across up to five merchant candidates, and adds a clear scope caveat distinguishing it from a full-catalog lost-revenue estimate. It is clear but does not explicitly differentiate from sibling tools such as ace_check or compile_commerce_claims, so it stops 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?

The description implies the tool is for provider-qualified merchant candidates in a bounded sample, but it provides no explicit when-to-use vs. alternatives guidance. It does not name any sibling tool or state conditions under which another tool would be preferred, leaving the agent to infer usage from the name and description alone.

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?

With no annotations, the description carries the behavioral burden. It usefully discloses that Shopify Global Catalog is live while eBay Browse and Amazon Creators are only available when their 'explicit authorization gates are open.' It does not cover read-only guarantees or error behavior, but the gating detail is substantive.

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 convey the core operation and provider availability without wasted words. The active search verb is front-loaded and the gating nuance is placed in a compact second sentence.

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 seven parameters, no output schema, and no annotations, the description is under-equipped. It explains provider gating but omits parameter semantics, output expectations, and selection guidance, leaving an agent needing more information to invoke it confidently.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate for the seven parameters. It adds only provider availability context and leaves query, limit, country, currency, min_price, and max_price semantically unexplained.

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: 'Search the ACE Provider Mesh.' It also names the provider set and their availability, which helps distinguish the tool from commerce decision/identity sibling tools, though it never explicitly references an alternative.

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

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

The phrase 'just in time' implies this is for on-demand discovery, and the provider-gate sentence clarifies when each source is usable. However, it does not explicitly state when to prefer this tool over siblings like route_commerce_decision or resolve_product_identity, nor does it give exclusions.

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?

With no annotations provided, the description carries the full burden of disclosure, and it does so well: it reveals the exact-identifier post-filtering behavior, the authoritative status of a match, and the critical limitation that an absent match is not proof of safety or absence of recall elsewhere. Minor gap: no statement about invalid input handling or network failures, but the epistemic caveats are the most important behavioral traits and they're covered.

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 sentences, each earning its place: operation, behavioral guarantee, and interpretive caveat. No filler, no repetition of schema data, and the most important epistemic qualifier is front-loaded. This is appropriately sized for a single-parameter lookup.

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 lookup with no output schema, the description is nearly complete: the agent knows what to pass, what the result means, and how to interpret a null result. The main missing piece is the return shape, which could matter if the agent needs to extract recall details. The 'CPSC' typo is minor and doesn't affect comprehension, but it dows the score slightly from a 5.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description needed to compensate for the lone 'gtin' parameter — but it only mentions 'GTIN/UPC' in passing without explaining format normaliation, hyphen handling, or what values are acceptable beyond 8-24 characters. The description doesn't explicitly map the parameter to its schema property, which would have been trivial to do. With zero schema coverage, this is a clear compensation 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?

The description clearly states the operation ('Query'), the exact resource ('authorized U.S. CPSC recall API'), and the required identifier ('exact GTIN/UPC'). The phrase 'exact-identifier post-filtered' distinguishes this from sibling tools in an important way, and 'authoritative safety evidence' makes its purpose unmistakable.

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 when to use the tool: when an agent has a specific GTIN/UPC and needs authoritative recall information. It also tells the agent how to interpret an empty result ('no match is UNKNOWN and never proof that a product is safe'), which is critical usage guidance. However, it doesn't explicitly name sibling alternatives or state when NOT to use this tool, leaving some room for 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?

With no annotations, the description carries the full behavioral burden, and it discloses consequential matching behavior: resolution is 'conservative', only exact GTIN or exact brand+MPN bridges providers, and title similarity never merges. It also states a blocking condition (variant conflicts), which is meaningful guidance beyond the schema. It does not address side effects, permissions, or failure behavior, but the core matching behavior is well exposed.

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 dense sentences with the core action front-loaded and the critical matching rules immediately after. Every clause carries semantic content: conservative resolution, exact GTIN, exact brand+MPN, title-similarity prohibition, and variant-conflict blocking.

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 tool with no annotations and no output schema, the description explains the resolution policy well, but leaves gaps: the role of country is undocumented, the format/provenance of candidate_ids is unstated, and the return behavior is unspecified. The matching rules make the tool usable, but the missing country and output semantics prevent full standalone completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate for the schema's silence. It adds some meaning to candidate_ids by calling them 'provider-qualified' and implying they are the IDs to be merged using GTIN/brand+MPN, but it never describes the optional country parameter or the exact string format expected. The matching criteria are indirectly useful but do not fully document the two parameters.

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 names the operation ('Resolve ... into conservative ACE product entities') and the input ('provider-qualified candidate IDs'), giving a specific verb and resource. The second sentence's exact-ID matching rules also help distinguish it from more permissive discovery or claim tools in the sibling list, even though 'ACE' is left as a domain acronym.

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 establishes the intended use (canonicalizing provider-qualified IDs into product entities) and the operative constraints: exact GTIN or brand+MPN may bridge providers, title similarity alone never merges, and variant conflicts block proof. It clearly conveys when the tool applies, though it does not explicitly name an alternative tool or state formal when-not-to-use conditions.

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?

With no annotations, the description carries the full burden. It discloses meaningful traits: the routing is immutable with respect to ranking/verdict and only surfaces verified executable paths. Yet it leaves side effects, authentication/permissions, expiry behavior, and failure modes unstated, and the term 'post-truth' could confuse an agent.

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 dense sentences, front-loaded with the verb and resource, and no filler. The second sentence is slightly convoluted and 'post-truth' is jargon, but overall the description is appropriately compact.

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 tool with no output schema and no annotations, it gives core behavioral context but does not describe the return shape of 'execution routes', how the decision_ref expiry is surfaced, or how this tool relates to the many commerce siblings. An agent could invoke it, but would be guessing at output details.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate, but it only references decision_ref by name and hints at 'protocol paths' without explaining preferred_protocols, its optionality, the enum values, or how it affects routing.

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 names a specific verb ('Plan') and resource ('execution routes' for a server-issued ACE decision_ref), and clarifies that it returns only verified executable protocol paths. It does not explicitly distinguish itself from sibling tools such as commerce_preflight or create_commerce_referral, and the phrase 'post-truth' is ambiguous jargon rather than a clear domain term.

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 implies the tool should be used after an ACE decision exists ('short-lived server-issued ACE decision_ref') and that routing cannot alter ranking or verdict, which signals a post-decision use case. However, it never names alternatives or states explicit when-to-use/when-not-to-use conditions relative to the sibling tools.

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?

With no annotations, the description carries the full burden. 'Return machine-readable ... prices' clearly indicates a read-only retrieval operation and hints at structured output, but it does not disclose potential caveats such as authorization requirements, output format details, or whether usage boundaries are enforced limits.

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 a single front-loaded sentence with no filler. 'Machine-readable' earns its place by signaling structured output, and every word contributes to the tool's meaning.

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 read-only tool, the description is minimally complete: it identifies the return content and format. However, it lacks domain context for the 'ACE' acronym, does not explain what 'usage boundaries' means, and provides no guidance relative to sibling tools, so an agent may not fully understand when to invoke it.

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 leaves nothing undocumented. The description is not required to explain parameter behavior, and the baseline for a no-parameter tool is appropriately met.

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 ('Return') and a specific resource ('ACE prices and usage boundaries'). It is clear about what the tool does, though it does not explicitly differentiate itself from sibling tools like commerce_capabilities or product_discovery.

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?

There is no guidance on when to use this tool versus its siblings, no exclusions, and no mention of alternatives. The description only states what the tool returns, leaving the agent to infer appropriate usage 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description only adds the notion of resolving to 'current normalized offers' and the low-level compatibility framing. While useful, it does not disclose return shape, failure modes, or external dependencies beyond what annotations broadly imply.

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

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

Two tight sentences with no filler. The 'low-level' positioning is front-loaded, followed by the core function and then the routing guidance. Every clause earns its place.

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

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

The tool is simple, has strong annotations, and the usage guidance is good. However, with no output schema and no description of the 'country' parameter's role or accepted values, the agent lacks full information to reliably call the tool, especially for country-dependent offer normalization.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It does clarify the 'identifier' parameter by listing accepted forms (ID or HTTPS URL), but it says nothing about the 'country' parameter beyond schema defaults and length constraints. This is partial compensation, not full.

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?

Description states a specific verb ('Resolve') and a clear target ('Shopify Global Catalog product/variant ID or HTTPS product URL') with an explicit outcome ('current normalized offers'). It also positions itself as a 'low-level compatibility primitive', which clearly differs from the higher-level sibling commerce_preflight.

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

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

Explicitly names the alternative: 'New integrations should prefer commerce_preflight.' This tells the agent when not to use the tool and which sibling to use instead, leaving little ambiguity about intended invocation context.

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