Merchant Context

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 'free' and 'diagnostic' but does not disclose what the diagnostic entails, potential external requests, or return behavior, offering limited extra context beyond 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 short sentences efficiently convey purpose and usage guidance with no redundant words. Front-loaded with the primary action, making it easy to parse.

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 parameter, simple annotations, and no output schema, so the description is mostly adequate. However, it does not explain what the diagnostic returns or what 'diagnostic' covers, which could leave the agent guessing about result usage.

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 parameter merchant_url already has a clear description ('Public HTTPS merchant URL to check'). The tool description adds no additional semantics beyond the schema, 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 clearly states the tool runs a merchant-site diagnostic, which is a specific verb+resource. It distinguishes from siblings like compare_offers and search_merchants, but overlaps somewhat with inspect_merchant without explicit differentiation.

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 instructs agents to use resolve_merchant before relying on merchant facts or actions, providing a clear prerequisite and context. It does not exclude alternatives or state when not to use, but the guidance is actionable.

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

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

Annotations already convey read-only, open-world, idempotent, and non-destructive behavior. The description adds valuable behavioral nuances: it only uses sourced fields, preserves unknown values, and crucially states 'payment never changes order,' which hints at a side-effect guarantee not captured by annotations. This goes beyond the structured hints.

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, tightly packed sentence that front-loads the core action and resource. Every clause adds meaning (scope, field filter, unknown-value behavior, side-effect guarantee) with no filler or 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?

For a tool with simple inputs and strong annotations, the description covers the primary behavior and side-effect guarantees reasonably well. However, without an output schema, the description does not explain the return format or what 'compare' produces (e.g., a list, matrix, diff). It also omits any mention of client_id, leaving a small but noticeable completeness gap.

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

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

Schema description coverage is 0%, so the description must explain parameters. It only indirectly references merchant_urls with 'two or more merchants' but does not clarify URI format or the purpose of client_id. The description fails to compensate for the missing schema descriptions, leaving both parameters underspecified.

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 explicitly states the action ('Compare'), the target ('sourced offer fields'), and the scope ('from two or more merchants'), clearly distinguishing it from sibling tools like check_merchant or search_merchants. It also includes meaningful qualifiers ('only sourced', 'unknown values stay unknown') that sharpen 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?

The description implies when to use the tool: to compare offer data across multiple merchants. It does not explicitly mention alternatives, but the constraints ('only sourced offer fields', 'unknown values stay unknown') convey that it is not for filling gaps or modifying data. This is clear context though without explicit 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?

Annotations already establish readOnly, idempotent, and non-destructive behavior. The description adds useful context by indicating that the response includes 'current' state plus fields like 'authority', 'confirmation', 'expiry', 'retry rules', 'recovery', and 'attribution', giving the agent a clearer picture of what the read operation returns.

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, compact sentence that front-loads the verb 'Return' and efficiently enumerates the return fields. No wasted words or 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?

Without an output schema or parameter advice, the description is insufficient for an agent to know how the parameters map to the tool's behavior or when to invoke it. It lists output fields but does not connect them to input semantics or provide operational context.

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?

None of the five parameters (merchant_url, client_id, action_type, allowed_authority, human_confirmation_available) are explained in the description. With 0% schema description coverage, the description does nothing to compensate, leaving parameter meaning and usage completely unspecified.

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

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

The description uses the specific verb 'Return' and identifies the resource as 'current merchant-owned action URLs' with a detailed list of attributes (exact inputs, authority, confirmation, expiry, retry rules, recovery, attribution). This clearly distinguishes it from sibling tools like search_merchants and preflight.

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 such as inspect_merchant or get_service_info. It lacks any mention of appropriate contexts, exclusions, or alternative 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 declare readOnlyHint=true, and the description aligns with a read-only 'Describe' action. The description adds minimal behavioral context beyond the annotation, such as the specific aspects covered (service, price, inspection checks). No contradictions, but no additional safety or permission details.

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, direct sentence that conveys the tool's purpose without extraneous words. It is well-structured 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?

For a tool with no parameters and no output schema, the description provides adequate context, listing key aspects of the service. However, terms like 'Merchant Context service' and 'inspection checks' could be further clarified, so a 4 rather than 5.

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 is empty with 0 parameters, so schema coverage is effectively 100%. The description doesn't need to explain parameters, and the baseline for 0 params is 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 uses 'Describe' as a specific verb targeting the Merchant Context service, explicitly listing service, price, and inspection checks. This clearly states the tool's function, though it doesn't differentiate from sibling tools like check_merchant or inspect_merchant, so not 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 provides no guidance on when to use this tool versus sibling tools. It neither mentions alternatives nor specifies scenarios, leaving the agent without usage context. This warrants a low score.

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?

Beyond the annotations (readOnlyHint=false, openWorldHint=true), the description adds valuable behavioral context: the operation is priced, requires displaying the price, and mandates explicit human approval. It does not contradict the annotations and provides workflow ordering that is not inferable from the schema alone.

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. Every clause contributes meaning: the alias relationship, the price display, and the approval prerequisite.

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 no output schema and 3 required params, but the description covers the essential human-approval workflow and references refresh_merchant for underlying behavior. It leaves some ambiguity about the exact return payload, but the alias pointer and clear process steps make it reasonably complete for this simple 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 description coverage is 100%, so the baseline is 3. The description reinforces the 'approved' parameter's role and adds the notion of showing a price, but does not clarify agent_id or merchant_url beyond their schema descriptions.

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

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

