CPG Knowledge Graph

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description's 'Check whether' wording is consistent with them. The description adds no additional behavioral context beyond the check semantics, but with annotations covering the safety profile, the safety burden is already covered.

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

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

The description is a single, front-loaded sentence with no filler or redundant restatement of the title. Every word contributes to understanding the tool's purpose.

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 operation is simple, all required parameters are documented, an output schema exists, and annotations cover safety and idempotence. The description is sufficient for an agent to invoke the tool correctly; the main gap is the lack of explicit guidance about when to prefer sibling tools, though that is partly penalized in the usage dimension.

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%, and each parameter already has detailed documentation including GTIN normalization rules, exact banner naming, and country format. The description itself adds no additional parameter detail beyond what the schema already provides, 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?

The description uses a specific verb with a clear resource: 'Check whether a GTIN can ship to a specific retailer banner in a country.' This clearly separates it from sibling tools like resolve_gtin, find_retailers, or count_gtin_coverage, and the title reinforces the intent without ambiguity.

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 use context: use this when you need to determine eligibility for a GTIN against a specific banner in a country. It doesn't explicitly name alternatives or exclusions, but the intended scenario is immediately apparent from the sentence.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds that this is global coverage statistics spanning supply and demand, which adds some context beyond the annotations. However, it doesn't clarify whether the results are aggregates only or include per-node breakdowns, pagination, or time-dependency.

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 short sentence with zero filler. It front-loads 'Global coverage statistics' and immediately enumerates the meaningful dimensions in parenthetical detail. 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?

Given that there is an output schema, zero parameters, and annotations already cover the safety profile, the description is largely complete. It conveys the global scope and the supply/demand distinction. A minor gap is not explicitly stating that this is an aggregate overview rather than a per-entity lookup, but the sibling list and output schema help fill that in.

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 0 parameters, and schema description coverage is 100%, so there are no parameter semantics for the description to add. Per calibration, 0 params with full coverage earns a baseline 4; the description's mention of 'supply' and 'demand' provides meaningful context about what the global statistics represent.

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

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

The description states a clear verb+resource ('Global coverage statistics') and enumerates the specific dimensions (GTINs, nodes, makers, retailers), which distinguishes it from sibling tools like find_makers or find_retailers. However, it doesn't explicitly differentiate it from other statistics-like tools such as node_market or list_nodes, so it stops short of a 5.

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

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

The description implies usage for global supply/demand coverage analysis and distinguishes supply vs demand roles, but it doesn't explicitly state when to use this tool versus alternatives like find_makers or find_retailers. It provides no exclusions or alternative routing, so it's adequate but not 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?

Annotations already indicate readOnlyHint, idempotentHint, and destructiveHint false, so the safety profile is covered. The description adds the global scope and filterable dimensions but does not disclose additional behavior such as result ordering, default breadth when no filters are supplied, or any cross-node side effects; those are partially covered by the schema and 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 two short sentences with no filler: it states the global scope and then lists the available filters. All content is relevant and front-loaded.

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

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

All five parameters are optional and fully documented in the schema, the output schema exists, and annotations cover read/idempotent behavior. The description adds the necessary global cross-node context, making the tool complete enough 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?

Schema description coverage is 100%, and every parameter has a detailed description. The tool description only lists filter names that mirror the schema, adding no new semantic meaning beyond what the structured parameter descriptions already provide.

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

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

The description gives a specific verb and resource: 'Global cross-node maker (supply) search.' It clearly distinguishes this from sibling tools like find_retailers by identifying the resource as makers/supply butterfly and from node-scoped tools by emphasizing 'global cross-node.'

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

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

The description establishes a clear context: use this tool for cross-node maker searches with filters. It does not explicitly name alternatives or provide when-not conditions, so it falls short of a 5, but the intended usage is immediately understandable.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds the 'demand search' context and the filter dimensions, which is useful but not rich behavioral detail. It doesn't mention pagination, result ordering, or that filters are combined, but the schema covers the filter semantics. With annotations carrying the safety burden, a 3 is fair.

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

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

The description is two sentences with zero waste. The core purpose and scope are front-loaded, and the filter list is compact. 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?

