MCP CPG Knowledge Graph

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 implies a read-only check but never states it explicitly, and it does not disclose whether the operation has side effects, requires special authorization, or how edge cases (unknown GTIN, unsupported banner) are handled. The core behavior is described accurately but thinly.

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

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

A single sentence with no filler that front-loads the core action. It is appropriately brief and every word earns its place.

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

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

An output schema covers return values, and the three flat, required parameters keep this manageable. However, with no annotations and no usage guidance, an agent must guess at prerequisites and edge-case behavior. For a simple check tool this is passable but not rich.

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

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

Schema coverage is 0%, so the schema documents nothing beyond parameter names. The description loosely maps to the parameters (GTIN, banner, country) but does not clarify what a 'banner' is (retailer chain), the format of country_iso, or expected value domains. With zero schema coverage, the description should compensate and does not.

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

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

The description states a specific verb-resource pair ('Check whether a GTIN can ship') with a precise scope (to a specific retailer banner in a country). This clearly distinguishes the action from resolve_gtin, find_makers, and find_retailers. However, it does not explicitly name or contrast the overlapping sibling 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?

There is no guidance on when to use this tool versus its 13 siblings, such as resolve_gtin, get_signal_chain, or node_market. An agent has to infer that shipping-eligibility checks belong to this tool, but nothing states when it is the right choice, when it is not, or which alternative to prefer.

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 of disclosing behavior. It only names metric categories and supply/demand framing; it does not state that the operation is read-only, describe how coverage is computed, or mention any data-scope caveats. For a zero-parameter tool the risk is low, but the absence of behavioral detail is still a gap.

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

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

A single compact sentence that front-loads the core idea ('Global coverage statistics') and then enumerates the relevant facets. Every phrase earns its place, with no filler or repetition.

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 that the tool has no required parameters and an output schema is present, the description provides sufficient domain context for a caller to understand what the tool reports. It does not explain when to choose this over siblings, but that is a moderate gap rather than a fatal one for such a simple call signature.

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 parameters and 100% schema description coverage by construction, so there is no parameter documentation burden on the description. The baseline for zero parameters is 4, and no additional parameter context is necessary.

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

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

The description names a specific resource domain ('GTINs, nodes, makers, retailers') and a clear verb concept ('coverage statistics'), and distinguishes itself from sibling resolution/list tools by emphasizing global coverage. It could be slightly more explicit that it returns counts, but it is not vague or tautological.

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

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

No guidance is provided on when to use this tool vs. siblings like node_market, list_brands_by_node, or find_retailers. The 'Global' prefix implies a high-level overview, but there are no explicit alternatives, exclusions, or selection conditions.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It does state that the search is global and cross-node and enumerates the filter dimensions, which clarifies scope. However, it does not mention pagination, limit behavior, or read-only semantics, though 'search' implies a non-mutating operation.

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

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

The description is two short sentences that front-load the core purpose and then enumerate the filter dimensions. There is no filler, repetition, or unnecessary detail.

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 the fundamental operation and filters, and an output schema exists so return structure does not need explanation. Yet it lacks explicit usage guidance, mentions only four of five parameters, and gives no detail on how node or segment values are specified, leaving some ambiguity among the many sibling tools.

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 0% schema description coverage, the description must compensate. It explicitly identifies four of the five parameters as filters, giving the agent their role, and 'cross-node' adds context for the node parameter. However, limit is omitted and no value formats or allowed values for segment, region, or node are provided.

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 opens with a clear phrase 'Global cross-node maker (supply) search' that names the resource (makers) and the operation (search). It adds scope ('global cross-node') and domain ('supply'), distinguishing it from the sibling find_retailers without needing to inspect schemas.

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 'supply' qualifier and the existence of find_retailers imply this tool is for the supply side of the marketplace, but the description never explicitly says when to choose it over alternatives. There are no exclusions or alternate tool names, so an agent must infer the routing from context.

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

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

No annotations are provided, so the description must carry the full burden of behavioral disclosure. It does not state whether the operation is read-only, whether it has side effects, pagination behavior, or any performance constraints. The description merely restates the search purpose and filter options without revealing operational traits.

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, well-structured sentence that front-loads the core purpose and lists the filter dimensions immediately. There is no fluff or redundancy; every word earns its place.

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

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

While the output schema exists to define return values, the description is thin for a tool with four parameters and zero annotation or schema-level parameter docs. It does not explain filter semantics (exact match? wildcard?), the limit parameter, or how the tool behaves with nulls. It is acceptable for a simple search but leaves 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?

The schema has no property descriptions (0% coverage), so the description must compensate. It names three filter parameters (region, node, parent_banner) but omits limit entirely and gives no detail about value formats, matching semantics, or optionality. This is insufficient for an agent to construct correct calls without additional inference.

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 the tool performs a 'retailer (demand) search' across a 'global cross-node' scope. This clearly identifies the resource (retailers) and the operation (search), and the parenthetical '(demand)' distinguishes it from maker/producer searches. It is specific and avoids tautology.

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

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

