AI Orderability (AIO) Agents CPG with x402: Retail & Marketplace Sourcing

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

With no annotations, the description carries the burden of disclosure. It reveals that a human intervenes (slower, async) and that the tool is a communication channel, not a data-fetching endpoint. It doesn't disclose turnaround expectations, escalation paths, or whether replies arrive via the same channel, but the core behavioral trait (human-mediated) is clear.

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 terse sentences, front-loaded with the core 'human channel' identity. Minimal waste; the key usage guidance is in the final sentence. Slightly more verbose than strictly needed but acceptable.

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 tool, the description is sufficient. It tells the agent this is the human fallback, gives the trigger condition, and rules out agents. Nothing else an agent needs to invoke it is missing — though it could note that responses are asynchronous.

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 zero parameters. The description essentially communicates that no structured input is needed — the agent simply sends its message. This is important context that the schema alone (empty properties) doesn't fully convey, so the description adds meaningful functional meaning.

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

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

The description clearly states this is 'The human channel' for the GSC Trading Desk, explaining that a human reads and answers. It distinguishes this from agent-to-agent communication, though it doesn't explicitly name the sibling tool it contrasts with ('agents use Instant Messaging' implies instant_message_agents).

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 states 'Use it for anything a person should decide; agents use Instant Messaging.' This provides clear when-to-use guidance and points to the alternative channel (Instant Messaging for agents), though it doesn't elaborate on edge cases or when a human decision is unnecessary.

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 must carry the behavioral burden. It mentions properties like 'append-only' and 'non-substitutable', which hint at data semantics, but it does not clarify whether the tool reads or writes, what it returns, or what side effects occur. The mention of canonical resolution and a 'gen-2 door' is cryptic and fails to describe observable behavior of the tool call 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 short, but it is not front-loaded with the most critical information—what the tool does. Instead it leads with an abstract characterization of a protocol. The prose is efficient but obscure, making it less usable than a concise action-oriented statement. No redundancy, but poor prioritization.

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 get tool with no annotations and no output schema, the description leaves out fundamental details: what the tool returns (presumably the seven signals, but not stated), any prerequisites, or what 'canon resolves' means practically. An agent cannot tell what result to expect or how to interpret the response, making the definition incomplete for reliable use.

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

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

The tool has zero parameters, so the baseline per the guidelines is 4. The description adds nothing about parameters because none exist; there is nothing to explain beyond the empty schema, which is already fully described at 100% 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?

The description describes 'the deterministic signal protocol every GSC surface speaks' but never states what the tool does when invoked. There is no explicit verb like 'retrieve', 'query', or 'return'. It reads as a definition of the ACM-68000 standard rather than a tool action, leaving the agent without a clear idea of the operation it would perform.

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 any of the siblings. The list of sibling tools includes get_brand, search_brands, and others, but the description gives no hint about which scenario would call for get_acm_68000. No exclusions, no context, no alternatives are mentioned.

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 bears full responsibility for behavioral disclosure. It only offers the cryptic hint 'Status is only what the wire says', which implies a live read with no caching or resolution logic, but it never explicitly says the call is read-only, what happens on missing hosts, whether auth is required, or what error semantics apply. For a get-style tool, that is a meaningful gap in disclosure.

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 admirably short, but its density works against clarity: terms like 'signed Card', 'host's jwks', and 'what the wire says' are insider vocabulary that force the agent to decode rather than simply process. It is concise in word count but not in comprehension value, so it earns a middling score.

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 definition is safe to invoke since there are zero parameters and the resource is generally named. However, with no output schema and no description of the return shape, an agent cannot predict whether the result is a single class object, a per-region map, or an array of agent records. For a domain this specialized, the description should at least sketch the shape of what comes back.

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 nothing for the description to explain about invocation arguments — the call cannot be mis-parameterized and schema coverage is vacuously complete. Per the 0-parameter baseline, this dimension is effectively covered.

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 points at a concrete resource — the AIO Agent class and its regional hosts — rather than merely restating the tool name, so it is not a tautology. However, it never uses an explicit verb such as 'retrieves', 'lists', or 'enumerates', and it is full of unexplained jargon ('gen-2 fleet', 'signed, resident, addressable resolvers', 'jwks', 'wire'). An agent gets a vague sense of the subject but not a crisp statement of what the call actually returns.

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 whatsoever about when to call this tool versus the many sibling get_* tools (get_marketplace_operators, get_radar, get_x402_rail). The description offers no enabling conditions, no exclusions, no async or alternate routing, and no mention of prerequisites, so an agent can only infer usage from the tool name.

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 discloses that the tool returns a SPARKS tier, market supply/demand context, and 'both doors to act', and explicitly lists what it does not return. However, the concept of 'doors' is not explained, and there is no mention of error behavior or response format, limiting full transparency.

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, front-loaded with the step and purpose. It efficiently packs tier definitions and exclusions without excessive length, though the cryptic 'doors' term and specialized jargon reduce accessibility slightly.

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?

