MCP CPG Knowledge Graph

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

No annotations are provided, so the description must convey behavioral traits. 'Check whether' indicates a read-only query, but it does not explicitly state that the operation is non-destructive or what side effects exist. An output schema exists, but the description could still add context about return format.

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 fluff. It efficiently communicates 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?

Given the simplicity of the tool and the existence of an output schema, the description is fairly complete. It covers the what and the key inputs, though parameter details are missing. The context signals indicate a straightforward eligibility check.

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 has 0% coverage, so the description must compensate. It provides general context (GTIN, banner, country) but does not specify formats or constraints. The names are somewhat self-explanatory, but more detail would help avoid incorrect usage.

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 verb 'Check whether' and the resource 'GTIN can ship to a specific retailer banner in a country.' It distinguishes from sibling tools like count_gtin_coverage or find_retailers, as none of them perform this specific eligibility check.

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 that the tool should be used when determining shipping eligibility, but it does not provide explicit guidance on when not to use it or mention alternatives. The context is clear but lacks exclusion criteria.

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 transparency. It mentions entities covered but does not disclose key behavioral traits such as whether the statistics are counts, percentages, or raw numbers, nor does it mention performance, authentication requirements, or whether it aggregates across all data. This lack of detail could lead to misuse.

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

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

The description is a single sentence that communicates the core purpose without redundancy. It is appropriately sized for a tool with no parameters, and every word adds value. There is no wasted content.

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 parameters and an output schema (which handles return values), the description is minimally adequate but lacks completeness. It does not specify whether the output is aggregated counts or detailed breakdowns, leaving ambiguity about what 'coverage statistics' means. A more complete description would clarify the nature of the statistics (e.g., 'Returns counts of distinct GTINs, nodes, makers, and retailers') to avoid confusion.

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 no parameters, and schema coverage is 100% (as there are no parameters). The description does not need to add parameter semantics beyond the schema. Per the rubric, 0 parameters yields a baseline of 4.

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 'Global coverage statistics: GTINs, nodes, makers (supply), retailers (demand)' clearly indicates the tool provides aggregate statistics about coverage across distinct entities. The verb 'count' in the name is reinforced by the intent, though the description does not explicitly state that counts are returned. It distinguishes from siblings by focusing on global aggregates.

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 does not provide any guidance on when to use this tool versus sibling tools. Siblings like 'find_makers', 'find_retailers', or 'resolve_gtin' serve different purposes, but the description fails to explain that this tool is for high-level coverage stats rather than specific lookups or searches.

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 provided, so description must disclose behavior fully. It only states it is a search with filters, but lacks details on pagination, default limit, completeness of results, or read-only nature.

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?

Single sentence, no filler, key information front-loaded. Every word adds value.

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?

Output schema exists, so return values need no explanation. However, with 5 parameters and no schema descriptions, the description could better explain parameter usage or search behavior. Adequate but not thorough.

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 has 0% description coverage. Description lists four filter parameters (segment, region, node, has_website) but does not explain their meaning or allowed values; the limit parameter is not mentioned. Partial improvement but insufficient depth.

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 'Global cross-node maker (supply) search' with specific filters, distinguishing it from sibling tools like 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?

No explicit guidance on when to use this tool versus alternatives. The description implies it is for searching makers globally, but does not mention when not to use or suggest other 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?

No annotations provided, and description does not disclose behavioral traits like read-only nature, authentication needs, or pagination behavior. The phrase 'global cross-node' is vague.

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?

Single sentence is concise and front-loaded with purpose. Could be split for clarity, but overall efficient.

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

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

Despite having an output schema, the description fails to explain return behavior, pagination, or error conditions. With 4 optional parameters, more context is needed 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?

Description mentions three filters (region, node, parent_banner) which correspond to three parameters, adding some meaning beyond the schema. However, 'limit' is omitted and no parameter details are given.

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?

Description clearly states it's a search for retailers by region, node, or parent_banner, differentiating it from sibling tools like find_makers or list_brands_by_node. However, 'demand' is ambiguous.

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 on when to use this tool versus siblings like find_makers or list_brands_by_node. The agent must infer usage 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?

With no annotations provided, the description fully discloses behavioral traits: it returns a stored tier flag (not computed), the meaning of tier values, and that it never returns pack/size. This gives a clear understanding of what the tool does and its limitations.

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 concise, with a clear main sentence and additional details on tier values and constraints. It is front-loaded with the purpose. Minor formatting (newlines) does not hinder readability.

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 presence of an output schema, the description adequately explains return values (100, 8, floor). However, it lacks parameter semantics, which is a gap for a tool with two required parameters. This reduces completeness for an agent to know how 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?