No guidance is given on when to use this tool versus sibling tools like find_makers or check_eligibility. The description simply says what it does, leaving the agent to infer applicability. There are no exclusions, alternatives, or context hints.

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 does so well: it explains the stored-flag semantics, the meaning of each tier value, and the negative guarantee about pack/size. It also clarifies that the tool is a pure retrieval operation, not a computation. It does not discuss error behavior, but for a simple getter this is a solid 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 compact and front-loaded with the core purpose, followed by useful value semantics and usage constraints. Each sentence adds information, and it avoids unnecessary filler. Minor formatting artifacts like the stray space before the period prevent a perfect 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 description covers the return values, the default behavior, and what the tool does not return, which is strong given that an output schema exists. However, it leaves the meaning of the 'node' parameter somewhat implicit and does not clarify how this tool relates to sibling tools like resolve_sparks. For a low-complexity two-parameter getter, this is adequate but not fully complete.

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

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

Schema description coverage is 0%, so the description must compensate. It indirectly maps the two parameters by saying 'brand in a market,' suggesting brand maps to 'brand' and node maps to the market context. However, it never explicitly names 'node' or defines what a node is, leaving some ambiguity for a tool with no schema-level 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 identifies the tool as returning a SPARKS completeness tier for a brand in a market and explains the three possible values (100, 8, 'floor'). It does not just restate the name 'get_kernel' and gives the agent a concrete sense of what the tool returns. It does not explicitly differentiate from sibling tools like resolve_sparks, which keeps it from a 5.

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

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

The description gives clear usage context: it returns the stored tier flag and explicitly warns not to compute a score. It also states that the tool never returns a pack/size, which helps an agent avoid misuse. However, it does not mention alternatives or give explicit when-to-use versus when-not-to-use guidance relative to sibling tools.

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

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

With no annotations, the description carries the full behavioral burden. It does add useful input-normalization behavior ('zero-pads to 14') and implies a read-only operation via 'Return', but it does not disclose error behavior, permission requirements, or side effects. The presence of an output schema reduces the need to describe return structure.

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

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

The description is a single, front-loaded sentence with no wasted words. The parenthetical adds a functionally important normalization detail without bloating the 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 one-parameter lookup with an output schema, the description is minimally adequate. It covers what the tool returns and how the input is normalized, but it leaves out usage context, the meaning of the opaque domain term 'ACM-68000 signal chain', and any mention of when it should be preferred over sibling tools.

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

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

Schema coverage is 0%, so the description must compensate. It does identify the only parameter, gtin, and adds the zero-padding behavior, which clarifies the expected format. It still does not specify valid GTIN lengths or whether any additional formatting is expected beyond padding.

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 operation ('Return') and the resource ('full ACM-68000 signal chain for a GTIN'), which distinguishes it from siblings like get_kernel or resolve_gtin. However, it assumes domain knowledge of what an 'ACM-68000 signal chain' is, so it is not fully self-explanatory.

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

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

No guidance is given about when to use this tool versus siblings such as resolve_gtin, get_kernel, or count_gtin_coverage. The agent must infer usage from the tool name and the one-line description, with no exclusions or alternative routing.

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 disclosure burden. It does disclose a meaningful behavior: the result is coverage-only and excludes pack/size values. However, it does not discuss behavior for unknown nodes, market semantics, data freshness, or any access constraints, leaving the agent to infer from the 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 compact at two sentences and includes both the core purpose and an important limitation in the em-dash phrase. It is front-loaded with purpose, though the initial 'SPARKS depth surface' label is cryptic and could be replaced with plainer wording.

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 one-parameter tool with an output schema, the description covers the core query and return limitation. It lacks node format guidance and any routing relative to 13 siblings, so an agent may still be unsure which value to pass for 'node' or whether this is the best tool for a market-coverage question.

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

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

Schema coverage is 0%, so the description must explain the lone 'node' parameter. It does add context by framing node as a 'sovereign market' and using [node] in the question, but it does not specify expected format, identifier type, or valid market values. This partial compensation is adequate but not strong.

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

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

The description identifies the resource ('distinct brands SPARKS covers') and the exact question it answers ('what brands do you know in [node]'). It distinguishes itself from value-returning tools by adding 'Coverage only — no pack/size values,' though the opening phrase 'SPARKS depth surface' is jargon and no sibling is named.

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?

