ec-storefront

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

No annotations are provided, so the description carries full burden. It discloses ordering and special x402 behavior, but omits details about other statuses, response format, permissions, or rate limits.

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 that efficiently convey the tool's purpose, ordering, and a key special case. 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?

For a simple retrieval tool with one well-documented parameter and no output schema, the description is fairly complete. It covers ordering and a notable edge case, though it could mention other possible statuses.

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 single parameter (customer_address) is fully described in the schema with pattern and description. The tool description adds no additional semantic meaning beyond the schema.

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

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

The description clearly states the tool returns order history for a wallet address in newest order, with specific details about x402 orders. This distinguishes it from siblings like get_product or submit_payment.

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?

While the tool's purpose is clear, there is no explicit guidance on when to use vs. alternatives or when not to use it. Usage is implied by the name and context.

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

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

No annotations are provided, so the description carries full burden. It discloses the returned data and two critical flags to inspect. It implies a read-only operation but could mention idempotency or absence of 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 sentences, front-loaded with the action, and no wasted words. Perfectly concise for the information conveyed.

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 (1 param, no output schema), the description completely covers what the tool does and what it returns. It also provides actionable guidance for purchase flow.

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 one parameter described. The description adds usage context but no additional parameter semantics beyond the schema. Baseline 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 fetches details of a single product by product_id. It lists specific returned fields (price in JPYC, stock, SKU, variations, shipping requirement, supported chains), distinguishing it from sibling tools like list_products_in_shop.

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 to call this tool before purchase to check requires_shipping and has_variants. While it does not mention alternatives, the context is clear and helpful for the agent's decision.

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 disclose behavioral traits. It implies a read operation via '取得する' and specifies returned fields, but does not explicitly state that the tool is read-only, idempotent, or error handling behavior (e.g., if shop not found). This is sufficient for a simple GET but could be improved.

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 concise sentence that front-loads the action and lists key return data. No filler or redundant information, achieving high efficiency.

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 and no output schema, the description covers the return data adequately. It could be enhanced by mentioning error cases or format details, but is mostly complete for operational 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?

The input schema has 100% coverage with parameter description 'ショップの slug（URL 識別子）'. The description adds 'slug で取得する' confirming the parameter role, but does not add substantial new meaning. 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 retrieves details of one shop by slug and lists the returned data (story, description, supported blockchains, x402 payment status). It effectively distinguishes from siblings like list_shops (which returns multiple shops) and get_product (which returns product details).

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 (when you need specific shop details by slug) but does not explicitly mention when not to use or suggest alternatives, such as using list_shops for browsing or get_product for product details. Guidance is adequate but could be more explicit.

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

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

With no annotations provided, the description reveals some behavioral traits: it returns only published products and lists included fields. However, it does not disclose potential pagination, rate limits, authentication requirements, or what happens if the shop slug is invalid. The description provides moderate transparency but leaves gaps.

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, consisting of two clear sentences. It front-loads the primary purpose and efficiently adds contextual usage guidance 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?