No output schema exists, so the description must explain return values. It mentions SPARKS tier, supply/demand context, and 'both doors to act', but 'doors' is underspecified and 'supply/demand context' is vague. An agent cannot determine what the response will contain or how to use the 'doors' to proceed, leaving important gaps.

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 both parameters are fully documented in the schema. The description does not add any new semantics about 'brand' or 'market' beyond what is already in the schema, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: verifying whether a brand exists on the CPG Knowledge Graph for a market and determining its SPARKS completeness tier. The verb 'verify' and resource 'brand on the CPG Knowledge Graph for this market' are specific scrape. While it does not explicitly compare to sibling tools like get_brand_identifiers, the action is distinct enough that an agent can infer its core role.

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 as 'Step 2 — VERIFIED' in a multi-step flowasi, and it provides exclusions ('No prices, no stock, no terms — those go through the doors'). However, it does not name any alternative tools or when to prefer them over this one, leaving the routing partially 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 behavioral burden, and it does add meaningful constraints: only GSC's own GS1-registered 990832300xxx block is published, third-party GTINs are never stored or surfaced, and the demo brand carries GSC's rail GTIN. This sets clear expectations about data boundaries even though it does not describe response structure or error 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 compact: three sentences that state the publishing boundary, redirect held-GTIN lookups, and note demo data. It is dense and moderately jargon-heavy, but every sentence contributes useful context. The 'Step 3 — ANSWERABLE' prefix is cryptic but not wasteful.

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 simple two-parameter lookup, the description gives solid policy and boundary context but never directly states what the tool returns or what a successful response contains. With no output schema and no annotations, that missing explicit return-value statement leaves a real gap, though the overall context is enough to make a reasonable 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?

The input schema already covers both parameters with descriptions (brand name, market member code or namespace), so the schema carries the parameter-documentation weight. The description adds domain color like 'rail GTIN' and '990832300xxx block,' but it does not add parameter-level meaning beyond what the schema provides. Baseline 3 is appropriate at 100% 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?

The description explains a brand identifier policy and points to alternative resolution tools, but it never states the tool's core action in a direct verb phrase such as 'returns the GSC-published identifiers for the requested brand.' The name and title imply the purpose, and the phrase 'never appear here' hints at the output domain, but an agent must infer what calling this tool actually produces.

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 routes callers who already hold a GTIN to CPG Knowledge Graph tools (resolve_gtin, resolve_sparks, check_eligibility) and explains that third-party GTINs will not be found here. This is useful when-not and alternative guidance. It does not, however, explicitly state when to prefer this tool over siblings like get_brand or search_brands.

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. It weakly implies read-only behavior ("14 read tools", "statement of record, read live") and cites a source URL, which is some signal, but it never says what a zero-parameter call returns, whether there is paging or a rate limit, or how large the response is.

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?

It is a single line, but it is front-loaded with catalogue statistics and URLs rather than the operational purpose an agent needs first. The most prominent content (counts of makers/banners/markets) does not help select or call the tool.

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 root tool with no annotations and no output schema, the description is the only place to explain what a call returns and when it is worth making. Instead it supplies branding and external links, leaving the actual behavior of the call 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?

