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

Annotations already indicate readOnlyHint=false. The description adds the 'Requires scope merchant_write' auth requirement and clarifies the effect (making purchasable again), adding value 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 sentences with no waste. The first sentence states the action, the second adds critical scope info. Front-loaded and 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?

For a simple tool with one parameter, plus annotations and an output schema (not shown but present), the description provides the core purpose and auth requirement. Lacks details on idempotency or error cases, but overall sufficient.

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 should describe parameters. It does not mention product_id, but it is the only required parameter and its role is obvious from the tool name. Adequate but could be explicit.

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: 'Make a product purchasable again.' This is a specific verb-resource combination that distinguishes it from siblings like deactivate_product (reverse action) and create_product (new creation).

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 a product needs to be reactivated for purchase, and the sibling deactivate_product provides contrast. However, it does not explicitly state when not to use or mention alternatives, but the context is clear enough.

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 indicate readOnlyHint=false (mutation) and openWorldHint=true (potential side effects). The description adds the scope requirement but does not elaborate on other behavioral traits like idempotency handling or payment page behavior beyond creation. It does not contradict 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 primary purpose, no wasted words. Efficient and clear.

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 complexity (10 parameters, nested objects, output schema), the description is minimal but sufficient for a creation tool. It covers core purpose and scope, but omits details like idempotency behavior or payment page flow, which are partially covered by schema. Adequate but not comprehensive.

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 parameters are already well-documented. The description adds no new meaning beyond the schema; the mention of 'BRL cents' is redundant with the param descriptions. 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 action ('Create') and resource ('Pix charge (checkout) with a hosted payment page'), distinguishing it from sibling tools like get_checkout and list_checkouts.

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 mentions required scope and currency unit, but lacks explicit guidance on when to use vs. alternatives such as get_checkout or simulate_checkout_payment. The context of sibling tools implies usage, but no direct comparisons are given.

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 behavioral context beyond annotations by stating 'Requires scope merchant_write', indicating authorization needs. It does not contradict annotations; the openWorldHint vs schema conflict is between annotations and schema, not the description.

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, front-loading the purpose. However, it could include brief parameter guidance without becoming verbose.

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

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

Given the tool has 10 parameters, an output schema, and nested objects, the description is too brief. It lacks explanation of return values, parameter constraints (e.g., BRL cents), and how to use it effectively.

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 40%, the description does not compensate by adding meaning to the parameters. It only mentions the scope requirement, leaving 10 parameters with no additional context.

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 'Create a reusable product (fixed-price checkout template with a public page)', specifying the verb 'create' and resource 'product'. It also mentions the required scope, distinguishing it from sibling tools like update_product or deactivate_product.

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 for creating a product and the required scope, but it does not explicitly state when not to use this tool or mention alternatives like update_product for existing products.

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 indicate write operation (readOnlyHint=false) and open-world side effects. The description adds specific behavioral traits: hiding from public page and blocking new checkouts. It does not disclose reversibility or impact on existing checkouts, but provides sufficient transparency 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 concise sentences: first states the effect, second states a prerequisite. No unnecessary words, front-loaded with key information.

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 and existing output schema, the description covers purpose and a requirement. It could mention reversibility (via activate_product) or effect on existing checkouts, but overall is adequate for the tool's simplicity.

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%, and the tool description does not explain the product_id parameter or its pattern. While the parameter is self-evident, the description adds no semantic value beyond the schema, resulting in a gap for parameter 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 the tool hides a product from the public page and blocks new checkouts, using a specific action verb and resource. It effectively distinguishes from siblings like activate_product and create_product.

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 mentions a required scope (merchant_write) but does not explicitly state when to use this tool versus alternatives or provide when-not-to-use guidance. Usage context is implied from the name and sibling tools, but lacks explicit direction.

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 the scope requirement ('merchant_read') beyond annotations (readOnlyHint, openWorldHint). No contradiction found; it supplements transparency about authorization.

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, extremely concise, front-loaded with purpose. No waste.

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 tool with annotations and output schema, the description is fully complete, covering purpose and required scope.

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 and 100% schema description coverage, the description does not need to add parameter details. Baseline 4 for trivial parameters.

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

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

The description clearly states 'Identify the authenticated merchant (connection test)', providing a specific verb and resource. It is distinct from sibling tools which focus on products and checkouts.

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 as a connection test and explicitly requires the 'merchant_read' scope, but does not mention when not to use it or suggest alternatives, though alternatives are not needed given its simplicity.

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 readOnlyHint and openWorldHint annotations, the description adds the scope requirement and owner view, 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?

One sentence, directly front-loading the purpose with 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?

