Nashboard Merchants

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

No annotations are provided, so the description carries the full burden. It discloses return fields, default limit, and max rows, but does not explicitly state read-only nature or potential side effects, though 'list' implies a read 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?

Two concise sentences front-load the purpose and key constraints; every word earns its place with no redundancy.

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

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

Given no output schema, the description adequately explains what is returned (fields listed) and constraints (limit, country filter). Missing details like pagination or error responses are minor for a simple list tool.

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% with descriptions for all three parameters. The description adds value by listing returned fields and clarifying the row type, going slightly 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 tool lists location-tier rows for a brand_id, with an optional country filter, distinguishing it from sibling tools like lookup_merchant or resolve_operator_hierarchy.

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 needing location rows for a brand but provides no explicit guidance on when not to use it or how it compares to siblings; additional context like alternatives or exclusions would improve 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?

With no annotations, the description must fully convey behavior. It states what is returned but omits critical details: match behavior (exact vs fuzzy), case sensitivity, handling of partial names, and what happens when no match is found. This leaves significant ambiguity about how the tool operates.

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 action, then lists optional inputs and output details. Every word adds value, and there is no redundancy or clutter.

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 lacking an output schema, the description thoroughly explains the return value: hierarchy, 8 industry-code standards, and confidence tier. It does not cover match behavior, but the richness of the output description makes the tool's purpose and return value clear.

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% with good parameter descriptions. The tool description adds no new semantic information beyond the schema—only restates that name is required and country is optional. Given high schema coverage, a baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Look up a merchant by name (+ optional country)' and details the rich output (hierarchy, 8 industry-code standards, confidence tier). This distinguishes it from siblings like list_locations_for_brand or resolve_operator_hierarchy, which serve different lookup paths.

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 clear context: use this tool when you have a merchant name and optionally a country to get full hierarchy and codes. It lacks explicit exclusions or mention of alternatives, but the sibling tool names are listed for context, making the intended usage reasonably clear.

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 full burden. It describes the traversal logic ('walk parent_merchant_id upward') and return fields, but lacks details on error handling (e.g., invalid merchant_id, missing parent), performance implications, or authentication needs. This is minimal disclosure for a mutation-like resolution tool.

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

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

The description is a single sentence of 23 words, efficiently conveying the core action and expected outputs. There is no extraneous information 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 the tool's complexity (hierarchy resolution) and lack of output schema, the description covers the main behavior and return fields. However, it omits edge cases (e.g., merchant_id with no parent, multiple operators) and error conditions, leaving minor gaps for an agent.

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% with a single parameter, and the schema already describes 'merchants_global.id (UUIDv7) of any tier'. The description adds no new semantic information beyond 'any tier', so it meets the baseline but does not enhance understanding.

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

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

The description clearly states that the tool resolves the operator hierarchy by walking parent_merchant_id upward, returning brand, operator (with type and license territory), and ultimate_parent. It is specific and not a tautology, but it does not explicitly differentiate from sibling tools like lookup_merchant or list_locations_for_brand, which weakens the clarity.

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., lookup_merchant for a single merchant, or list_locations_for_brand for locations). It only states the input type, not the specific contexts or exclusions.

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 mentions the resolution process and reuse of retrieval stack but does not detail idempotency, auth needs, rate limits, or failure behavior beyond the basic function.

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 concise sentences that front-load the core function and are free of unnecessary detail, making it efficient for an AI agent.

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

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

Given no output schema, the description explains the return format of tuples. However, it lacks details on error handling, per-item output structure, or behavior when resolution fails, which would enhance completeness for a tool with array input.

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 covers 100% of parameters, and the description adds value by specifying the output format (tuples of merchant_id, product_global_id, confidence) and mentioning reuse of the retrieval stack, which is not in 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 tool resolves 1-50 receipt line item descriptions to (merchant_id, product_global_id, confidence) tuples via the global product graph, which is specific and distinct from sibling tools like list_locations_for_brand or lookup_merchant.

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 like lookup_merchant or resolve_operator_hierarchy. It mentions reusing the same retrieval stack as another endpoint but does not explain when to choose this tool over others.

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