For a read-only, idempotent search tool with a 100%-covered schema and an output schema present, the description is nearly complete. It could mention that filters are combinable or that the result is a list, but the output schema and annotations cover most of what an agent needs. A 4 is appropriate because the description is sufficient but not exhaustive.

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 schema already documents all four parameters with types, defaults, and examples. The description adds the phrase 'demand search' and lists the filter dimensions, but it doesn't add meaning beyond what the schema provides. Baseline 3 is correct when the schema does the heavy lifting.

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 ('find'), a resource ('retailers'), and a domain ('demand search'), and immediately distinguishes it from sibling tools by noting it is a 'global cross-node' search. It also lists the three filter dimensions (region, node, parent_banner), which clearly differentiates it from find_makers and other 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?

The description implies when to use this tool: when searching for retailers by region, node, or parent_banner. It does not explicitly state when not to use it or name alternatives, but the filter list and 'global cross-node' scope provide clear context. A 4 is appropriate because the usage context is clear but exclusions are not stated.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, and the description adds meaningful behavioral context: it returns only the stored flag, must not be used to compute, and always excludes pack/size results. This goes beyond what annotations alone convey without contradicting them.

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 every phrase earns its place: the tier semantics, the stored-flag nature, and the explicit exclusions. There is no filler or repetition of schema details.

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 read-only getter with two fully documented parameters, an output schema, and safety annotations, the description covers the essential return semantics, the possible values, and the key negative behavior. Nothing needed for correct invocation is missing.

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%: both 'brand' and 'node' are fully documented with format, case-insensitivity, and fail-closed behavior. The description's phrase 'brand in a market' maps to the two parameters but adds no additional parameter semantics beyond the schema.

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 what the tool does: it returns the stored SPARKS completeness tier for a brand in a market, enumerates the possible values, and explicitly distinguishes itself by saying it does not compute a score and never returns a pack/size. The verb is specific and the scope is defined.

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 for when to call it — retrieving the stored completeness tier — and when not to: 'do NOT compute a score' and 'Never returns a pack/size.' It does not name a specific sibling alternative, so it lacks explicit routing among the long sibling list.

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

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

Annotations already cover read-only, idempotent, non-destructive behavior, so the description does not need to restate safety. It adds the zero-padding behavioraisl, but that detail is also present in the schema parameter description, so the added value is limited.

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, front-loaded sentence conveys the operation, target resource, and canonicalization detail with no filler. 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?

Given a single parameter, a fully described schema, rich annotations, and an output schema, the description is sufficient for an agent to invoke the tool correctly. No critical return-value or side-effect information is missing.

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%, and the schema already explains GTIN format and zero-padding. The description repeats the zero-padding behavior but does not add meaningful information beyond the schema.

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 specific verb 'Return' and the resource 'ACM-68000 signal chain' for a GTIN. It is unambiguous about what the tool does, though it does not explicitly distinguish itself from siblings like get_kernel or resolve_gtin.

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 alternatives such as get_kernel or resolve_gtin. The description only states what it returns, not the conditions under which it should be preferred.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so safety is covered. The description adds value by specifying that only coverage is returned (no pack/size values) and that brands are distinct, which implies deduplication. This clarifies the output scope beyond the annotations and is consistent with them, so no contradiction.

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

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

The description is two sentences with zero fluff. It front-loads the core purpose, then adds the scope restriction in the second sentence. Every word earns its place, and there is no redundancy with the schema or annotations.

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's simplicity (one parameter), the presence of an output schema, and the rich annotations, the description covers all necessary information. It explains what the tool returns, what it doesn't, and how to frame the query. Nothing an agent needs to correctly invoke it is missing.

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 covers the 'node' parameter with 100% coverage, including format, case-insensitivity, and a reference to list_nodes for valid codes. The description does not add any additional parameter-level detail, so it does not exceed the baseline of 3 for a fully documented schema.

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 ('brands by node'), and clarifies it answers a concrete question: 'what brands do you know in [node]'. It distinguishes itself from siblings like find_makers or find_retailers by explicitly focusing on brand coverage within a sovereign market. The phrase 'distinct brands SPARKS covers' leaves no ambiguity about the tool's function.

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: use it to obtain brand coverage for a specific node. It also notes a key exclusion ('Coverage only — no pack/size values'), telling the agent what not to expect. However, it does not explicitly name alternative tools or conditions for choosing them, so it falls short of a 5 but is still unambiguous about the intended scenario.

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

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds useful context about the data: counts come from separate subqueries and are never summed, plus the notion of 'CLEAN' data. This enhances transparency beyond the 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?