A clear use case is implied by the quoted question, but the description does not state when to prefer this over siblings such as count_gtin_coverage, node_market, or resolve_sparks. There are no explicit when-to-use or when-not-to-use conditions beyond 'coverage only.'

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 disclosure burden. It discloses a non-obvious aggregation rule ('separate subqueries, never summed') and fixes the result cardinality at 49, which prevents misuse. It does not mention ordering or response wrapping, but with no parameters and an output schema present, this is sufficient for a simple list operation.

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 with no filler. It front-loads the core subject, then adds the key fields and the critical 'never summed' caveat, earning every word.

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 list tool with an output schema, the description provides the essential context: what nodes are returned, what each item contains, and an important aggregation caveat. There are no meaningful gaps that would prevent an agent from invoking the tool 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 empty, so there is nothing for the description to clarify. The baseline for zero-parameter tools is 4, and the description correctly focuses on output semantics instead.

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 specifies the exact resource ('49 sovereign nodes') and the output attributes (GS1 GTIN, per-node maker and retailer counts), so an agent can tell what data this tool returns. It does not explicitly use a verb like 'lists' or name sibling alternatives, which prevents a perfect score, but the title and content make the purpose clear.

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

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

The description implies this is the tool for enumerating the 49 sovereign nodes and their counts, but it gives no explicit when-to-use guidance or exclusions. An agent must infer from context rather than receive instructions on when to prefer this over sibling tools.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It implies a read-only list operation and notes the scope (84 codes), but it does not state whether the list is static or dynamic, whether pagination is involved, or restate the absence of side effects. The description adds context about the taxonomy but falls short of explicit behavioral guarantees.

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

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

The description is two sentences, front-loaded with the core definition ('SPARKS taxonomy') and immediately followed by usage guidance. No filler or redundant phrasing; every sentence earns its place.

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

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

For a tool with no parameters and an existing output schema, the description is nearly complete. It explains what the list is, why it exists, and how to use it. The only minor gap is the lack of explicit mention that the tool returns the full list without additional input, but that is easily inferred.

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 is 4. The description does not need to elaborate on parameter semantics, and no gaps exist. It appropriately focuses on the output and usage rather than parameters.

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

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

The description states a specific action (list) and resource (SKU types), and clarifies that these are the 84 standing BPC product-type codes. It distinguishes the tool from siblings by emphasizing the taxonomy scope, though it does not explicitly name alternatives. The purpose is clear and not a tautology.

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 direct guidance: use this to validate a type before a typed query. It also includes a noteworthy exclusion (BRAND is a tier, not a type). While it doesn't explicitly mention when not to use it or alternatives, the usage context is clear and actionable.

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 disclosure burden. It does disclose a genuinely useful trait — 'two separate counts (never summed)' — plus the presence of same-node bridge pairs and the single-jurisdiction scope. It does not cover absent-data or error behavior, but the never-summed warning and scope constitute real behavioral value beyond a trivial statement.

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

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

A single dense sentence with zero filler; scope and the two key behavioral traits are front-loaded. Efficient and waste-free, though the shorthand and technical jargon ('bridge', 'same-node') make it marginally harder to parse than a plainer phrasing would.

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 output schema covers return format, lowering the bar. Remaining gaps: no provenance for `code`, no explicit differentiation from per-entity siblings, and 'same-node potential bridge pairs' is undefined. Adequate for tool selection but not fully self-contained.

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 schema description coverage at 0%, the description must document `code` and only implies it is a jurisdiction identifier via 'ONE jurisdiction'. It neither names the parameter explicitly, nor states its format or how to obtain valid values (e.g., via resolve_node or list_nodes siblings). This is only partial compensation for an undocumented parameter.

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

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

The description identifies a specific resource — maker/retailer counts plus potential bridge pairs for one jurisdiction — and its aggregate nature implicitly contrasts with entity-level siblings (find_makers, find_retailers). However, the metaphor ('bridge') and phrase 'same-node potential bridge pairs' are cryptic; the core intent is legible ('two separate counts per jurisdiction') but the wording keeps it from being crisp.

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

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

No explicit guidance on when to call this tool versus the siblings. It never names find_makers, find_retailers, or count_gtin_coverage, nor states a condition such as 'use when you need per-jurisdiction aggregates instead of entity-level lookups.' Usage is only implied by the phrase 'ONE jurisdiction', leaving the agent to infer selection on its own.

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 behavioral burden. It discloses the zero-padding behavior, which is useful, but does not state whether the operation is read-only, how invalid GTINs are handled, or what happens for inputs that cannot be resolved.

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 extremely concise, with two short sentences that front-load the core purpose and then add the key normalization detail. Every sentence earns its place with no redundant wording.

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 one-parameter tool with an output schema, the description covers the essential invocation detail: the GTIN input and the normalization rule. Since an output schema exists, the return shape does not need to be described, though a note on when to use it would improve completeness.

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

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

The schema has 0% parameter coverage, so the description must compensate. It adds meaningful semantic detail by explaining that the input is zero-padded to 14 digits, but it does not clarify accepted formats, length limits, or validation behavior for the gtin parameter.

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

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

