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 provided, the description carries the burden of behavioral disclosure. It does so well by explaining the tier semantics, the return of supply/demand context, and the explicit exclusions for prices, stock, and terms. It is slightly vague about 'both doors' and does not state not-found behavior, but for a simple verification tool this is solid 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?

Two sentences with no filler: front-loaded with the core verification question, then the tier scale, return contents, and exclusions. Every phrase earns its place, and the structure makes the most important information immediately visible.

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 2-parameter tool with no output schema and no annotations, the description covers the return value, tier semantics, and explicit non-coverage. The unexplained 'both doors to act' phrase and the lack of a not-found case keep it from being 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?

Schema description coverage is 100%, so the baseline of 3 applies. The description adds no new meaning about the brand or market parameters beyond what the schema already documents, but it also does not need to.

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?

Names a specific verb (verify), a specific resource (one brand on the CPG Knowledge Graph for a market), and the key distinguishing output (SPARKS completeness tier). This clearly separates it from sibling tools like search_brands or get_brand_identifiers, and the exclusions reinforce its scope.

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 'Step 2 — VERIFIED' framing and the explicit statement that prices, stock, and terms are not returned give a clear sense of when and when not to use the tool. It does not name the sibling tools that should be used instead, so the guidance is implied rather than fully explicit.

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

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

With no annotations, the description carries the full behavioral disclosure burden. It does reveal a meaningful constraint: only GSC-owned 990832300xxx identifiers can be returned, and third-party GTINs are excluded. It also notes the demo brand carries GSC's rail GTIN. But it does not describe actual call behavior such as how brand/market are matched, what happens on no match, or what the response shape 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?

The description is compact: three sentences, each with a distinct job — state the identifier policy, route GTIN-holders to alternatives, and add the demo-brand example. The key exclusion is front-loaded. Some vocabulary is cryptic ('rail GTIN', 'entity universe'), but there is no filler and the structure is efficient.

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

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

The description covers policy scope, the exclusion of third-party GTINs, and alternative resolution paths, while the schema covers parameters. However, there is no output schema and the description does not explicitly say what a successful response contains or how the optional market parameter behaves. For a read-only two-parameter tool this is adequate, but it leaves some invocation and return behavior to inference.

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 documents both parameters, so the baseline is 3. The description adds domain context about GSC's identifier block and the demo brand, but it does not clarify how 'brand' or 'market' affect the lookup beyond what the schema states. It neither contradicts nor substantially extends the schema's parameter descriptions.

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

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