With a single parameter and output schema present, the description is complete for the tool's simplicity.

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 description does not expand on the parameter beyond what the schema provides. Baseline score applies.

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 fetches a checkout by ID with owner view, distinguishing from sibling tools like list_checkouts.

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 lacks explicit guidance on when to use vs alternatives, though the scope requirement is stated. No when-not-to-use info.

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 openWorldHint=true. The description adds the scope requirement and clarifies the tool is read-only and cannot create deposits, providing additional behavioral 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 concise sentences front-load the purpose and include essential usage notes. No redundant information.

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 only one parameter and an existing output schema, the description covers purpose, scope, and limitations fully. No gaps remain.

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 description for deposit_id is informative. The tool description does not add further parameter details, but baseline 3 is appropriate since the schema already handles it.

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 'Read a deposit's status (read-only)', specifying the verb (read) and resource (deposit status). It is distinct from sibling tools like create_checkout or update_product.

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 states required scope ('wallet_read') and that this MCP cannot create deposits (that is the SDK, F3). This tells when to use it and provides a clear alternative, preventing misuse.

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 adds behavioral context by stating it returns checkout aggregates and requires a scope. No contradictions; openWorldHint is consistent.

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, well-formed sentence with no wasted words. Every part is essential.

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 presence of an output schema covers return values. Description mentions aggregates and scope, which is complete for a simple fetch tool. No gaps.

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

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

Schema description coverage is 100% as the only parameter (product_id) has a description and pattern. The tool description adds no extra parameter semantics beyond what the schema provides.

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 action (fetch), resource (product by id), and specialization (with checkout aggregates). It distinguishes from sibling tools like list_products (listing multiple) and activate/deactivate product (modifications).

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?

Specifies required scope ('merchant_read'), which is a prerequisite. Context is clear but doesn't explicitly exclude cases where alternatives are better (e.g., fetching without aggregates).

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 openWorldHint=true, indicating safe read-only behavior. The description adds value by stating 'read-only' explicitly, requiring the `wallet_read` scope, and clarifying that this MCP cannot create withdrawals (which aligns with the readOnlyHint). There is no contradiction. This adds useful behavioral 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?

The description is extremely concise—two short sentences that immediately convey the purpose, scope requirement, and a key behavioral constraint. Every word earns its place with no redundancy or fluff. It is front-loaded with the primary action.

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 low complexity (one required parameter, read-only, output schema present), the description adequately covers all needed context: what the tool does, its scope requirement, and what it does not do. The presence of an output schema means return values don't need to be described. No information gaps remain.

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 `withdrawal_id` that has a description including test mode format. The description does not add additional parameter semantics beyond what the schema provides. With high schema coverage, the baseline is 3, and the description does not elevate it.

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 reads a withdrawal's status (read-only). It uses the specific verb 'read' and identifies the resource as 'withdrawal status'. It also distinguishes from sibling tools by explicitly stating it cannot create withdrawals, which is a different action performed by other 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 provides clear when-to-use context (to read a withdrawal's status) and an explicit exclusion (cannot create withdrawals). It also mentions the required scope `wallet_read`. However, it does not name alternative tools for related operations like get_deposit_status, but the sibling list provides that context. The guidance is strong but not perfect.

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 and openWorldHint. The description adds the scope requirement but does not disclose additional behaviors like pagination defaults or ordering.

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 two sentences and no unnecessary words. It front-loads the main action and requirements.

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 7 optional parameters and a rich schema, the description provides minimal context. It lacks explanation of default behavior, response structure (though output schema exists), or filter examples.

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 only 43% schema description coverage, the description does not compensate by explaining any parameters. It only says 'with filters and pagination', adding no value 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 'List checkouts with filters and pagination', specifying the verb and resource. However, it does not explicitly differentiate from siblings like 'get_checkout' or 'list_product_checkouts'.

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 mentions required scope 'merchant_read', which is useful, but provides no guidance on when to use this tool vs alternatives like 'list_product_checkouts' or the single 'get_checkout'.

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 and openWorldHint. The description adds the scope requirement, which is valuable context beyond annotations. No contradictions.

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: one for purpose, one for scope. Efficient and front-loaded with key information, 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?

Has an output schema (not provided), but description omits parameter guidance for pagination and filtering. For a list tool with 4 parameters, this is a moderate gap. Agent would need to infer from schema defaults and enums.

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 should compensate by explaining parameters like product_id, limit, offset, and status. It does not, leaving the agent to rely solely on schema types and defaults, which may be insufficient for understanding filtering and pagination.

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 'List checkouts created from a product', specifying the verb, resource, and scope. It distinguishes from siblings like 'list_checkouts' (which lists all checkouts) and 'get_checkout'.

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 requires 'merchant_read' scope, providing a prerequisite. However, it does not explicitly state when to use this tool versus alternatives like 'list_checkouts' for all checkouts, though the product-specific focus implies 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?

Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds the authorization requirement (scope merchant_read) beyond annotations. No contradictions are present. The description moderately enhances 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 extremely concise: two sentences with no superfluous information. It front-loads the core purpose and includes the scope requirement efficiently.

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 (4 parameters, output schema exists), the description adequately covers the main behavior. It omits pagination details like limit defaults and offset usage, but the schema covers these. The scope requirement is the main extra 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?