Schema coverage is 0%, so the description must compensate. It mentions 'brand in a market' which hints at the parameters brand and node, but it does not define what node represents (market?) or clarify the format/constraints of brand and node strings. This adds minimal value beyond the raw 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 it returns a 'SPARKS completeness tier for a brand in a market' and explains the three possible values (100, 8, floor). It also explicitly says it returns a stored flag and does not compute a score or return a pack/size, differentiating it from sibling tools like resolve_sparks or count_gtin_coverage.

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 useful guidance on what the tool does NOT do ('do NOT compute a score. Never returns a pack/size'), which helps an agent avoid misuse. However, it does not explicitly state when to use this tool over alternatives, such as when to prefer get_kernel over resolve_sparks or node_market, leaving some ambiguity.

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 disclosure burden. It mentions the input zero-padding behavior, but does not disclose destructive potential, rate limits, or authentication needs. The read-only nature is implied but not stated explicitly.

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 15-word sentence with no filler. It is front-loaded with the verb and resource, and every word contributes to understanding the tool's purpose and input behavior.

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 there is an output schema (not shown), the description appropriately omits return value details. It covers the input transformation and the specific model. However, it could be more complete by clarifying how this tool fits among the many sibling GTIN 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?

The schema has 0% description coverage for the single 'gtin' parameter. The description adds valuable meaning by explaining it is a GTIN and that it gets zero-padded to 14 digits, which goes well beyond the bare schema definition.

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 verb 'Return' and the resource 'full ACM-68000 signal chain', and specifies the input GTIN. It provides some differentiation by naming a specific model, but does not explicitly distinguish 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?

The description implies usage when the ACM-68000 signal chain is needed for a GTIN, but provides no explicit scenarios, prerequisites, or when-not-to-use. It does not mention alternatives among the 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?

No annotations are provided, so the description alone must convey behavioral traits. It mentions 'Coverage only — no pack/size values,' which sets expectations about output scope, but it does not disclose whether the operation is read-only, whether results are paginated, or any other behavioral characteristics. The jargon 'SPARKS depth surface' is unexplained, reducing 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 extremely concise (two sentences) and front-loaded, starting with the core function. Every sentence adds value: the first states the domain ('SPARKS depth surface') and purpose, the second clarifies the query scope and limits. No redundant or irrelevant 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?

Given the tool's simplicity (one parameter, no annotations, output schema exists), the description covers the basic purpose and output scope. However, it relies on domain-specific jargon ('SPARKS', 'sovereign market') without explanation, and does not mention that the output schema details the return structure. For a straightforward list tool, it is minimally adequate but lacks completeness for agents unfamiliar with the domain.

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 description mentions the parameter 'node' implicitly by using '[node]' in the context of 'Answers ‘what brands do you know in [node]’', indicating it represents a sovereign market. However, it provides no explicit type, format, or constraints beyond what the schema gives (a required string). With 0% schema description coverage, the description partially compensates by relating the parameter to the query, but lacks detail.

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 lists distinct brands for a given node, answering 'what brands do you know in [node]'. It uses a specific verb ('list') and resource ('brands by node'), which distinguishes it from sibling tools that focus on counts, GTINs, or resolution.

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 when-to-avoid guidance is provided. The phrase 'Coverage only — no pack/size values' implicitly tells the agent not to expect detailed product values, but it does not name alternative tools for those use cases. The description assumes domain knowledge (e.g., 'SPARKS depth surface') without clarifying when to choose this over siblings like 'node_market' or 'resolve_node'.

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?

Does not disclose whether the tool is read-only, idempotent, or any side effects. The mention of 'separate subqueries, never summed' is an internal implementation detail but does not communicate safety or behavior clearly.

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?

Very concise single sentence. However, the cryptic language reduces clarity; a slightly expanded description could be more helpful.

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 no parameters and an output schema, the description provides the key semantic meaning (nodes, GTIN, counts). However, it does not explain what 'sovereign nodes' or 'spine' mean, leaving ambiguity for agents unfamiliar with the domain.

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?

No parameters exist, so schema coverage is irrelevant per guidelines. Baseline 4 applies; the description adds no parameter info but is not required to.

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

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

Clearly states the resource (49 sovereign nodes) and the attributes returned (GS1 GTIN, maker and retailer counts). The purpose is discernible despite jargon like 'spine' and 'sovereign'.

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 on when to use this tool versus siblings like find_makers or find_retailers. No context about prerequisites or typical scenarios.

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 adds important behavioral context: the list is the foundational taxonomy and that BRAND is excluded. It implies a read-only operation without side effects.

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 concise sentences with no wasted words. First sentence defines the tool's output, second provides usage guidance and a key clarification.

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 all necessary context: what is returned, why it matters, and a common pitfall (BRAND vs type). 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?

No parameters exist; baseline for 0 parameters is 4. The description adds meaning by explaining the content and usage of the output, going 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?

Clearly states that the tool returns the 84 BPC product-type codes (SPARKS taxonomy) which the graph is structured on. Differentiates from siblings by highlighting its role as a taxonomy list, and clarifies that BRAND is not a type.

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 advises to validate a type against this list before a typed query, giving a clear use case. Does not explicitly contrast with sibling tools, but the context differentiates it as a reference 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?

The description discloses key behavior: counts are never summed, and same-node potential bridge pairs are included. However, no annotations are provided, and the description does not mention read-only status, side effects, or error conditions.

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 conveys the core purpose efficiently. However, it could be front-loaded with the tool's main function before 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?