The input schema declares zero parameters, so there is nothing for the description to document; per the rubric this is the baseline-4 case. No parameter meaning is added or omitted.

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 text is a marketing statement of record ("353,532 makers · 8,619 retail banners · 25 markets", "14 read tools over MCP") rather than a statement of what invoking this tool does. It restates the title ("The CPG Knowledge Graph — data surface") without a verb+resource pair an agent can act on, and it never distinguishes this tool's output from siblings such as get_brand or search_brands.

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 when-to-use guidance at all: no condition for selecting this tool, no exclusions, and no reference to any of the ten siblings. "The data surface every marketplace answer resolves against" is promotional framing, not an invocation cue.

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 well: it discloses content exclusions ('no tiers, no pursuit language, no relationship claims, no named individuals') and clarifies the posture field's meaning ('wire evidence only'; 'unassessed' means none collected). This is substantial behavioral context, though it omits data-freshness or pagination 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?

Two dense sentences front-load the resource and scope, then add the neutrality constraints without filler. Every clause adds information, though a single taxonomy-value example could make it more concrete.

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 one-optional-parameter read tool with no output schema, the description covers the data source, entity type, sort field, and negative constraints. The market parameter's summary behavior is delegated to the schema, so an agent has enough to call and interpret the result 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 only parameter, market, is fully described in the schema ('Omit for the 50-market summary'), so the description does not need to add much. It adds only the contextual phrase 'per market', which does not change parameter semantics; 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 identifies a concrete resource ('demand side per market', retail banners/public registry data) and a specific verb ('get'/'map'), making the tool's purpose clear. It does not explicitly contrast itself with siblings like get_cpg_knowledge_graph, even though 'as the CPG Knowledge Graph publishes it' hints at a projection.

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 explicit when-to-use or exclusion guidance is provided; the description only implies this is for reading neutral marketplace-operator data. It never names alternatives such as get_cpg_knowledge_graph or contact_trading_desk, leaving the agent to infer selection.

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 useful behavioral context beyond annotations (which are absent): the data is live, comes directly from GSC Radar, and is macro-level. It does not disclose rate limits, authentication needs, or potential side effects, but for a read-only getter, this is acceptable. The phrase 'as GSC Radar publishes them' hints at a passthrough behavior. No contradiction with annotations.

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

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

The description is a single, information-dense sentence. It front-loads the core subject ('public network figures') and qualifies with format and scope. The only minor issue is that 'macro numbers only' is a bit cryptic—could be clearer, but it stays concise.

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

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

For a parameterless, read-only tool, the description covers the key aspects: what data (network figures), source (GSC Radar), format (live JSON), and granularity (macro). It doesn't describe the JSON structure or sample response, but given the simplicity and no output schema, this is sufficient. An agent could correctly use this tool with the given information.

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?

With zero parameters and 100% schema coverage (empty schema), the baseline is 4. The description adds context about what the data represents, effectively explaining why no parameters are needed—it's a fixed public feed. No additional parameter documentation is required.

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 retrieves 'public network figures as GSC Radar publishes them,' adding the format ('live JSON') and scope ('macro numbers only'). While it doesn't explicitly contrast with siblings, the resource and action are clear. The title also reinforces the purpose.

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 context is implied through 'public network figures' and 'macro numbers only,' suggesting it's for high-level data, not detailed breakdowns. However, there's no explicit guidance on when to prefer this over sibling tools or any exclusions. The description implies a general use case but leaves selection logic to the agent.

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 disclosure burden. It does state that the gsc-marketplace.ai/api endpoint's terms live only in its 402 payload and never the tool description, which is a genuine behavioral disclosure. But it never says whether calling this getter is side-effect free, whether it reaches a remote endpoint, or how the returned declaration is formatted.

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 text is short, but not especially well structured. The first sentence packs list, network, asset, status, and terms caveats into a run-on; the second adds 'Door' and 'skill' without explaining what those terms mean for an invoker. It is telegraphic rather than simple.

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-param unput getter, the tool requires almost no parameter setup, yet an Agent needs to know what the response contains, and whether it is safe to call remote. The description lists the domains of information (header, network, asset, status) and the endpoint, but it does not explain the response structure or what 'capability declaration' actually returns.

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

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