A single, dense sentence that front-loads the primary resource ('49 sovereign nodes') and then lists the key attributes. No wasted words; every clause earns its place.

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

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

For a parameterless list tool with an output schema, the description covers the essential content. It explains the structure of the results and the key nuance about separate subqueries. It could mention pagination or ordering, but with no params and an output schema, it is reasonably 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?

There are zero parameters, so the description carries the full burden of explaining what the tool returns. It names the output fields (GS1 GTIN, maker counts, retailer counts) and clarifies they are separate, adding meaning beyond the empty schema.

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 returns the 49 sovereign nodes with GS1 GTIN and per-node maker/retailer counts. It specifies the resource and the fields, but does not explicitly differentiate from sibling tools like find_makers or find_retailers. Still, it is specific enough to infer 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?

No explicit guidance on when to use this tool versus alternatives. The description implies it lists all nodes, but does not mention exclusions or scenarios where siblings are preferred. An agent must infer usage from the name and context.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, covering safety. The description adds context about the taxonomy's structure and its purpose (validation), which goes beyond the annotations without contradicting them.

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 waste: the first defines the taxonomy and its scope, the second gives the intended use. The key information is front-loaded, and the parenthetical clarifies a common confusion.

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

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

For a zero-parameter read-only listing tool with an output schema, the description covers the tool's purpose, the content of the list, and its intended usage. Nothing essential is missing for an agent to invoke it correctly.

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

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

With zero parameters, the schema fully describes the input, so the description has no parameter burden. It doesn't add parameter details because none exist, which is appropriate and matches the baseline 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 states a specific resource (SPARKS taxonomy) and its role (the 84 standing BPC product-type codes), and clarifies that BRAND is not a type, distinguishing it from sibling tools like list_brands_by_node. The verb 'list' is implied by the name and title, but the description adds semantic precision.

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 explicitly advises validating a type against this list before a typed query, giving a clear usage context. It does not name specific alternatives or state when not to use it, but the BRAND clarification hints at avoiding confusion with brand-related 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds meaningful behavior beyond annotations: the counts are separate and never summed, and only same-node potential bridge pairs are included.

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 focused sentences with no wasted words. The first sentence explains output semantics, and the second provides usage guidance, with the 'ONE jurisdiction' constraint front-loaded.

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

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

The single parameter is fully documented, output schema exists, and annotations cover safety and scope. The description supplies the market-picture purpose and key output constraints, making the tool sufficiently 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?

Schema coverage is 100%, and the schema fully explains the code parameter: ISO 3166-1 alpha-2, case-insensitive, with list_nodes providing the valid codes. The description only reinforces that the tool targets one jurisdiction, adding no necessary parameter information beyond the schema.

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 (jurisdiction market picture) and precisely states what the tool returns: separate maker and retailer counts that are never summed, plus same-node bridge pairs. This clearly distinguishes it from sibling tools such as find_makers and find_retailers.

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 use case: 'use this first for "what does the market look like in X"' and scopes the tool to a single jurisdiction. It does name the trigger context well, though it does not explicitly enumerate alternatives or when to prefer them.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds the zero-padding normalization behavior, which is useful context beyond what annotations provide. It doesn't contradict any 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?

A single, front-loaded sentence that states the core purpose first and then the key behavioral detail. No fluff or repetition; 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?

For a simple one-parameter lookup tool with an output schema and strong annotations, the description is complete. The zero-padding detail is the only behavioral nuance not in annotations, and it is included. Return format is handled by the output schema.

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% and already documents the gtin parameter including zero-padding and an example. The description essentially summarizes the zero-padding behavior but doesn't add new semantic meaning beyond the schema.

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') with a specific resource ('GTIN') and outcome ('procurement readiness signal'), which clearly distinguishes it from sibling resolve_* tools targeting nodes, scopes, or sparks. It also notes the zero-padding behavior, adding further specificity.

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 purpose implies usage when you have a GTIN and need readiness information, but there is no explicit guidance on when to use this tool versus alternatives like check_eligibility or other resolve_* tools. No exclusions or sibling comparisons 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so no safety caveats are needed. The description adds context about the aggregate contents (license, supply, demand) but no additional behavioral traits such as rate limits, auth requirements, or edge cases. 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?