The description states a specific action ('Resolve a GTIN') and a distinct outcome ('procurement readiness signal'), which clearly differentiates it from sibling resolve tools. 'Procurement readiness signal' is not fully defined, but the resource and purpose are unambiguous enough.

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 the many sibling tools such as resolve_node, resolve_scope, or resolve_sparks. The only usage-related detail is the zero-padding normalization behavior, but no selection criteria or exclusions are provided.

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 burden of behavioral disclosure. It does reveal the return scope (license, makers, retailers), but it does not state whether this operation is read-only, whether it performs external lookups, or what happens for unknown nodes. It is not misleading, but it is thin.

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?

One tight sentence that leads with the action and resource, then breaks the result into three parenthetical components. Every word adds value and there is no redundant restatement of the tool name.

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

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

The output schema likely covers return values, but the definition leaves usage context and parameter semantics under-specified. Given the large sibling list and no annotations, a short note on when to use this resolver versus the more specific find_* tools would make it contextually 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 coverage is 0%, and the description does not clarify what 'code' means, what format it should take, or how it relates to a node beyond the weak inference from 'one node.' With a single required parameter, even a short format hint or example would add meaning; none is provided.

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

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

The description uses a specific verb ('resolve') and specifies exactly what is included: GS1 license, makers (supply), and retailers (demand). This clearly distinguishes it from sibling tools like find_makers or find_retailers, which each cover only part of this 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 description implies this is the combined tool for resolving a single node's license, supply, and demand, but it never explicitly says when to choose it over find_makers/find_retailers or what to do if you only need one aspect. The 'one node' qualifier is helpful but is not a full routing statement.

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 mentions Era 1 standing and Era 2 mint-on-activation, but does not disclose side effects, permissions, failure behavior, or whether resolution is read-only. With no annotations, the description leaves the behavioral and safety profile largely undefined.

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 cryptic rather than usefully concise. The policy code SM-ECO-10060 and registry capacity facts do not earn their place because they do not help an agent select or invoke the tool correctly.

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?

Even with an output schema available, the description does not tie the optional parameter to the two registry eras, explain null behavior, or indicate what a successful scope resolution returns. The provided registry lore is insufficient for correct tool 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 sole parameter, scope_id, is described nowhere in the tool description. With 0% schema description coverage, the description needed to explain what scope_id represents and how null should be interpreted, but it does not.

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

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

The description names a registry and its era structure but never states what operation resolve_scope performs. It adds domain context to the title but does not distinguish the tool from sibling tools like resolve_gtin, resolve_node, or resolve_sparks.

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 sentence explains when this tool should be used, when it should not be used, or what alternatives exist. The registry-era details imply some selection logic, but the agent is left to guess which registry is relevant or when to call this tool.

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

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

With no annotations, the description carries full responsibility for behavioral disclosure. It is exceptionally thorough: zero-padding to 14, branch-specific outcomes (full license record vs. gated proof), explicit note that pack/size VALUE is never returned, routing to Navigator, and fail-closed brand matching with uncertainty represented as recognized:false. No annotation contradiction exists since annotations are absent.

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, moderately dense block but is logically structured into two branches with a note on brand matching. It front-loads the core purpose ('Two-branch SPARKS resolver') and then elaborates. Every sentence contributes information; there is no fluff or redundancy. Slightly dense, but appropriate for the complexity of the two-branch logic.

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 the tool has an output schema (context indicates has_output_schema=true), the description does not need to fully explain return shapes. It already specifies what Branch A returns (full license record) and what Branch B returns (gated proof with specific fields and exclusion of pack/size). It also covers failure semantics and routing. All necessary behavioral context is present, making it complete for an agent to invoke 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 input schema only defines a single required string 'gtin' with 0% description coverage. The description compensates by explaining that it is a GTIN that gets zero-padded to 14, and differentiates behavior based on the GTIN prefix (e.g., 990832300xxx). This adds meaningful semantic value beyond the bare schema, though it does not specify exact format constraints (like allowed characters) or give examples. Given the low schema coverage, the description does enough.

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 resolves SPARKS and distinguishes two branches (GSC versus third-party BPC GTINs). It specifies the resource (SPARKS) and the operation (resolver). It does not explicitly name a sibling tool to differentiate from, but the branch logic and the 'Route to Navigator' instruction make the purpose clear enough for an agent to select it correctly.

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 a clear trigger for when to use the tool: a GTIN that is either a GSC Territory/License GTIN (Branch A) or any third-party BPC GTIN (Branch B). It also notes fail-closed behavior and uncertainty handling. Although it doesn't explicitly list alternatives, the conditions effectively indicate which input types are appropriate, and the 'Route to Navigator' hint suggests a downstream action. Slight lack of explicit 'when not to use' guidance, but the branches define the scope well.

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