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 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 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?

No annotations are provided, so the description carries the behavioral burden. It discloses that the tool returns only brand names from the SPARKS depth surface, operates across 50 live markets, and that brands, makers, and banners are separate registries that must not be summed. It stops short of describing pagination, rate limits, or exact output format, but the core behavior 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?

The description is organized around a Step 1 label and includes useful scale figures and an important registry caveat. The opening sentence is somewhat promotional but still conveys next-step context; overall there is little wasted text.

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 search tool with three schema-documented parameters and no output schema, the description provides enough orientation: what it returns, what market scope is expected, and what downstream tools to use. An explicit note on result format or pagination would improve completeness, but the description covers the essentials.

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 all three parameters are already documented at the schema level. The description adds only high-level context like the 50-market scope, not additional parameter-level meaning, so the baseline 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?

States a specific verb-resource pair: search brands within the CPG Knowledge Graph for one of 50 markets. It explicitly says it returns brand names and positions itself as Step 1, clearly distinguishing it from the lookup siblings get_brand and get_brand_identifiers.

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?

Provides a concrete workflow: search first, then call get_brand to verify and get_brand_identifiers for identifier policy. It frames the intended caller ('marketplace or retail sourcing agent') and gives next steps, though it does not enumerate explicit exclusion cases.

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