Given one parameter and the presence of an output schema, the description covers the main outputs (counts and pairs). It is mostly complete but could clarify that the 'code' parameter refers to a node code.

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 'code' is not described in the input schema (0% coverage). The description implies it is a jurisdiction identifier but does not explicitly explain its meaning or format.

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

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

The description clearly states it is a 'Supply↔demand bridge' for one jurisdiction, providing counts of makers and retailers separately and potential bridge pairs. This is specific and distinguishes from siblings like 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 implies usage for a single jurisdiction but does not explicitly state when to use this tool over alternatives or provide exclusions. No guidance is given for when not to use it.

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 only mentions zero-padding of input. It does not disclose whether the operation is read-only, idempotent, requires authentication, has rate limits, or any side effects. This is insufficient for safe and accurate tool selection.

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 consists of two short, front-loaded sentences with no filler. Every sentence serves a purpose: the first states the core functionality, the second adds a critical input-handling detail. It is appropriately sized for the tool's simplicity.

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 existence of an output schema (not shown), the description does not need to detail return values. However, it lacks coverage of error conditions, edge cases (e.g., invalid GTIN), and does not relate to sibling tools. The minimalism is adequate for a straightforward resolver but leaves gaps for a tool with one parameter and no annotations.

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 add meaning beyond the schema. It does so by noting zero-padding to 14 digits, which clarifies expected input format. However, it does not explain what constitutes a valid GTIN, any constraints like length before padding, or the impact of invalid inputs, leaving ambiguity for a single 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 uses a specific verb 'resolve' and resource 'GTIN' and clearly states the output is a 'procurement readiness signal'. It also adds a useful behavioral detail, zero-padding, which enhances understanding. The purpose is clearly distinguished from sibling tools like resolve_node or resolve_sparks since they operate on different entities.

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

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

The description provides no guidance on when to use this tool versus alternatives (e.g., resolve_node, check_eligibility). It does not mention prerequisites, context, or situations where this tool is inappropriate. Without such guidance, the agent cannot effectively decide when to invoke it.

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 provided, so description bears full burden. It states what the tool does (resolve license, makers, retailers) but lacks any disclosure about side effects, permissions, or performance. Basic transparency is provided.

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?

Single sentence, front-loaded with key information. No wasted words.

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?

Output schema exists, so return values are covered elsewhere. However, given the tool resolves three distinct aspects, the description is minimal but functional. Missing explanation of the 'code' parameter reduces 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?

Schema description coverage is 0%; the description does not explain the only parameter 'code'. Without context, an agent cannot know what value to provide (e.g., node ID, GTIN). Fails to add 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?

Description clearly states verb 'resolve' and resource 'one node', and specifies exactly what it resolves (GS1 license, makers, retailers). This distinguishes it from sibling tools like find_makers or 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?

No explicit guidance on when to use versus alternatives. It implies bundling multiple pieces of information, but does not mention when to use find_makers or find_retailers separately.

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, and the description does not disclose whether the tool reads or writes, what side effects occur, or what the tool actually does. Terms like 'mint-on-activation' hint at registry mechanics but not tool 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 a single dense sentence, but it front-loads a registry specification rather than the tool's purpose. It is concise in length but sacrifices clarity, mixing jargon (SM-ECO-10060) with no explanation.

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 no annotations, one optional parameter, and an output schema, the description should clarify the scope of the operation and inputs. It fails to explain the two eras, what resolving a scope means, or the role of scope_id, leaving the agent unable to use 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?

The input schema has one optional parameter (scope_id) with zero description coverage. The tool description never mentions scope_id, how it controls behavior, or what happens when it's null.

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 'GSC Scoped Agents Registry' but never states what action the tool performs (e.g., resolve, lookup, register). It lacks a verb and does not explain how 'resolve_scope' relates to the registry, making the tool's purpose ambiguous.

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, no prerequisites, and no mention of alternative tools despite the presence of many siblings. The description only describes registry properties.

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 fully discloses key behaviors: zero-padding to 14 digits, branch-specific returns, that pack/size value is never returned, fail-closed brand match, and uncertainty handling.

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 highly concise and well-structured, using bullet-like formatting to convey complex branching logic without wasted words.

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?

Despite the tool's complexity, the description covers all major behaviors, including branch outcomes and fail-closed matching. An output schema is present, but the description still provides sufficient context for correct invocation.

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

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

The description adds meaning to the single 'gtin' parameter by specifying it is zero-padded to 14 digits, which goes beyond the schema's simple type definition. However, it could provide more detail on valid GTIN format.

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 defines the tool as a two-branch SPARKS resolver with specific details for each branch (GSC Territory/License GTIN vs third-party BPC GTIN). It distinguishes its behavior clearly from sibling tools like 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?

The description specifies when to use each branch based on GTIN type and mentions routing to Navigator, but does not explicitly state when not to use this tool versus alternatives like resolve_gtin.

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