The input schema has zero properties and zero required parameters, so there is no parameter documentation gap to fill. The baseline for a caller with no parameters is high, and the description adds small value by contextualizing what the tool declares. Nothing about parameters is missing.

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 the concrete verb-resource shape: it says the tool reports 'what GSC-Marketplace declares about x402' and enumerates the scope (header, network, asset, status, endpoint). That gives the agent a real sense of what the tool retrieves. It is not a tautology, and the content separates it from mere 'get' across ancestors. However, it does little to distinguish itself from sibling tools by 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?

There is no explicit statement of when an agent should call this tool versus contact_trading_desk or any other sibling. The description indirectly implies an agent calls it to inspect the x402 declaration, but it gives no exclusions, no prerequisites, and no guidance for choosing it over alternatives.

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 the full burden. It does well: it discloses the behavior (typed, identified, ticketed, human-signed), the routing (x-gsc-inbound address), and explicitly states a limitation ('No new write path here'). It even explains the relationship to the transaction MCP. This is solid transparency for a zero-parameter tool.

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, all of which carry meaning. The purpose is front-loaded, and the necessary qualifiers (no new write path, human-signed) are packed tightly. The only slight redundancy is the title-phrasing ('agents' door') which adds little, but the description itself is efficient and skimmable.

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 and no annotations, the description fully explains the service being exposed, its interaction model, and its constraints. An agent can understand how to use it, where it routes, and what it does. Missing details like exact payload syntax and response format are acceptable given the absence of parameters and the nature of the tool as a policy statement rather than a function 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?

The tool has zero parameters, so the schema covers 100% of nothing and imposes no burden on the description. The description doesn't need to document any parameters, and it doesn't attempt to. It does mention the message types (RFQ, terms request, escalation) which gives the agent context on how it would be used, effectively compensating for the absence of a structured envelope.

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 is specific about the tool's purpose: it describes how an agent lodges specific message types (RFQ, terms request, escalation) with a specific identified recipient (GreenCore Solutions Corp), using a specific protocol (IA-MESSAGE). It clearly distinguishes itself from the sibling tools by noting it 'points at the existing door' rather than being a new write path, and the sibling list contains no other messaging tools.

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

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

The description gives clear context on what the tool is for (lodging typed, ticketed, human-signed messages) but doesn't explicitly state when to use this versus alternatives. There's no guidance on when NOT to use it, though the note 'No new write path here' and pointing to the x-gsc-inbound address and transaction MCP imply outside the normal flow. Without explicit alternative names or conditions, the guidance is implied 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?

With no annotations, the description carries the full burden. It discloses useful context: data is 'live', it is a 25-market graph surface, it returns names (not records) from the SPARKS depth surface, and that brands/makers/banners 'are separate registries — never summed'. However it never states read-only semantics, auth/permission requirements, or pagination behavior beyond the schema's limit default, leaving real gaps.

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 text is heavily padded with marketing language and figures ('353,532 makers · 8,619 retail banners', a URL to a statement of record) that do not help an agent invoke the tool. The actual operational content — search brands, then verify with get_brand — is diluted and not 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?

There is no output schema, so the description must explain returns; it does say brand names come back from the SPARKS depth surface, which is the minimum needed. But it omits result shape, pagination/truncation behavior, and total-count semantics, so it is adequate rather than 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?

Schema description coverage is 100% (all three params documented, including market codes and the limit default), so the baseline is 3. The description adds only the '25 markets' framing for the market parameter and reinforces the registry separation, which is marginal beyond what the schema already provides.

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 clear verb+resource ('search the brands the CPG Knowledge Graph covers in one of 25 markets') and identifies the return ('brand names'), while distinguishing itself from siblings by positioning get_brand and get_brand_identifiers as follow-on verification steps. The framing is buried in marketing prose ('leaves with a brand it can act on — found, verified, and answerable'), but the core purpose is 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?

It lays out an explicit workflow — this tool is 'Step 1 — FOUND', then 'call get_brand to verify, get_brand_identifiers for the identifier policy' — which tells the agent where this sits relative to alternatives. It lacks explicit when-not-to-use guidance, so it falls short of a 5.

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