The description clearly communicates the identifier policy scope — GSC-only 990832300xxx identifiers, never third-party GTINs — and it names alternatives for GTIN resolution. However, it never explicitly states what get_brand_identifiers does with its brand/market parameters; there is no clear 'returns', 'gets', or 'resolves' verb tied to the tool itself. The title supplies the missing intent, but the description alone reads more like a policy note than a tool-purpose statement.

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 an explicit when-not scenario: if the caller already holds a GTIN, use resolve_gtin, resolve_sparks, or check_eligibility on the CPG Knowledge Graph instead. It also states third-party GTINs never appear here, which prevents misuse. It does not explicitly state the positive condition ('use this when you need the brand's marketplace-published identifiers'), though that is strongly implied by the tool name and schema.

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 behavioral disclosure. It does add meaningful scale context (counts across four dimensions, classification on SPARKS) and hints at a read-oriented nature ('14 read tools over MCP'). However, 'data surface' is abstract jargon that doesn't operationally explain what happens when called — what is returned, what SPARKS classification means for the agent, or what the entry point into this 'surface' actually delivers.

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, with the most concrete information (the stats) front-loaded first. The second sentence is dense but relatively efficient. It loses a point because phrasing like 'source of truth for AI agents' and 'data surface every marketplace answer resolves against' is semi-redundant marketing language — both communicate approximately the same authoritative-role claim.

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 0-parameter tool with no output schema, the definitional burden is modest, and the description provides scale and conceptual anchoring that a bare 'get the CPG knowledge graph' would lack. However, the abstract 'data surface' language leaves genuine uncertainty about the return format or behavior of such a large graph — does it return everything, a summary, or a pointer? Without annotations or an output schema, the description could have done more to set expectations about invocation results.

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, the description has no parameter mechanics to clarify. The rubric establishes a baseline of 4 for 0-parameter tools, and the description earns it by adding context about what the resulting data contains (the entity types and scale an agent can expect). It contributes no misleading parameter information, which would be the only way to score lower at this baseline.

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 (the CPG Knowledge Graph) and its specific contents through stats (24,126 brands, 5,928 makers, etc.), which is far from a tautology. However, it relies on the verb in the tool's NAME ('get') and abstract nouns like 'data surface' rather than stating an action directly. The role 'every marketplace answer resolves against' implies reading/accessing, but purpose is inferred more than stated.

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?

Phrases like 'source of truth' and 'data surface every marketplace answer resolves against' imply this is the authoritative/primary read path for CPG data, offering weak contextual guidance. However, there is no explicit when-to-use versus the sibling tools (get_brand, search_brands, get_radar), no exclusions, and no mention of alternatives. The usage context is implied through marketing-style language rather than stated 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 the full burden of behavioral disclosure. It explains the data source (public registry data), the sorting (by posture), and the special meaning of 'unassessed' (no data collected yet). It also clarifies that it is 'wire evidence only' and deliberately neutral. However, it does not disclose what happens when the 'market' parameter is omitted (though the schema does), nor does it describe the output format beyond the posture field, which is a gap for a tool without an output schema.

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 three sentences long with no filler. The first sentence states the core function and content, the second clarifies neutrality, and the third explains the meaning of the posture field. Each sentence earns its place, and the key information is front-loaded. It is slightly longer than strictly necessary but still 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 simple tool with one optional parameter, the description covers the essential context: what it returns (retail banners), the taxonomy (fixed), the sorting, and the semantic of 'unassessed'. The schema handles the parameter details, and the description clarifies the data's nature (public registry, wire evidence). An agent has enough to call it correctly, though the lack of an output schema is mitigated by the description's mention of the posture field.

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 provides 100% coverage for the single 'market' parameter, including guidance to omit it for a 50-market summary. The description adds no new semantics about the parameter itself—it only describes the overall output. Since the schema is comprehensive, a baseline of 3 is appropriate; the description does not need to elaborate further.

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 that the tool returns retail banners per market from the CPG Knowledge Graph, each with an agentic-posture field, sorted by it. It uses specific vocabulary ('demand side', 'retail banners', 'public registry data') and a verb ('get' implied). While it doesn't explicitly name a sibling, the 'neutral by design' phrasing distinguishes it from potentially more sales-oriented tools in the set.

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 this tool by emphasizing neutrality ('no tiers, no pursuit language, no relationship claims'), suggesting that if an agent needs objective, wire-evidence-based data, this is the right choice. However, it does not explicitly name an alternative tool or provide exclusion criteria beyond the neutral stance, leaving some inference 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?

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 full burden. It explicitly states no price is published, no 402 challenge is issued, and everything is free in v1, which reveals it is a non-transactional, read-only capability. It also scopes behavior to 'nothing else,' so the agent knows there are no side effects or costs.

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 sentence that front-loads the core purpose ('network, asset, status') and then adds clarifying disclaimers. It is efficient and well-structured, though slightly lengthy with the extra details on free vs. price.

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 getter with no parameters and no output schema, the description is complete. It states exactly what data is returned and clarifies the absence of pricing or challenges. There is no missing information an agent would need to call it correctly.

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

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

There are zero parameters and the schema is trivially empty (100% coverage). The description adds value by explaining what the response will contain (network, asset, status), exceeding the baseline of 4 for zero-parameter tools.

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 it declares what GSC-Marketplace says about x402, specifying the three fields (network, asset, status) and explicitly saying 'nothing else.' This is a specific verb-resource combination that distinguishes it from siblings, which focus on other entities.

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

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

The description provides context about what the tool does (returns capability declaration) but does not explicitly state when to use it versus alternatives. It implies it is for x402-related info but doesn't offer exclusions or name alternatives. The 'free in v1' note hints at usage conditions but not tool 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?

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 that the service is 'live, free,' returns brand names from a specific depth surface, and provides data counts. It also includes an important caveat about separate registries (brands, makers, banners never summed). This is more than minimal, though it omits details like pagination, error behavior, or rate limits, which are common for search tools.

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 moderately long but well-structured with a clear 'Step 1' framing and next-step callouts. The opening sentence is somewhat indirect ('When a marketplace or retail sourcing agent calls...') but quickly pivots to actionable instructions. It is efficiently organized despite some redundancy in the counts.

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 no output schema, the description sufficiently explains what the tool returns (brand names) and provides supporting context (data volumes, market count, separate registries). It also directs the user to follow-up tools for verification and identifiers. It lacks explicit return format or pagination details, but those are not critical for a search tool's 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?

Schema coverage is 100% for all three parameters (market, limit, query), so the baseline is 3. The description adds context about the market scope (50 markets) but does not provide additional semantics for limit or query beyond what the schema already specifies. It reinforces the market parameter meaning but adds little value for the others.

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 explicitly states the tool searches brands in the CPG Knowledge Graph across 50 markets, identifying this as the 'FOUND' step. It clearly differentiates from siblings by directing to get_brand for verification and get_brand_identifiers for identifier policy, making the purpose distinct and actionable.

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 provides explicit usage guidance by stating this is the 'Step 1 — FOUND' action and names the next steps: 'then call get_brand to verify, get_brand_identifiers for the identifier policy.' It also mentions instant messaging or human-in-the-loop trading desk as possible follow-ups, giving clear context on when to use this tool within a workflow.

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