Schema description coverage is 50% (2 of 4 parameters have descriptions). The description generically mentions 'filters and pagination' but does not elaborate on parameter details beyond what the schema provides. The baseline is 3 given the coverage level, and the description adds no extra semantic value.

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 'List products with filters and pagination', specifying the verb (list), resource (products), and distinct features (filters and pagination). It differentiates from sibling tools like list_checkouts and list_product_checkouts by focusing on products.

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 mentions 'Requires scope merchant_read', which provides authorization context. However, it does not explicitly state when to use this tool versus alternatives or provide exclusion criteria. Usage is implied but not fully elaborated.

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 a write operation (readOnlyHint=false), so the description adds value by stating the scope requirement and the clearing behavior when an empty array is passed. It does not contradict 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 efficient sentences: first explains purpose and behavior, second states authentication requirement. No unnecessary 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?

Given the presence of an output schema (not shown, but exists), the description covers the main behavior, parameter constraint, and scope. It doesn't mention error conditions but is adequate for agent 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?

Schema coverage is 100%, so baseline 3. The description repeats the clearing behavior already in the schema parameter description, but does not add 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 clearly states the tool reconciles the pinned product set/order on the public page, using the specific verb 'reconcile' and identifying the resource. It distinguishes from sibling tools like update_product or activate_product by focusing on bulk pin management.

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 mentions 'in one call' and 'empty array clears all', providing context for when to use it (replace all pins) versus using individual updates. It also notes the required scope. However, it does not explicitly discuss when not to use it or name 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 already indicate readOnlyHint=false (mutation). The description adds that marking as paid triggers 'checkout.completed' and errors on live checkouts. It mentions required scope but does not elaborate on idempotency or other 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?

The description is two concise sentences, front-loading the key action and constraints. No wasted words; every sentence 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?

For a simple sandbox simulation tool with one parameter, the description covers purpose, usage context (sandbox only), required scope, and expected error for live checkouts. The output schema exists but is not needed for 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 coverage is 100% with description and pattern for 'checkout_id.' The description reinforces that it must be a sandbox checkout, adding value beyond schema. No further parameter details needed.

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 'simulate payment' and the resource 'checkout,' specifically for sandbox environments. It distinguishes from siblings by noting that live checkouts return 'sandbox_only,' making the purpose unambiguous.

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 that the tool is for sandbox only and requires 'merchant_write' scope. It implies not to use on live checkouts by stating they return 'sandbox_only,' but does not explicitly list alternatives or when to use among 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?

The description adds the scope requirement beyond annotations, but does not disclose error handling or side effects, even though openWorldHint is true. Minimal additional 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?

Two sentences, front-loaded with core functionality, no redundant words. Efficient and clear.

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 lacks guidance on prerequisites, error scenarios, or state implications. For a mutation tool with many parameters, it is insufficient.

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 18%, and the description does not elaborate on any parameters. Critical for a 11-param tool with low 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 description clearly states the action 'partially update a product' and the resource, distinguishing it from sibling tools like create_product and activate_product.

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 mentions partial update and required scope, but does not explicitly specify when not to use it or compare to alternatives like activate_product or create_product.

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: true and openWorldHint: true. The description adds value by specifying the return shape ({ status, terminal, timed_out }), explaining timeout behavior ('returns timed_out:true rather than being killed'), and stating the required scope. This goes beyond annotations, though it doesn't detail progress emission mechanisms.

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 that cover purpose, behavior, return shape, and scope. Every sentence is necessary and front-loaded with the core action. 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?

Given the tool's simplicity (2 parameters, output schema present, annotations provided), the description covers the essential aspects: core behavior, return shape, timeout semantics, and required scope. It omits details about progress emission and error handling for invalid checkout_id, but these are minor gaps given the 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?

Schema coverage is 100%, so the schema already documents both parameters well. The description adds contextual meaning for timeout_seconds by clarifying that exceeding it returns timed_out:true instead of an error, which is valuable beyond the schema's description of min/max/default.

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: 'Wait server-side for a checkout to reach a terminal status, emitting progress.' It uses a specific verb ('wait') and resource ('checkout'), and distinguishes itself from sibling tools by explicitly contrasting with 'no client-side polling.' This makes the purpose unambiguous and distinct.

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 usage guidance by contrasting with polling ('One call — no client-side polling') and specifying the required scope ('merchant_read'). However, it does not explicitly list alternative tools or conditions when not to use this tool, which would enhance clarity.

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