Two sentences, front-loaded with the core behavior and followed by usage context. Every phrase earns its place; 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?

For a one-parameter read-only resolver with an output schema, the description is largely complete: it explains what is resolved, the market-picture framing, and when to use it. The only gap is not addressing the relationship to sibling tools like node_market or find_makers/find_retailers, but that is not critical for calling this 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?

Schema coverage is 100%: the single code parameter is fully documented with format, examples, case-insensitivity, and source. The description adds no parameter details, but with full schema coverage 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?

The description states a specific action ('Resolve one node') and enumerates the result components (GS1 license, makers/supply, retailers/demand), which is far from a tautology. It frames the tool as 'the market-picture call' and 'use this first,' but it never explicitly names sibling alternatives like node_market, so differentiation is implied rather 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?

It gives clear when-to-use guidance: 'use this first for "what does the market look like in X"'. It does not provide when-not-to-use conditions or name alternative tools, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description is not required to restate safety. It adds useful registry context such as Era 1 founding standing, Era 2 mint-on-activation capacity, and the SM-ECO-10060 reference, but it does not describe operational behavior like result shape, errors, or registry lookup semantics, leaving it at a solid but not rich level.

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 one compact sentence with no filler and includes meaningful registry-scope details. It is slightly front-loaded toward registry context rather than the verb/action, but it earns its place by clarifying the two registry variants.

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

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

The tool has only one optional parameter, detailed schema documentation, explicit annotations, and an output schema, so the description does not need to explain return values. Combined with the registry-context sentence, the definition is complete enough for an agent to invoke the tool correctly, though it could still briefly note when to prefer this over sibling resolvers.

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 fully documents the single optional parameter with a detailed format for Era 1 and Era 2 IDs plus the omit-for-summary behavior, so schema coverage is 100%. The description adds no parameter explanation beyond that, which matches the baseline score for high 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 title 'Resolve scoped agent' and the parameter description 'Scoped agent id to resolve' together make the core action clear, and the description identifies the resource as the GSC Scoped Agents Registry across Era 1 and Era 2. However, the description itself does not use a strong action verb or explicitly differentiate this from sibling resolve tools like resolve_gtin or resolve_node, so it stops short of a 5.

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

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

The parameter schema gives useful guidance: provide a scoped agent ID to resolve or omit the parameter for the registry summary, which gives implied usage context. There is no explicit statement about when to choose this tool over the related resolver siblings, so the usage guidance remains mostly implicit 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?

Annotations already declare readOnly/idiempotent/non-destructive, so the description correctly focuses on added context: zero-padding to GTIN-14, the gated response shape, the 'pack/size VALUE is NEVER returned' guarantee, and fail-closed brand matching with uncertainty mapped to recognized:false. This is meaningful disclosure beyond the annotations, with no contradiction.

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?

Dense and efficient: branches are labeled, the never-returned value is front-loaded, and the fail-closed policy is a single closing clause. Slight deduction for jargon density ('SPARKS', 'GSC', 'BPC', 'Map Navigator') that may cost an agent a parse, but 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?

With an output schema present (so return values need no explanation) and a single fully-documented parameter, the description covers the two behavior branches, gating logic, and matching policy thoroughly. The only minor gap is not spelling out what the GALICIA license record in Branch A contains, though the output schema likely covers it.

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

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

Schema coverage is 100%, so the baseline is 3. The description restates the zero-padding behavior that the gtin parameter schema already documents, adding no new parameter semantics beyond what the schema and behavior descriptions provide. No deduction is warranted since the schema already carries the load.

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 and resource ('Two-branch SPARKS resolver') and precisely scopes the behavior with named Branch A (GSC Territory/License GTIN) and Branch B (third-party BPC GTIN) paths. Being SPARKS-specific cleanly differentiates it from siblings like resolve_gtin, resolve_node, and resolve_scope without requiring schema inspection.

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 two-branch breakdown effectively tells the agent which GTINs route where, and the explicit 'Route to Navigator' instruction gives downstream guidance. It doesn't name sibling alternatives directly (e.g., when to pick resolve_sparks over resolve_gtin), but the internal routing logic is clear enough for this one-parameter tool.

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