Given the tool has one parameter and no output schema, the description adequately explains the return fields (price, stock, variations, etc.) and the intended workflow (after list_shops). It lacks error handling or edge-case behavior but is sufficient 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 100%, and the description adds marginal value by explaining the slug parameter contextually (used to identify which shop's products to fetch). It does not add new meaning beyond the schema, maintaining the baseline score.

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 all published products in one specific shop, including details like price (JPYC), stock, variations, shipping, and corresponding chains. It explicitly differentiates from siblings like list_shops by indicating this tool is for viewing a shop's assortment after finding the shop.

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 explicit guidance to use list_shops first, then this tool for assortment. It implies when to use but does not explicitly state when not to use (e.g., for searching across shops) or name alternative sibling tools directly, though context is 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?

With no annotations, the description takes the full burden. It clearly indicates the tool is read-only (returns a list) and specifies the output fields. It does not mention pagination or potential errors, but for a zero-parameter list tool, this is adequate.

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 three sentences, front-loaded with the core purpose, then details and usage suggestion. Every sentence adds value 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 the simplicity (no parameters, no output schema), the description covers the essential: what it does, what it returns, and when to call it. It could mention edge cases like empty lists, but is otherwise complete for effective 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?

The tool has no parameters, and the input schema has 100% coverage. The description does not need to add parameter details. The baseline for zero parameters 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 clearly states it returns a list of public shops on the JPYC EC Platform, specifies the types of shops (direct-from-producer, specific product categories), and lists the included fields. It differentiates from siblings like get_shop and list_products_in_shop by positioning itself as the entry point for product searching.

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

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

The description explicitly advises calling this tool first as a starting point for product search, implying it should be used before more specific tools like get_shop or list_products_in_shop. However, it does not explicitly mention when to avoid using it or provide alternatives for other 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?

No annotations provided, but the description details key behaviors: stock reservation for 5 minutes, return of non-final data, requirement for same shop, and the need for a subsequent signed challenge. It lacks info on idempotency or error handling, but covers the main behavioral traits beyond basic read/write 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 four sentences, each contributing essential information: action, returns, next step, and constraints. It is front-loaded with the main purpose and avoids unnecessary words, making it efficient for an AI agent 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?

Given the tool's complexity (8 params, nested objects, no output schema), the description adequately covers purpose, workflow, return values, constraints, and the required follow-up action. It provides a complete mental model for an agent 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?

Schema description coverage is 100%, but the tool description adds meaningful context for the 'shipping' and 'gift_recipient' parameters (conditional necessity based on cart contents) and reinforces the 'shop_id' constraint (all items same shop). This aids correct parameter usage beyond the schema's minimal 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 specifies a clear verb ('実行する') and resource ('x402 チェックアウトの 1 回目'), and distinguishes it from the sibling 'submit_payment' by outlining the two-step process. It also details the returned data and constraints, making the tool's role 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 explicitly states when to use this tool (first step of checkout) and how it relates to 'submit_payment' (sign challenge and pass to it). It also provides conditional requirements for 'shipping' and 'gift_recipient' parameters, but does not exhaustively list when not to use it (e.g., if a reservation already exists).

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. It discloses sorting by sales and a maximum of 50 results, but does not mention authentication, error behavior, or pagination. This is adequate but not comprehensive.

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 paragraph that starts with the primary purpose, then lists examples, then details each parameter. Every sentence adds useful information 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?

With 7 parameters and no output schema, the description covers purpose, parameters, sorting, and limit. It does not describe the return structure, but the agent can infer from sibling tools. Additional detail on default behavior (e.g., default limit of 20) would improve 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%, so baseline is 3. The description adds value by providing examples ('text' with '丹波 米'), clarifying 'tag' as region/certification, and noting that prices are in JPYC. This goes beyond the 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 identifies the tool as a cross-search across public products on the JPYC EC Platform, with examples of product types (e.g., reduced-pesticide rice, sake, crafts). It distinguishes from sibling tools like list_products_in_shop (per-shop) and get_product (single product) by specifying cross-shop scope.

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 broad product discovery across multiple shops, with filtering options. It does not explicitly state when not to use or provide alternatives, but the sibling context and filtering parameters (e.g., shop_slug) guide appropriate use.

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 provides moderate transparency: it states the server settles on-chain via facilitator and returns order details. However, it does not mention potential failure modes, idempotency, or authentication requirements, which are important for a payment submission 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, well-structured paragraph in Japanese that front-loads the key inputs and process. It is concise, with no redundant information, and every sentence contributes to the understanding of the tool's function.

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 description covers inputs, server action, and outputs (order_number/tx_hash). It also highlights the signing requirement, which is critical. However, it could explicitly mention prerequisites (e.g., having called quote_checkout) and error conditions for a more complete 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?

Despite 100% schema coverage, the description adds significant semantic value by explaining that reservation_id comes from quote_checkout, that payment_signature is a base64url JSON of a signed x402 PaymentPayload, and crucially that the signature must follow EIP-3009 against the payment_required content. This goes well beyond the 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 the tool's purpose: it finalizes payment using a reservation_id from quote_checkout and a signed x402 PaymentPayload. It specifies the server action (on-chain settlement via facilitator) and the return values (order_number/tx_hash), distinguishing it from sibling tools like quote_checkout and get_order_status.

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 the tool should be used after quote_checkout and before checking order status, as it references obtaining the reservation_id from quote_checkout. It does not explicitly state when not to use it or list alternatives, but the workflow context is clear from the description.

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