The description identifies the tool as 'Compatibility alias for refresh_merchant', providing a clear connection to an established sibling and conveying the core action. It adds the key requirements of showing the price and obtaining human approval, though it does not fully define what 'refresh merchant' entails on its own.

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 a clear procedural requirement: show the price and get explicit human approval first. However, it does not explain when to use this alias vs. refresh_merchant, nor does it mention any exclusions or alternatives beyond naming the canonical tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds some context about evaluating 'sourced intent constraints' and selecting a 'safe action', but it does not disclose potential side effects, authentication needs, or output characteristics beyond those annotations.

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

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

The description is a single sentence with no filler and is front-loaded with action verbs. However, terms like 'sourced intent constraints' and 'attribution' are cryptic and unexplained, slightly reducing clarity, but the compact structure is still 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?

With 11 parameters, no output schema, and 0% parameter coverage, a one-sentence overview is insufficient. The description gives a high-level process but omits return format, parameter semantics, and usage context, making it inadequate for reliable tool 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 input schema has 11 parameters with 0% schema description coverage, yet the description mentions none of them by name. Vague terms like 'intent constraints' and 'safe action' offer no concrete mapping to fields like action_type, allowed_authority, or max_stale_seconds, leaving the agent unable to infer parameter semantics.

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

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

The description names a specific multi-step process: resolve a merchant, evaluate intent constraints, select a safe action, state approval, and return attribution. This is more specific than a vague verb and helps distinguish the tool from siblings like get_safe_actions or resolve_merchant, though 'attribution' 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 is given about when to use this tool versus siblings such as resolve_merchant or get_safe_actions. The description implies a pre-action workflow but does not state explicit use cases, prerequisites, 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?

The description adds valuable behavioral context not present in annotations: the tool incurs a cost and requires explicit human approval before execution. Annotations already mark the operation as non-read-only and non-idempotent, so the description enhances transparency without contradicting annotations.

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

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

The description is highly concise: two sentences, no filler, and front-loaded with the core action. It wastes no words and clearly conveys the primary purpose and key precondition.

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 moderate complexity (3 params, no output schema), the description covers the essential aspects: paid refresh, price display, and approval. However, it does not describe the return value or post-conditions, leaving a minor gap for an agent to infer expected outputs.

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%, with each parameter (merchant_url, agent_id, approved) already described. The description reinforces the 'approved' parameter's purpose by mentioning 'explicit human approval', but does not add substantial new 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 states a specific action ('Pay for a fresh merchant inspection and cache refresh') with a clear resource (merchant) and outcome (cache refresh). It distinguishes itself from sibling tools like inspect_merchant by emphasizing the paid, refreshed nature and the requirement for human approval.

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 getting fresh merchant data (via payment) but does not explicitly compare to alternatives or provide when-not-to-use guidance. The approval requirement is clear, but there is no mention of when to prefer this over inspect_merchant or check_merchant.

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 this read-only, idempotent, safe, and open-world. The description adds the behavioral trait that data is 'cached' (likely stale) and includes 'freshness' information, which is beyond the annotations and useful for setting expectations. It does not contradict 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?

The description is two compact sentences, with the main capability front-loaded in the first sentence and usage guidance in the second. 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?

Despite the absence of an output schema, the description lists the types of data returned (identity, facts, offers, terms, freshness, safe actions) and provides a clear use case. It lacks details on return structure or error cases, but for a simple read-only cached lookup, it is adequately 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?

The schema already provides 100% coverage with descriptions for both parameters ('Stable, non-secret identifier' and 'Public HTTPS merchant URL'), so the description doesn't need to add much. It adds no additional parameter semantics, 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 clearly states a specific verb ('resolve') and lists the exact resources (merchant identity, sourced facts, offers, terms, freshness, safe actions), and notes it is 'cached' and 'free', distinguishing it from likely live-check alternatives among siblings.

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 says 'Call this before relying on merchant facts or starting an action,' providing clear contextual timing. However, it does not name alternative tools or specify when not to use it, so it lacks explicit exclusion guidance.

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

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

Annotations already declare read-only, open-world, idempotent, and non-destructive. The description supplements this with 'Payment and adoption never change order,' a specific ordering guarantee, and notes that the tool searches 'cached' records, implying data may be stale and freshness is a consideration. These traits are not captured by annotations, providing useful behavioral context.

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 the first front-loading the core purpose and the second adding a concise behavioral note. No filler or redundancy; every word earns its place.

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

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

With 10 optional parameters and no output schema, the tool is complex, yet the description gives only a high-level overview of search dimensions and a single ordering rule. It does not explain return values, pagination, default ordering, or the semantics of parameters like max_stale_seconds and client_id. Given the complexity, the description is notably underspecified for complete guidance.

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 only 10% (only client_id has a description), so the description's list of search dimensions (place, price, timing, policy, action support, freshness) adds semantic meaning that maps to many parameters (e.g., geography, maximum_price_amount, action_type, freshness). However, not all parameters are covered (e.g., max_stale_seconds, client_id) and 'sourced offer' is ambiguous, leaving gaps in understanding. The description provides high-level guidance but does not fully compensate for the missing schema descriptions.

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

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

The description clearly states 'Search cached merchant records by sourced offer, place, price, timing, policy, action support, and freshness,' identifying the action (search), resource (cached merchant records), and filter dimensions. It distinguishes from siblings like check_merchant and inspect_merchant by indicating it is a general search over cached data. The phrase 'Payment and adoption never change order' adds a specific scoping detail.

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 searching cached merchants by various filters, but provides no explicit guidance on when to use this tool versus sibling tools (e.g., inspect_merchant, resolve_merchant) or when not to use it. The reference to 'cached' hints at a distinction from live data, but this is not elaborated. No alternatives or exclusions are mentioned.

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