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

No annotations are present, so the description carries the full burden. It discloses key side effects: images become immediately visible, URLs must be publicly accessible, and quantity limits depend on plan. It also lists the API endpoint and return structure. Missing permission or failure details, but the provided transparency is solid.

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 well-structured with clear sections (purpose, API, return, side effects). Each sentence provides useful information without redundancy, and the purpose is front-loaded with a [WRITE] marker.

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 2-parameter write tool with no output schema, the description provides a complete picture: what it does, how it works, what the API call is, what the response looks like, and side effects. No critical 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% for both parameters, so the schema already explains the inputs. The description adds little beyond the schema, mainly repeating that URLs must be public, which is also in the schema. 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 adds images to a product by uploading image URLs, with the specific detail that images are appended to the existing album. This distinguishes it from siblings like delete_product_images and 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?

It provides explicit context for use ('適用於新增商品展示圖、情境圖等' – suitable for product display and context images). However, it does not mention when not to use this tool or alternative tools like upload_media, so it lacks exclusions/alternatives.

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

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

With no annotations provided, the description carries the full burden. It discloses side effects (immediate balance change, points history recording), an error condition (deduction may fail if insufficient points), and the return structure. This is rich behavioral context well beyond a basic operation statement.

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 well-structured with clear section headers (用途, API, 回傳結構, 副作用), front-loaded with the [WRITE] flag and purpose. Every section adds value and the length is justified for a write operation with no annotations.

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 write tool with no annotations and no output schema, the description covers purpose, usage scenarios, the underlying API endpoint, return structure, and side effects. It even references a sibling tool for verification. It is fully sufficient for an agent to invoke correctly.

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

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

The input schema has 100% description coverage for all three parameters, including the sign convention for points. The description does not add additional parameter-level meaning beyond what the schema already provides, so 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 opens with '[WRITE]' and explicitly states the tool's function: increasing or deducting customer member points, with concrete use cases (manual top-up, promotional gifts, complaint compensation). This clearly identifies the action and resource, distinguishing it from sibling read-only tools like list_member_point_rules.

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

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

The description specifies when to use the tool: '常用於手動補點、活動贈點、客訴補償等場景' (commonly used for manual point additions, promotions, and complaint compensation). It provides clear context but does not explicitly state when not to use it or name alternative tools, so it falls short of a 5.

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

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

With no annotations, the description fully discloses behavioral traits: write operation ([WRITE]), immediate effect, additive nature (non-overwriting), and error handling for non-existent IDs. This goes beyond minimal expectations.

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 well-structured with clear sections (purpose, API, return, side effects). Each section is concise and information-dense, front-loading the purpose.

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

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

Despite no output schema or annotations, the description provides return structure, side effects, error behavior, and usage context, making it highly complete for a 2-parameter 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%, with both product_ids and category_ids described. The description does not add significant extra parameter semantics beyond what the schema already provides, so 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?

Description clearly states the tool's function: '批次將多個商品指派至指定分類' (batch assign multiple products to specified categories), and elaborates with use cases. It is a specific verb+resource that distinguishes itself from sibling read-only tools and other write 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?

States appropriate scenarios ('新季商品上架分類', '重新整理分類結構') and notes efficiency advantage over updating one-by-one. However, it does not explicitly name alternative tools or provide exclusion criteria.

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

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

With no annotations, the description carries the full burden. It discloses important side effects: reviews may be public or pending, affects average ratings, and partial failures possible. It also describes the return structure, offering strong transparency.

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

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

The description is well-structured with clear sections (purpose, usage, API, return, side effects). Every sentence provides actionable information, and the front-loaded purpose makes it quickly scannable.

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 purpose, usage, API, output, and side effects, which is sufficient for a bulk write operation. It lacks details on batch limits or item validation specifics, but references create_product_review for format and warns about API-dependent failure behavior, keeping it reasonably 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 describes the 'reviews' parameter with a full example and notes that each item format matches create_product_review. The description adds no additional parameter-level meaning beyond the schema, so 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 explicitly states it batch creates multiple product reviews, provides the API endpoint, and distinguishes itself from siblings like create_product_review (single) and bulk_update/delete.

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 use case: bulk importing historical reviews or backfilling after promotions. It does not explicitly mention alternatives or when not to use, but the context is strong enough for an agent to select this tool for batch operations.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly states that deletions are permanent and irreversible, that product review counts and average ratings will be updated, and that partial failures may occur depending on API implementation. This is highly transparent for a destructive operation.

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

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

The description is well-structured with labeled sections: purpose, API call, return structure, and side effects. It is concise, with every sentence providing meaningful information. No fluff 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 simple one-parameter bulk delete tool with no annotations and no output schema, the description is complete. It covers purpose, API endpoint, return structure, and side effects, giving the agent all necessary context to invoke the tool correctly. Sibling tools are not referenced but 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?

The input schema has 100% coverage for the single parameter comment_ids, including an example. The description does not add extra semantic detail beyond the schema, which is acceptable since the schema already provides sufficient meaning. The baseline of 3 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 the tool's function: batch deleting multiple product reviews ('批次刪除多筆商品評論'). It specifies the action (delete), resource (product reviews), and scope (batch/multiple), distinguishing it from the single-delete sibling tool. The use case for batch clearing test data or violating reviews adds specificity.

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 usage context by stating suitable scenarios (batch clearing test data or large numbers of violating reviews). However, it does not explicitly mention alternatives like delete_product_review for single deletions or when NOT to use this tool, leaving some implicit 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?

With no annotations, the description carries full disclosure. It lists side effects (batch status update, potential partial failures, multiple shipment notifications) and the return structure, going well beyond the schema. This is comprehensive for a mutation 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 well-organized with labeled sections (purpose, API, return, side effects) and each sentence adds value. It is appropriately sized without 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 simple schema, absence of annotations, and lack of output schema, the description provides all essential context: what it does, when to use, side effects, and return format. It equips an agent to correctly invoke and interpret the result.

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 already fully documents the only parameter (order_ids as array of strings) with 100% coverage. The description adds no additional syntax or format details, so the baseline 3 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 the tool batches multiple order shipments, using the explicit [WRITE] marker and a dedicated purpose section. It distinguishes from the sibling execute_order_shipment by focusing on batch processing.

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 context ('daily batch shipment scenarios') but does not explicitly contrast with alternatives like execute_order_shipment or state when not to use. It is clear enough for an agent to infer batch use, but lacks 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?

With no annotations provided, the description carries the full burden and does well by disclosing side effects: changes are immediate, product average ratings may sync, and partial failure behavior depends on API implementation. It also states the return structure. However, it does not mention authentication requirements or rate limits, which would make it more complete.

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 well-structured with clear sections: purpose, API call, return structure, and side effects. It is concise, every sentence adds value, and the key purpose is front-loaded in the first line.

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 is complete for a single-parameter batch update tool: it provides the API endpoint, a high-level return structure (since no output schema exists), and important side effects including partial failure. The schema covers the parameter, so the combined information is sufficient for an agent to select and invoke the tool correctly.

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

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

The only parameter 'updates' is fully described in the schema (100% coverage) with an example and the requirement that each item contain an id field. The tool description adds no additional parameter syntax or field details beyond the schema, so 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 does a batch update of multiple product reviews, with a specific purpose of admin batch publishing or hiding comments. The verb '批次更新' (batch update) and resource '商品評論' (product reviews) are explicit, and it distinguishes from siblings like update_product_review (single) and bulk_create/delete_reviews.

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 identifies a clear use case: '適用於管理員批次公開或隱藏評論' (suitable for administrators to batch publish or hide comments). It provides context for when to use the tool, but does not explicitly mention alternatives or when not to use it, such as using update_product_review for single updates.

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

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

With no annotations provided, the description carries full behavioral disclosure. It lists side effects (immediate update affecting frontend purchasable quantities), error behavior (possible skip or error for missing SKUs), and a precaution (verify SKUs before running). This is comprehensive for a write operation.

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

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

The description is well-structured with a one-line summary followed by sections for usage, API endpoint, response structure, and side effects. It is compact and every section adds value, though it includes some details (like the exact endpoint) that are not strictly necessary.

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 (bulk array update), lack of annotations, and lack of output schema, the description covers all essential aspects: purpose, when to use, API endpoint, response shape, side effects, and error caveats. It leaves no major gaps for the agent to invoke it correctly.

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

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

The input schema fully describes the 'updates' parameter, including its structure as {sku: str, quantity: int}. The description adds no new parameter-level detail beyond what the schema already provides, so 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 it batch updates inventory quantities for multiple SKUs using a specific verb and resource. It distinguishes itself from sibling tools by explicitly naming update_product_quantity and update_variation_quantity as alternatives, making its scope obvious.

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 explicit use cases (inventory adjustments after stocktaking, purchase inbound) and compares efficiency to calling single-update tools. However, it does not explicitly state when not to use it, such as for single SKU updates or if validation is required.

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

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

With no annotations provided, the description fully discloses behavioral traits: it marks the operation as irreversible, notes that cancellation may fail if the order is already shipped, and states that refunds are handled separately for paid orders. It also includes the return structure (dict with success, resource_id, message), which goes beyond basic safety info.

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 well-structured into concise sections (purpose, API, return structure, side effects) with no fluff. Every section adds value, and the key info is front-loaded with the [WRITE] tag and purpose.

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

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

For a write operation with no output schema, the description is complete: it explains the API endpoint, return structure, side effects, and conditions affecting cancelability. The parameter schema covers the arguments, so the agent has everything needed to invoke the tool correctly.

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

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

The input schema already provides 100% coverage with descriptions for both parameters (order_id and reason). The tool description adds no additional parameter-specific guidance, so the schema carries the burden. 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 cancels a specified order (取消指定訂單) and lists specific use cases (customer request, stock shortage, payment issues). This distinguishes it from sibling tools like update_order or update_order_status, which handle other order 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?

The description provides clear context for when to use the tool by listing scenarios such as customer cancellation requests and stock issues. However, it does not explicitly contrast with alternatives or state exclusions (e.g., when not to use), relying mostly on implied usage from the purpose.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It explicitly labels the operation as [WRITE], lists side effects (coupon binding, visibility in customer account, error on limit/expiry, one-per-customer rule), and describes the return structure. This is exceptionally transparent and goes beyond what annotations would typically provide.

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 well-structured with clear sections ([WRITE], 用途, API, 回傳結構, 副作用). Every section provides relevant information without any padding. The opening [WRITE] immediately signals the destructive/write nature, and the content is concise yet comprehensive.

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 is complete for a tool of this complexity. It covers purpose, the underlying API endpoint, return structure, and side effects/error conditions. There is no output schema, but the description explicitly lists the return keys. Combined with the schema's coverage of coupon_data, it leaves no major gaps for an agent to correctly invoke the 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?

The input schema already provides a description for coupon_data ('優惠券領取資料，通常包含 coupon_code 與客戶識別資訊') and the schema coverage is 100%, so the baseline is 3. The tool description adds only a brief hint about '兌換碼場景' that aligns with the schema, but it does not add new parameter details. Therefore, it does not exceed the baseline.

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: to claim a coupon on behalf of a customer and bind it to their account. It uses a specific verb ('claim') and resource ('coupon'), and even mentions suitable scenarios ('兌換碼場景'). However, it does not explicitly differentiate from sibling tools like send_coupon or redeem_coupon, so it loses the point for sibling 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 provides clear context for when to use this tool: '適合兌換碼場景或 API 整合的會員領券流程' (suitable for redemption code scenarios or API-integrated member coupon claiming). It does not, however, mention when not to use it or explicitly point to alternatives among siblings, which would be needed for a 5.

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 burden. It explicitly discloses side effects in 【副作用】 (adds a record to the addon product list, requires activation to be visible) and describes the return structure. This goes beyond a bare description, though it omits permission or error 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?

Description is well-structured with labeled sections: [WRITE], purpose, API, return structure, side effects. Each section adds useful information, and the content is front-loaded with the write indicator and purpose. Slightly longer than strictly necessary but justified by the added context.

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 create tool with a flexible object parameter and no output schema, the description provides the return structure, side effects, and activation prerequisite. It could be improved by listing required subfields of addon_data, but the schema's example and additionalProperties mitigate this 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 coverage is 100% with description '加購商品資料，例如 {name, sku, price, quantity, ...}', which sufficiently explains the single parameter. The tool description does not add parameter details beyond the schema, so 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?

Description clearly states it creates a new addon product in Shopline: '建立新加購商品' and '在 Shopline 商店中建立一個新的加購商品（Addon Product）'. The verb '建立' (create) and resource '加購商品' are explicit, and it distinguishes from sibling list/update tools by focusing on the create operation.

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 purpose context (e.g., for customers to purchase at checkout) and implies usage via '建立後需於促銷或商品設定中啟用才會顯示給顧客', but it does not explicitly mention when to use this tool versus list_addon_products or update_addon_product, nor any exclusions.

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

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

With no annotations provided, the description carries the full burden. It discloses important behavioral traits: it is a write operation (marked [WRITE]), calls POST /v1/affiliate_campaigns, returns a dict with success/resource_id/message/campaign, and lists side effects including automatic commission calculation and a warning about financial loss. This is substantial transparency for a mutation tool, though it doesn't mention permissions or reversibility.

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 well-structured with clear sections (目的, API, 回傳結構, 副作用) and is front-loaded with the [WRITE] tag and purpose. Each section adds value, though it is slightly verbose. The organization aids readability without being bloated.

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 create tool with one complex nested parameter and no output schema, the description provides a complete picture: API endpoint, return structure, side effects, and a financial warning. The only gap is detailed parameter structure, but that is referenced in the schema. Sibling tools are all related CRUD operations, so the context is fully covered.

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 sole parameter campaign_data is described in the schema as '聯盟行銷活動資料（參考 Shopline affiliate_campaign 物件結構）', which already provides good coverage. The tool description adds high-level context that the data includes reward rules, but does not elaborate on the object structure. Since schema coverage is 100%, a baseline of 3 is appropriate, with moderate added 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 the tool creates an affiliate campaign (建立聯盟行銷活動) with specific details about setting referral reward rules and commission tracking. The verb 'create' and resource 'affiliate campaign' are explicit, and it distinguishes from sibling tools like update/delete/list by focusing on 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: use this when you need to create a new affiliate campaign. However, it does not explicitly contrast with sibling tools (e.g., 'use update_affiliate_campaign to modify an existing campaign') or state when not to use. The context is clear from the purpose but lacks explicit alternative 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?

With no annotations, the description carries the full burden and discloses important behaviors: it uses the [WRITE] marker, cites the POST /v1/categories API, details the return structure (dict with success, resource_id, message, category), and lists side effects including the addition of a category record and potential error if parent_id doesn't exist. This goes beyond minimal disclosure, though it omits auth requirements and reversibility.

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 compact and well-structured into sections (purpose, API, response, side effects), with every sentence contributing directly to understanding the tool. There is no redundant verbiage or unnecessary repetition.

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

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

For a simple create operation with one parameter, the description covers purpose, API, return structure, and side effects, and highlights the main error condition. It is nearly complete, though it could mention required permissions or other common error scenarios like duplicate names.

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 already includes the example for category_data, so the tool description adds no extra parameter semantics. The side-effect note about parent_id is useful but not focused on parameter meaning, resulting in a 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 the tool creates a new product category in Shopline ('建立新商品分類') and specifies it can assign a parent category for hierarchy. This unambiguous verb+resource phrasing distinguishes it from siblings like update_category and delete_category.

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?

It provides clear usage context by stating the purpose is to create a new category and optionally set a parent. While it does not explicitly mention alternatives or exclusions, the context is sufficient for a straightforward create operation; it also warns about parent_id errors, which helps avoid 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?

No annotations are provided, so the description carries the full burden. It discloses that it adds a customer to the store's customer list and that duplicate email or phone may cause failure, plus includes return structure and API endpoint. This is strong behavioral disclosure for a create operation, though it omits authentication requirements.

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 well-structured with headers and bullet-like sections, covering purpose, API, return structure, and side effects without excessive wordiness. Each section adds useful context and the format is easy to scan.

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

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

Given no output schema or annotations, the description compensates with return structure, side effects, and API endpoint. It is complete for a simple create tool, covering the essential operational aspects an agent needs to know.

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 already has 100% parameter descriptions, so the baseline is 3. The description adds value by noting that duplicate email or phone may cause failures, which informs how those parameters should be considered, though it doesn't provide format details 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 it creates a new customer record in Shopline, using the specific verb '建立' (create) and resource '客戶' (customer). It distinguishes from sibling tools like update_customer and delete_customer by explicitly targeting new customer 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 specifies suitable scenarios (manual customer service entry or batch import) and clearly implies it is for new records. It does not explicitly contrast with update_customer for existing customers, but the context is clear enough for an agent to select it.

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

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

No annotations are provided, so the description carries full burden. It discloses key side effects: automatic activation at start time, storefront price impact, and overlap priority confirmation. It also marks the tool as [WRITE], indicates the exact API endpoint, and describes the return structure. This is thorough and genuinely helpful.

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?

Well-structured with clear sections: purpose, API call, return structure, and side effects. The [WRITE] marker front-loads the mutation behavior. Every sentence serves a purpose; 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?

The description covers purpose, usage scenarios, API endpoint, return structure, and side effects. It lacks detailed campaign_data field specifications, but given the external reference to the Shopline object and the presence of side-effect disclosures, it is sufficiently complete for an agent to invoke the tool 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?

The schema has one parameter (campaign_data) described as '參考 Shopline flash_price_campaign 物件結構' (refer to Shopline object structure), which is vague. The description adds context that the data involves time periods and product prices, but does not detail the parameter structure. With schema coverage at 100% but low specificity, the description adds marginal value, consistent with a baseline score of 3.

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

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

Description explicitly states the verb and resource: '建立限時特價活動（Flash Sale）' (create flash price campaign). It clearly distinguishes itself from sibling tools like list_flash_price_campaigns, get_flash_price_campaign_detail, update_flash_price_campaign, and delete_flash_price_campaign by being the creation variant.

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?

Provides clear usage context: '適合節慶特賣、清倉、限時搶購等場景' (suitable for holiday sales, clearance, limited-time flash purchases). It does not explicitly exclude alternatives like create_promotion, but gives enough context to know when this tool is appropriate.

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

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

With no annotations provided, the description carries the behavioral disclosure burden. It transparently lists side effects (adds a gift record, can be configured via promotion rules) and marks the operation as [WRITE]. It also specifies the Shopline API endpoint. It does not discuss permissions or reversibility, but the main behavioral traits are covered.

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 well-structured with headers, a purpose statement, API reference, return structure, and side effects. It is efficient and front-loaded with the primary purpose. Each section adds value and there is no filler.

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 one open-ended parameter and no output schema, but the description compensates by providing the return structure (dict with success, resource_id, message, gift) and explicitly naming the API endpoint. It also lists side effects. It does not cover error scenarios or auth, but for a simple create operation it is reasonably 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 covers 100% of the parameter (gift_data) with a description and example, so the baseline is 3. The description does not add any additional parameter details beyond restating that gift_data is the data object. It neither clarifies required fields nor enumerates possible structures beyond the schema's '例如' example.

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 creates a new gift record in Shopline ('建立新贈品'), uses a specific verb (建立) and resource (贈品), and distinguishes it from sibling tools like update_gift or list_gifts. It also mentions the promotion integration context, which adds clarity.

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

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

The description explains that the tool is used to create a gift for promotions and notes that after creation it can be used with promotion rules. It does not explicitly state when not to use it, but the create operation is clearly differentiated from read/update siblings. The context is clear, though exclusions are not spelled out.

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 the side effect of creating a new record and explicitly warns that an existing namespace+key combination may cause failure or overwrite. It also includes the API endpoint and return structure, adding meaningful behavioral context beyond the bare create action.

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 well-structured with clear sections: [WRITE], purpose, API endpoint, return structure, and side effects. Every section provides necessary information without redundancy, and the write indicator is 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 single-parameter create tool with no output schema, the description covers all essential aspects: purpose, API call, return format, and side effects/risks. It is fully self-contained and does not rely on annotations.

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

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

The schema already provides 100% description coverage for the single parameter with an example. The description adds value by explaining the uniqueness constraint on namespace+key, which is crucial for understanding how metafield_data is used. This goes beyond the schema's example.

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

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

Description begins with '[WRITE]' and clearly states '建立商家應用元欄位（App Metafield）' (create merchant app metafield), with a specific verb and resource. It also explains the purpose: storing app-specific merchant settings or data, which distinguishes it from sibling read-only 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 【用途】 section gives clear context for when to use the tool: to store additional merchant settings/data needed by the app. No explicit alternatives or when-not-to-use guidance, but no sibling tool shares the same write purpose, so the context is sufficient.

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?

There are no annotations, so the description carries the full burden. It thoroughly discloses the API endpoint (POST /v1/orders), side effects (inventory deduction, customer notification, immediate effect), and return structure. It also warns that the order becomes active immediately, emphasizing the need to verify data before execution.

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 well-structured with labeled sections (用途, API, 回傳結構, 副作用) and bullet points. It front-loads the purpose and each section provides non-redundant, necessary information, making the length justified and easily scannable.

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

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

Despite lacking annotations and output schema, the description provides a complete picture: purpose, API endpoint, return structure, side effects, and parameter requirements. For a single-parameter write tool, this covers all critical aspects needed for correct invocation.

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

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

The schema already describes order_data as requiring complete order data, and the description reinforces this by stating it must contain all required fields per the Shopline API spec. Since there is only one parameter with 100% schema coverage, the description adds minimal additional meaning but does not need to compensate.

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 immediately states '[WRITE] 建立新訂單' (create new order), clearly defining the action and resource. It further specifies practical use cases such as phone orders, customer service order supplements, and offline order transfers, which distinguishes it from order modification or query tools like update_order or get_order_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 explicitly lists when to use the tool (phone orders, CS order supplements, offline transfers) and states the prerequisite that order_data must contain complete fields required by the Shopline API. However, it does not mention when not to use it or explicitly name alternative tools such as update_order, making it clear but not exhaustive.

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

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

With no annotations provided, the description carries the full transparency burden. It discloses the write nature ([WRITE]), side effects (immediate visibility, duplicate SKU/barcode errors), and the return structure, offering substantial behavioral insight beyond the structured schema.

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 well-structured with clear sections (purpose, API call, return structure, side effects) and is front-loaded with the core action. Each sentence adds value, and the format is easy to scan.

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 fully addresses the tool's complexity by including the API endpoint, return structure, and side effects, including duplicate error behavior. Since no output schema exists, the explicit return structure is especially valuable for an AI agent.

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

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

The schema description already covers the single parameter with 100% coverage, explaining it should be a complete product body per the Shopline API spec. The tool description adds emphasis on completeness and mentions SKU, but this largely overlaps with the schema and does not provide significant additional meaning.

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 tool creates a new product record in Shopline, using the verb '建立' (create) and the resource '商品' (product). It further distinguishes from sibling tools like update_product and delete_product by specifying the POST /v1/products endpoint and emphasizing creation of a new record.

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 clearly indicates when to use this tool: to create a new product. It also provides practical guidance on assembling product_data according to the Shopline Open API spec. While it does not explicitly mention alternatives, the context is clear and no exclusions are necessary.

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 carries the full burden and discloses side effects: it adds a review to the list, may be immediately public or pending review based on store settings, and affects average rating. It also specifies the return structure. This is strong behavioral transparency, though it omits details like permission requirements 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?

The description is well-structured with clear sections (purpose, API, return structure, side effects) and is appropriately concise. Every section earns its place, and the [WRITE] tag front-loads the key action. It avoids unnecessary fluff.

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 is complete for a write operation with one param and no output schema, as it provides return structure and side effects. However, it could elaborate on validation rules or required fields within review_data, though the schema example helps. Overall, it provides enough context for an agent to invoke it correctly.

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

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

The schema description covers 100% of the single parameter 'review_data', including an example with product_id, rating, content, and reviewer_name. The tool description itself does not add further parameter details, so it meets the baseline but does not exceed it. The example in the schema is the primary semantic source.

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 function with a specific verb ('建立' - create) and resource ('單筆商品評論' - single product review), distinguishing it from sibling tools like bulk_create_product_reviews and update_product_review. The [WRITE] tag and API endpoint further reinforce 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 provides a clear usage context: '適用於客服代為補登評論或匯入歷史評論資料' (for customer service to add reviews on behalf or import historical review data). It does not explicitly mention alternatives or exclusions, but the singular nature and sibling tools imply when to use it. The guidance is sufficient but could be more explicit about bulk scenarios.

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

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

With no annotations, the description carries the full burden. It discloses key side effects: the variation is immediately added and available in the storefront, and duplicate SKUs may cause API errors. It also names the exact Shopline API endpoint and return structure, providing strong 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 well-structured with labeled sections (用途, 呼叫的 API, 回傳結構, 副作用) and front-loaded [WRITE] indicator. 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?

Given the tool has no output schema, the description compensates by detailing the return dict structure. It covers purpose, API endpoint, parameter shape, side effects, and an error condition, making it complete for an agent to invoke 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?

While the schema already describes all parameters (100% coverage), the description adds meaning by specifying that variation_data must follow Shopline Open API spec and includes SKU, price, inventory, and spec options. This goes beyond the generic schema description.

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 verb and resource: '為商品新增變體' (add variation to product). It clearly distinguishes from sibling tools like update_product_variation and delete_product_variation by focusing on creation of a new variation under an existing 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 explains usage in existing products for adding new spec variants (e.g., color, size), and implies this is for creation rather than update/delete. It does not explicitly name alternatives, but the context is clear enough for correct selection 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?

With no annotations provided, the description carries the full transparency burden. It explicitly discloses side effects: adds a promotion to the store list, activation status depends on promotion_data, and immediate activation may make the promotion live to consumers. It also notes the shutdown for modifications via update_promotion and specifies the return structure (dict with success, resource_id, message, promotion).

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 well-structured with labeled sections: purpose, API endpoint, return structure, and side effects. Every section adds value and the content is front-loaded with a clear '[WRITE]' tag. It is compact yet covers all essential facets.

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 mutating tool with no output schema, the description supplies return structure and side effects, filling key contextual gaps. It also provides concrete examples of what can be created. Minor omission: it doesn't detail required fields or constraints of promotion_data, but that is delegated to the Shopline object structure reference.

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 covers 100% of the single parameter (promotion_data) with a description that references the Shopline promotion object structure. The tool description does not add further parameter-level detail, but it offers context by listing promotion types in the purpose section. Baseline 3 is appropriate since the schema already handles 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 opens with '[WRITE] 建立新促銷活動' (create new promotion), using a specific verb and resource. It further clarifies by enumerating promotion types (discount codes, buy-one-get-one, amount discounts) and distinguishes from siblings like update_promotion and delete_promotion.

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 states the tool's purpose and adds an explicit alternative: '促銷規則設定後如需修改，請使用 update_promotion' (if you need to modify promotion rules, use update_promotion). While not a full when/when-not matrix, this gives clear guidance for a primary alternative use case.

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 begins with '[WRITE]' flagging it as a write operation and lists side effects: adding a record to the POS purchase order list and enabling subsequent stock-in confirmation. It also discloses the return structure, providing behavioral context beyond what a basic create would offer. Since no annotations are provided, the description carries the transparency burden and does so reasonably.

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 well-structured with clear sections (purpose, API, return structure, side effects) and no redundant content. Each section adds value, and the most important information is front-loaded with the action tag and purpose.

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

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

The description includes purpose, API endpoint, return structure, and side effects, which covers the essential aspects of a create operation. It does not document prerequisites, failure behavior, or detailed parameter constraints, but given the simple schema and presence of an output shape description, it is reasonably 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 input schema already provides 100% coverage of the single parameter, including an example object ({supplier_id, items: [{sku, quantity, cost}, ...]}), so the description adds minimal parameter-specific information. The description's mention of recording supplier purchase information aligns with the schema but does not deepen parameter understanding beyond the baseline.

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 function: '建立新採購單' (create a new purchase order) and describes its purpose as recording supplier purchase information in Shopline POS. It also specifies the exact Shopline API endpoint (POST /v1/pos/purchase_orders), distinguishing it from other order 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 context that this tool is for '記錄向供應商進貨的資訊' (recording supplier purchase information), implying its use for purchase order creation. However, it does not explicitly mention when to use it over alternatives or any exclusions, leaving usage guidance implicit.

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?

Since no annotations are provided, the description carries the full burden. It discloses multiple side effects: creates a pending-review record, triggers return process affecting inventory/finances, and may error if order conditions aren't met. This is exemplary transparency for a write 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 well-structured with sections for purpose, API, return structure, and side effects. Every section adds value and there is no redundant filler, making it both concise and informative.

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

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

With no output schema and no annotations, the description compensates by detailing the POST endpoint, response dict fields, side effects, and potential error conditions. This is sufficient for an agent to understand the tool's behavior and invoke it correctly.

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

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

Schema coverage is 100% and the schema already provides a detailed example and description for return_order_data. The tool description adds no extra parameter semantics beyond referencing the order target generally, 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 it creates a return/refund request for a specified order ('建立退貨／退款申請單'), with a clear verb and resource. It distinguishes from siblings like list_return_orders and update_return_order by focusing on the creation action.

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 usage context: '適用於客服處理退換貨流程' (suitable for customer service return/exchange processing). It does not explicitly mention alternatives or when not to use, but the context is clear enough for selection.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure and does so thoroughly. It explicitly states that deletion is permanent and irreversible, that affiliate links/codes become invalid, that new orders cannot be tracked, and that commission records/history are unaffected (with an implementation caveat). This goes beyond minimal disclosure and fully informs the agent of consequences.

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 well-structured with clear sections ([WRITE], purpose, API, return structure, side effects). Every sentence provides necessary information for a destructive operation—purpose, API endpoint, return format, and side effects—without redundancy or padding.

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 only one parameter and no output schema, the description fully contextualizes the operation: it specifies the exact API call, the return structure, and the irreversible side effects. This is complete for an agent to select and invoke the tool correctly, including understanding downstream impacts.

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 already describes the only parameter (campaign_id) with its meaning ('聯盟行銷活動 ID'), achieving 100% schema coverage. The description adds no additional parameter semantics beyond restating that the campaign is specified, so the 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 states a specific verb ('delete') and resource ('affiliate marketing campaign'), and explicitly says '永久刪除指定的聯盟行銷活動' (permanently delete the specified affiliate campaign). It clearly distinguishes itself from sibling tools like create/update/list/get by focusing on deletion.

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 when to use the tool: '用於清除已結束、取消或錯誤建立的活動' (for clearing ended, cancelled, or mistakenly created campaigns). However, it does not explicitly mention alternatives or exclusions (e.g., use update to pause instead of delete), so it falls short of a 5.

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 explicitly discloses irreversibility, permanent deletion, that products are unaffected but their category association is removed, and potential impact on subcategories. It also names the exact API endpoint and return structure, giving the agent a complete picture of the operation's behavior.

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

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

The description is well-structured with labeled sections (用途, API, 回傳結構, 副作用) and is front-loaded with the core purpose. Every section provides valuable information with no filler or redundancy, making it efficiently sized for the tool's complexity.

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 is complete for a destructive one-parameter tool. It includes the return structure explicitly since no output schema exists, covers all side effects, and provides sufficient context for safe invocation. It lacks only auth/rate-limit details, which are not essential here.

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 the parameter clearly described as '分類 ID'. The description adds the API path 'DELETE /v1/categories/{category_id}', which confirms category_id is a path parameter, but it does not add significant semantics about the parameter beyond what the schema already provides. 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 states a specific verb and resource: '永久刪除指定分類' (permanently delete specified category) from Shopline. It clearly distinguishes this from sibling tools like create_category, update_category, and get_category_detail by focusing on deletion. The additional note about suitability for clearing deactivated or mistake-created categories further clarifies the intended use.

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 a clear use case: '適合清除已停用或錯誤建立的分類' (suitable for clearing deactivated or mistakenly created categories). However, it does not explicitly mention when not to use it or suggest alternatives (e.g., update_category for reversible changes), so it falls short of a 5.

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，描述承擔全部責任。它清楚揭露「永久刪除客戶記錄，不可復原」以及「客戶相關的訂單紀錄可能仍保留」等重要副作用，並標註 [WRITE] 屬寫入操作。此資訊足以讓 agent 了解風險。

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?

描述以分段（用途、API、回傳、副作用）呈現，每個句子都有實質資訊，無冗詞，長度適中。

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?

此工具為單一參數的刪除操作，複雜度不高。描述包含用途、API 路徑、回傳結構與副作用，在無輸出 schema 下仍能提供完整指引。

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 已完整描述 customer_id（客戶內部 ID），覆蓋率 100%。描述本身未對參數增加額外語意，因此依據基準分數給 3 分。

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?

描述開頭明確標示「[WRITE] 刪除客戶」並說明用途為「從 Shopline 商店中刪除客戶記錄」，同時提供典型情境（測試資料、GDPR）。此描述以特定動詞+資源+範圍，且與其他客戶工具（list_customers、update_customer）清楚區隔。

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?

說明「通常用於清除測試資料或 GDPR 合規需求」提供明確使用情境。但未提及何時不應使用或與替代工具的比較（例如 update_customer），因此無排除條款。

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

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

With no annotations provided, the description carries the full burden and does so thoroughly. It discloses permanent deletion irreversibility, immediate price reversion for ongoing campaigns, and that historical orders are unaffected.

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 well-structured with separate sections for purpose, API call, return structure, and side effects. It is front-loaded with the [WRITE] marker and every line provides necessary information without 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 simple one-parameter delete operation with no output schema, the description is complete. It documents the API endpoint, return format, and all relevant side effects, giving the agent everything needed to select and invoke the tool correctly.

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

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

The single parameter campaign_id is already fully described in the schema with 100% coverage, including a Chinese description. The description adds no additional parameter-level meaning beyond implying the targeted campaign.

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 verb — permanently deleting a designated flash price campaign — and clearly identifies the resource and scope. It also specifies use cases (cleaning up ended, cancelled, or erroneously created campaigns), distinguishing it from sibling delete/update operations.

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 explicit use cases ('用於清除已結束、取消或錯誤建立的活動') and notes the operation is permanent. However, it does not explicitly mention alternatives like update_flash_price_campaign for modifying an existing campaign, so it stops short of full when-not 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly lists side effects: permanent deletion without recovery, possible retention of order line items, and immediate removal from the storefront. It also indicates the operation is a write via '[WRITE]' and names the exact API call, providing adequate transparency for a delete operation.

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

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

The description is well-structured with labeled sections (用途, API, 回傳結構, 副作用) and is reasonably concise. It avoids unnecessary fluff, though the inclusion of the API endpoint could be seen as slightly redundant given the schema, but it still adds value by clarifying the underlying call.

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 delete tool with one parameter and no output schema, the description is quite complete. It covers the purpose, typical use case, API endpoint, return structure, and side effects. The only missing piece is permission/authorization requirements, but that is not critical for a single-resource delete operation.

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 already provides 100% coverage with a description for the single parameter product_id ('商品內部 ID'). The tool description adds no additional meaning beyond what the schema provides, so the 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 deletes a product permanently from Shopline, using the specific verb '刪除' (delete) and the resource '商品' (product). It distinguishes itself from siblings like delete_product_variation and update_product by explicitly mentioning permanent deletion of the product record and the API endpoint DELETE /v1/products/{product_id}.

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 when to use this tool: '通常用於清除下架商品或測試資料' (usually for removing discontinued products or test data). While it does not explicitly mention alternatives or when not to use it, the typical use case is stated, which is enough to guide an AI agent.

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

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

With no annotations provided, the description fully discloses critical behavioral traits: images are permanently deleted and cannot be recovered, and if the main image is deleted it is automatically replaced. It also specifies the API endpoint and return structure, giving the agent full transparency about consequences.

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 well-structured with clear sections: purpose, API endpoint, return structure, and side effects. Every sentence adds valuable information without redundancy, and the main purpose is 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 simple delete operation with two parameters and no output schema, the description covers all necessary context: what it does, when to use it, the API call, the response format, and side effects. This makes it complete enough for an agent to correctly select and invoke the 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?

The input schema already provides full descriptions for both parameters (image_ids and product_id) with 100% coverage. The description does not add significant extra meaning beyond what the schema states, 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 'Delete product images' with a specific verb and resource, and further elaborates that it removes specified images from the product album. This distinguishes it from the sibling tool 'add_product_images' and other product update tools, making its 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?

It provides a clear usage context: 'Suitable for removing outdated images or incorrectly uploaded images.' While it does not explicitly mention alternatives or when not to use, this context helps an agent decide when to invoke it, and the presence of sibling tools like 'add_product_images' implies the contrast.

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 takes full responsibility for behavioral disclosure. It explicitly warns that the review is permanently deleted and cannot be restored, and that the product's review count and average rating will be updated. It also documents the return structure and the exact HTTP method and path, giving comprehensive insight into the operation's 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 well-organized into labeled sections (purpose, API call, return structure, side effects). Every sentence is informative and earns its place. It is concise yet thorough, with no redundant filler.

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 single-parameter delete operation, the description is highly complete. It covers the purpose, the exact API call, the return structure, and side effects. Since there is no output schema, the description provides return format details, ensuring the agent knows what to expect. The absence of annotations is fully compensated by the description's rich behavioral information.

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 complete coverage for the single parameter (comment_id) with a description ('評論 ID'). The tool description does not add significant meaning beyond what the schema provides; it only mentions comment_id in the API URL context, which does not enhance parameter understanding. Baseline 3 is appropriate given 100% 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 starts with '[WRITE] 刪除單筆商品評論' clearly stating the action (delete) and resource (single product review), which distinguishes it from sibling tools like bulk_delete_product_reviews, update_product_review, and create_product_review. The specific API endpoint is also provided, reinforcing the tool's exact operation.

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?

It provides clear usage context by stating the tool is suitable for removing violating, malicious, or test reviews. While it doesn't explicitly mention when not to use it or name alternatives like bulk_delete_product_reviews, the 'single' qualifier and purpose cover the main usage scenario adequately.

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

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

With no annotations provided, the description fully discloses behavioral traits: it explicitly says '永久刪除' (permanent deletion) and '不可復原' (irreversible), warns that deleting the only variation may make the product unpurchasable, and states that the frontend removes the spec option immediately. This is exceptional transparency for a destructive operation.

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

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

The description is well-structured with clear sections for purpose, API endpoint, return structure, and side effects. Every sentence adds value, and the information is front-loaded with the core action immediately. There is no redundant content.

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

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

Despite having no output schema, the description explicitly states the return structure (dict with success, resource_id, message), the API endpoint, and all relevant side effects. It is complete for a destructive mutation tool of this complexity.

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 already provides 100% coverage with descriptions for both parameters (product_id as '商品內部 ID' and variation_id as '變體內部 ID'). The description adds no additional parameter-level semantics beyond the schema, so the baseline of 3 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 opens with '[WRITE] 刪除商品變體' which clearly states the action (delete) and resource (product variation), and then elaborates the purpose: permanently deleting specific variations for discontinuing specs or cleaning up errors. This distinguishes it from sibling tools like delete_product or update_product_variation.

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 states when to use: '適用於停售特定規格或清理錯誤變體' (applicable for discontinuing specific specs or cleaning erroneous variations). It also warns about the unique-variation case where deletion may make the product unpurchasable. It does not explicitly mention alternatives, but the when-to-use 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?

No annotations are provided, so the description carries the full burden. It explicitly discloses side effects: permanent deletion, irreversibility, consumers losing access to discount codes, and historical orders unaffected. This is strong behavioral transparency for a destructive mutation.

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 well-structured with sections for purpose, API, return structure, and side effects. It is front-loaded with the core purpose and contains no redundant filler.

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 is simple with one parameter and no output schema, but the description compensates by specifying the return structure (dict with success, resource_id, message) and side effects. It could mention authentication or error behavior, but overall it's sufficient for the tool's complexity.

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 already describes promotion_id with 100% coverage. The description adds little beyond referencing the API endpoint with {promotion_id}, so it adds minimal semantic 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 this tool permanently deletes a promotion ('永久刪除指定的促銷活動'), using a specific verb and resource. It distinguishes from sibling tools like list_promotions and update_promotion by emphasizing the destructive, permanent nature.

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?

It provides context for when to use it: '通常用於清除過期、測試或錯誤建立的活動' (usually for removing expired, test, or erroneous promotions). It does not explicitly list alternatives or when-not-to-use, 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?

No annotations are provided, so the description carries full burden. It clearly discloses that the operation permanently deletes records irreversibly, notes a potential restriction if the purchase order has been stocked in, and specifies the exact API and return structure.

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 and well-organized into sections: purpose, API, return structure, and side effects. Each section provides essential information without unnecessary fluff.

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 one-parameter delete tool, the description covers purpose, usage context, API endpoint, return structure, and side effects. The lack of an output schema is mitigated by explicitly documenting the return structure.

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 purchase_order_ids is fully described in the schema with 100% coverage. The description adds no additional parameter semantics beyond confirming batch deletion, so the schema does the heavy lifting.

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 batch deletes purchase orders, with specific verb and resource. It distinguishes itself from sibling tools like create_purchase_order, list_purchase_orders, and get_purchase_order_detail by being the delete operation.

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 when to use: clearing test data or voiding erroneous purchase orders. It doesn't explicitly name alternatives or exclusions, but the given usage scenarios are sufficient for most cases.

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

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

With no annotations provided, the description carries full behavioral disclosure. It lists side effects: order shipment status updates to shipped, may trigger customer notifications, and the order must be shippable or the API returns an error. This is thorough for a write operation.

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

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

The description is well-structured with clear sections for purpose, API, return structure, and side effects. Every sentence provides useful information with no redundancy. It is appropriately sized for the tool's complexity.

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 is simple with one parameter, but the description covers all necessary aspects: purpose, API endpoint, return structure (dict with success, resource_id, message), and side effects. Even without an output schema, the return format is explicitly described, making the description complete for an agent to invoke and interpret results.

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

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

The schema has 100% coverage for the single parameter order_id, with description '訂單 ID'. The tool description does not add additional meaning beyond this, such as format or how to obtain the ID. However, since the parameter is simple and fully documented, a 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's function: '執行訂單出貨' marks an order as shipped and triggers the Shopline shipment flow. It also specifies the exact API endpoint (POST /v1/orders/{order_id}/shipment), making the operation unambiguous. This distinguishes it from siblings like update_order_status or bulk_execute_shipment.

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 the intended usage context: '適用於倉庫確認出貨後的狀態更新' (for status updates after warehouse confirms shipment). It also mentions the prerequisite that the order must be in a shippable state. However, it does not explicitly contrast with alternatives like bulk_execute_shipment or update_order_status.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses that this is a read-only GET request to a specific API endpoint and details the returned fields (id, title, status, commission_type, etc.). This is sufficient for a simple retrieval tool, though it does not mention error conditions or auth requirements.

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 well-structured with clear sections (Purpose, Usage, API Call, Return Structure). It is concise, with no filler, and each sentence adds value: purpose, when to use, what endpoint to call, and what the response contains.

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 get-by-id tool with one parameter and no output schema, the description is fully complete. It provides the API endpoint, usage context, and the full return structure, which is all an agent needs to select and invoke this tool correctly.

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

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

The input schema already provides 100% coverage for the single parameter, including the note that campaign_id comes from list_affiliate_campaigns. The description adds little beyond restating the usage context ('已知 campaign_id'), so the schema does the heavy lifting, matching the baseline of 3.

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

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

The description uses a specific verb '取得' with a clear resource '單一聯盟行銷活動的完整詳情' (get full details of a single affiliate campaign). It distinguishes itself from sibling tools like list_affiliate_campaigns (which lists campaigns) and get_affiliate_campaign_usage (which likely returns usage data).

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 it is suitable when the campaign_id is already known and you need all fields, and it even references that the ID comes from list_affiliate_campaigns. This provides clear context for when to use this tool, though it does not explicitly list exclusions or alternatives.

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 the API endpoint (GET /v1/affiliate_campaigns/{campaign_id}/order_usage), indicates read-only behavior via 'GET' and '回傳' (returns), and details the return structure including total_orders, total_revenue, and order-level fields. This gives the agent a clear picture of what to expect without hiding 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 well-organized into labeled sections (用途, API, 回傳結構), each with concise, purposeful content. It avoids redundancy and provides all necessary information in a compact form.

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 one-parameter read-only tool with no output schema, the description provides comprehensive context: purpose, API endpoint, and detailed return structure. It covers what the agent needs to know to invoke the tool correctly and interpret the result, with no major 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 coverage is 100% and the schema description already explains campaign_id. The tool description adds value by specifying the source of the ID (from list_affiliate_campaigns) and by referencing campaign_id in the return structure, reinforcing how it is used. This goes beyond the schema's descriptive text.

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 opens with a specific verb and resource: '取得聯盟行銷活動的訂單使用統計' (get campaign order usage stats), and explains the purpose: analyzing order count and revenue to evaluate promotion effectiveness. This clearly distinguishes it from sibling tools like get_affiliate_campaign_detail (campaign settings) and list_affiliate_campaigns (listing campaigns).

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

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

The description provides clear context: use this tool when you need to analyze a specific affiliate campaign's order usage, count orders, revenue, and commissions, to assess promotional performance. It does not explicitly mention when not to use it or name alternatives, but the use case is well-defined.

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 carries full burden. It discloses the endpoint is deprecated but still functional, and describes the return structure as a dict containing settings. However, it doesn't mention auth requirements, error behavior, or rate limits, and only indirectly implies read-only via '查詢'.

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 well-structured with sections for purpose, deprecation note, API endpoint, and return structure. It's slightly verbose but each section adds value and the main purpose is 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 zero-parameter, read-only settings tool with no output schema, the description adequately covers purpose, usage context, deprecation status, API endpoint, and return structure. It's complete enough for an agent to invoke correctly.

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

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

The input schema has zero parameters, so baseline is 4. The description adds context about the return structure but doesn't discuss parameters, which is fine since there are none. No additional parameter semantics 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 tool retrieves store-level application settings (取得商店應用程式設定), specifying it queries feature switches and theme settings. The verb '查詢' and resource 'app settings' are unambiguous, and it stands apart from sibling analytics/order 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?

It states the tool is suitable for confirming current feature enablement status and includes a deprecation warning recommending other settings endpoints for latest info. However, it doesn't name specific alternative endpoints, only generically referencing other settings endpoints.

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 carries the burden of behavioral disclosure. It adds valuable context by revealing that the tool scans all orders page by page and that larger date ranges degrade performance, and it provides a detailed return structure. It does not explicitly state read-only behavior, but the verb '查詢' implies a safe read operation, and the performance warning is a meaningful behavioral trait beyond the schema.

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 well-structured with clear sections for purpose, API endpoint, and return structure. It is front-loaded with the purpose and contains no redundant or filler content. The return structure is detailed but necessary for an agent to understand what to expect, and the entire description is compact given the information it conveys.

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

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

Despite lacking annotations and an output schema, the description compensates fully by including the exact API endpoint, a complete return structure with field names and types, and performance-related behavior. It gives an agent everything needed to invoke the tool and interpret results, making it contextually complete for a read-only list operation.

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 structured parameter descriptions already handle parameter meaning. The tool description itself does not add extra semantic detail about parameters; the useful caveats (short date range, pagination) are already present in the input schema, which is the appropriate place. Baseline 3 is warranted because the schema does the heavy lifting.

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 queries archived historical order lists with a specific verb and resource, and distinguishes it from order-related siblings by focusing on archived data. It explicitly says '查詢已封存（archived）的歷史訂單列表' and notes it is suitable for reviewing long-term archived old orders, leaving no ambiguity about 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 provides a clear use case ('適合調閱長期歸檔的舊訂單資料') and implies it is for archived orders as opposed to regular order queries. However, it does not explicitly name alternatives (e.g., query_orders) or state when not to use this tool, so it stops short of full alternative-driven 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?

The description discloses the return structure with a dict containing specific fields and notes an important behavioral nuance: Shopline categories lack a general description field, and seo_description comes from seo_description_translations. This adds value beyond the schema. No annotations are provided, so the description carries the burden, and it does well by mentioning the returned fields and the caveat about 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 well-structured with sections for purpose, API endpoint, and return structure. It is concise but contains useful details without redundancy. Minor issue: the API endpoint is somewhat redundant with the tool name, but it adds specific method and path info that helps clarify behavior.

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

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

Given the simple tool with one parameter and no output schema, the description is sufficiently complete. It explains what the tool returns, notes a caveat about the description field, and provides the API endpoint. It could arguably mention error cases (e.g., category not found), but for a detail-retrieval tool with this complexity, it's largely 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 parameter schema includes a description for category_id, pointing out it comes from get_category_tree's id field. This provides added context about where the ID comes from, which is helpful. Since schema description coverage is 100%, the description doesn't need to add much; the mention of the ID source is a slight bonus.

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 complete details for a single product category, including name, description, and parent category. It differentiates from the sibling tool 'get_category_tree' by focusing on a single category's full detail while the tree likely provides a hierarchical overview.

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 states '適合在已知分類 ID 的情況下取得詳細欄位' (suitable when the category ID is known), giving clear context for use. It doesn't explicitly name alternatives or exclusions, but the sibling list and the mention of the API endpoint imply this is for fetching details rather than listing or tree traversal.

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 burden. It discloses an important implementation detail: '需交叉 Categories API + Products + Orders' (requires cross-referencing multiple APIs), which signals potential complexity. However, it does not mention performance, side effects, or return format beyond listing the metrics, leaving room for more transparency.

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

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

The description is a single, information-dense sentence that front-loads the main function, lists key output fields, and notes the data dependency. Every part adds value with no redundancy, making it concise and well-structured.

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 the essential output metrics (revenue, volume, product count) and the cross-API dependency, which is sufficient for an agent to select and invoke the tool. It does not mention the channel filter or explicitly differentiate from channel comparison, but the schema covers those details, and with no output schema, the listed metrics provide adequate 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?

The input schema has 100% coverage with detailed descriptions for start_date, end_date, and channel, including performance warnings. The tool description itself adds no parameter-specific guidance, so it does not go beyond the schema; the baseline of 3 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 the tool aggregates sales data '依商品分類' (by product category) and specifies the exact output metrics: revenue, sales volume, and product count. This distinguishes it from sibling tools like get_sales_summary or get_channel_comparison, which focus on different breakdowns.

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 category-level sales reporting but does not explicitly state when to use this tool over alternatives among the many report siblings. No exclusions or comparisons are provided, so the usage context is only implied by the purpose.

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

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

With no annotations provided, the description carries the transparency burden and compensates well by disclosing the return structure (dict with total, tree[], flat[] and node fields) and the underlying API endpoint (GET /v1/categories). It does not mention edge cases like inactive categories, but for a read-only list tool this is sufficient.

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 uses clear section headers (用途, API, 回傳結構) and stays concise. Each sentence contributes meaningful information without redundancy, making it easy for an 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?

For a parameterless read-only tool, the description provides complete context: purpose, usage scenarios, related tools, the REST API call, and the full response structure. No output schema exists, so the description appropriately covers return values.

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 zero parameters, so there are no parameter semantics to explain. A baseline score of 4 is appropriate since the description needs no parameter documentation.

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 opens with a specific verb phrase '取得所有商品分類並組成樹狀結構' (get all product categories and build a tree), clearly distinguishing it from sibling get_category_detail. It also states the resource (categories) and the result format, making the tool's 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 【用途】 section explicitly states when to use the tool (browsing the full category hierarchy) and names companion tools: get_category_detail for individual details and product tools for filtering by category. This provides clear contextual guidance and alternatives.

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 完全未提供，描述須承擔揭露行為的責任。描述揭露了工具會逐頁掃描訂單、區間越大越慢等重要效能特性，但未說明回傳格式、是否需要特殊權限、或是否僅包含已完成的訂單等細節，因此僅達中等水準。

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?

描述以單一重點句開頭，直接點出工具功能（比較各門市/通路的同期業績），第二句補充支援的比較類型。文字精簡、無冗詞贅字，每句皆具備資訊價值，結構前重後輕，易於快速理解。

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?

此工具僅有 2 個參數且 Schema 已完整說明，無輸出 Schema 需要描述補足；描述已涵蓋工具目的、比較維度、使用警示（掃描成本），並在上下文中與眾多分析型 sibling tools 有所區隔。若補充回傳結構或比較對象的選擇方式會更完整，但以現有條件已算充分。

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

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

輸入 Schema 對兩個參數的描述已達 100% 覆蓋，且 start_date 特別補充了「逐頁掃描、區間越大越慢」的使用警告，超越 Schema 原本的欄位說明；描述本身也隱含日期區間與比較目的之關聯，因此在 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?

描述以明確動詞「比較」指出工具用途，並具體列出比較維度（營業額、訂單數、客單價）及比較對象（線上 vs 門市、門市之間），能與 sibling tools 如 get_sales_summary、query_orders 明確區隔，聚焦於跨通路比較而非單一彙總或明細查詢。

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?

描述明確說明支援「線上 vs 門市」或「門市之間」的比較情境，讓使用者知道何時採用此工具；雖然未明確列出「何時不該用」或替代工具名稱，但已提供足夠的使用情境脈絡，因此給 4 分。

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

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

With no annotations provided, the description carries the full burden. It discloses that the endpoint may return 403 or 422 under certain token permissions, identifies the underlying API (GET /v1/channels/{channel_id}), and lists the response fields. It implies a read-only operation via '查詢', though it does not explicitly state side-effect absence or rate limits. This is solid but not exhaustive.

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 well-structured with clear sections (purpose, usage, note, API, return structure) and is front-loaded with the main action. No redundant sentences; each section adds valuable information without unnecessary length.

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 get-detail tool with one parameter and no output schema, the description provides everything needed: the action, usage scenario, potential errors, actual API endpoint, and return fields. It is complete enough for an agent to invoke and interpret the response correctly.

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

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

Schema coverage is 100%: the channel_id parameter already has a clear description ('銷售渠道 ID（由 list_channels 回傳的 id 欄位取得）'). The tool description adds little beyond this, essentially just mentioning the parameter in context. Baseline 3 is appropriate since the schema does the heavy lifting.

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 purpose: '取得指定銷售渠道的詳細資訊' (get detailed info for a specified sales channel), and the usage section specifies it queries a single channel's complete settings including type, status, and link config. This distinguishes it from siblings like list_channels (listing) and get_channel_comparison (comparison) by emphasizing the singular 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 usage section says '查詢單一銷售渠道的完整設定...適合確認特定渠道的詳細配置', giving clear context for when to use the tool. However, it does not explicitly name alternative tools or state when not to use it, so it falls short of a 5. The note about token permissions adds a caution but not an explicit alternative.

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 must carry the full burden. It discloses the underlying API endpoint and return structure, which is helpful. However, it does not mention authentication requirements, rate limits, pagination behavior, or how max_results interacts with the response. For a read operation, destructive aspects are not relevant, but missing operational details prevent a higher score.

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 well-structured with clear sections (purpose, API call, return structure) and front-loads the main function in the opening sentence. It is concise without superfluous content; each section provides essential information for using the tool effectively.

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, no output schema) and lack of annotations, the description does a good job by providing the return structure in detail, including message fields. However, it omits details on pagination and how max_results works, which is a notable gap for a tool that returns message lists. Overall, it is fairly complete but not exhaustive.

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% for both parameters, with conversation_id and max_results already well-described in the schema. The description adds little beyond reiterating that conversation_id comes from list_conversations, and it does not elaborate on max_results behavior such as pagination or limits. Per the baseline for high schema coverage, a score of 3 is appropriate.

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

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

The description clearly states the tool's function: '取得指定對話的完整訊息記錄' (get complete message records for a specified conversation). It is explicitly distinguished from sibling list_conversations, which lists conversations rather than messages, and the purpose section provides concrete use cases.

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 includes a dedicated purpose section with specific use cases (understanding customer context, reviewing response quality, tracking order progress) and explicitly states that conversation_id is obtained from list_conversations. However, it does not mention when NOT to use this tool or provide alternative tools for the same task, so it lacks 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?

With no annotations, the description carries full burden. It adds useful context that the analysis is based on order shipping addresses at the city/county level, but it does not disclose output format, aggregation method, or read-only nature. This is minimal but adequate for a simple analytics 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 concise sentence that immediately states the tool's purpose and key scope. There is no redundancy or irrelevant detail.

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 simple structure (3 parameters, no nested objects) and clear purpose, the description is mostly complete. However, without an output schema, it could more explicitly state what the returned distribution contains (e.g., order counts, customer counts, percentages). The term 'distribution' implies a breakdown, which is sufficient for this minimal 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?

The schema fully describes all three parameters (start_date, end_date, channel) with descriptions and enum values, so the description doesn't need to add parameter-specific detail. It still sets context by explaining the analysis is based on shipping addresses, but adds no syntax or format information 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 specifies the action ('analyze'), the subject ('customer regional distribution'), the data source ('order shipping address'), and the granularity ('city/county level'). This distinguishes it from sibling tools like get_rfm_analysis, making the tool's purpose immediately clear.

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 (when geographic customer distribution by shipping address is needed) but provides no explicit guidance on alternatives or exclusions. It doesn't mention, for example, that it only covers orders with valid shipping addresses.

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

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

With no annotations provided, the description fully discloses the tool's behavior: it always returns an explicit error, describes the two failing API approaches, and specifies the return dict fields (error, group_id, supported_alternative). This is exemplary transparency.

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

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

The description is well-organized with clear sections (function, limitations, return structure). It is slightly long but every part earns its place, given the unusual unsupported nature of the tool. A single sentence would not suffice.

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 completely explains the tool's purpose, limitations, and return structure. Even without an output schema, the return dict is described. For a tool that exists primarily to surface an API limitation, this is exceptionally 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 for the single parameter, including its source (list_customer_groups). The description doesn't add new parameter details, but the schema adequately handles semantics, so a baseline score of 3 is appropriate.

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

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

The description first states the apparent purpose (get customer IDs in a group) but then immediately clarifies the actual behavior: the API doesn't support this and the tool always returns an error. This is a specific, honest depiction that distinguishes it from sibling list tools that actually return data.

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 explains when not to use the tool (the endpoint doesn't exist, filter params are ignored) and provides a concrete alternative: export from Shopline backend. This gives clear usage guidance beyond just the tool's behavior.

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 carries the full burden of behavioral disclosure. It transparently states that it calls GET /v1/orders/search twice (once per period) and describes the return structure (period1, period2, segment_migration, etc.). This provides useful behavioral context, though it does not mention potential performance or rate-limit implications.

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 compact and well-structured with clear sections (用途, API call, return structure). Each sentence contributes meaningful information without redundancy, and the core purpose is 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 moderately complex analysis tool with no output schema, the description supplies essential context: purpose, API invoked, and return structure. It covers the key aspects an agent would need to invoke it correctly, though it leaves out details about the migration matrix format. Overall, it is sufficiently 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 input schema already provides descriptions for all seven parameters (e.g., r_days, f_threshold, m_threshold, and date ranges), so the schema description coverage is 100%. The tool description adds no additional parameter-specific meaning, 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's purpose: '比較兩個時間區間的 RFM 分群遷移' (compare RFM segment migration between two time periods). It specifies the exact actions (calculate segments, compare migration, identify upgrades/churn/new/lost customers) and outputs a migration matrix, distinguishing it from sibling tools like get_rfm_analysis.

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 via the 用途 section, explaining that it supports customer lifecycle analysis and strategy formulation. However, it does not explicitly name alternative tools or state when not to use it, so it lacks the highest-level 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?

With no annotations, the description carries the burden. It discloses that the tool aggregates data from five different API calls and returns a dict with five sections. It also notes that amounts are float in TWD. It does not explicitly state read-only behavior or potential latency from multiple calls, but the 'get' semantics and endpoint listing make it sufficiently transparent.

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 well-organized with a summary, usage section, API list, and return structure. Each sentence adds value; it is longer than minimal but justified by the tool's aggregation complexity. 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 having no output schema, the description clearly explains the return structure (dict with five sections) and data types. It names all involved endpoints, which helps the agent anticipate the tool's scope. The differentiation from get_rfm_analysis covers a key sibling relationship. Complete for practical 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% (customer_id is documented as the internal ID from list_customers). The description adds no additional parameter-specific detail beyond the schema, but it does reinforce that this is a single-customer query. 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 it retrieves a single customer's complete profile (basic info, store credit, points, tier history, coupons) with a specific verb ('取得') and resource. It distinguishes itself from the sibling get_rfm_analysis for batch analysis, making its 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?

Provides explicit usage context: suitable for customer service or individual member analysis, and explicitly directs batch analysis to get_rfm_analysis. It also lists the exact underlying Shopline API endpoints, giving the agent clear expectations of scope.

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

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

With no annotations provided, the description carries the full burden. It discloses the API endpoint (GET) and the return structure (dict with customer_id, total_changes, history[]), which is meaningful behavioral context. It could mention error handling or permissions, but for a simple read operation it 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 well-organized into a one-line summary, purpose, API call, and return structure. Each section is brief and informative with no redundancy, 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?

With only one parameter and no output schema, the description compensates by clearly documenting the return structure and referencing a companion tool (list_membership_tiers) for tier name mapping. This makes it practically complete for an agent to invoke correctly.

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

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

The schema already provides 100% coverage for customer_id ('客戶內部 ID'). The description adds no additional constraints or format details beyond the schema, so the 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 a customer's membership tier change history, with the purpose of tracking upgrades/downgrades and reasons. This distinguishes it from sibling tools like list_membership_tiers, which lists tiers rather than history.

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 using list_membership_tiers to map tier names, providing practical usage context. It does not mention when not to use the tool, but the purpose is clear enough for a simple read-only lookup.

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 the underlying API endpoint (GET /v1/delivery_options/{delivery_option_id}), which indicates a read-only operation, and details the return structure with a list of fields. However, it does not explicitly mention error behavior, authentication requirements, or confirm there are no side effects, though the GET method inherently implies safety.

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 well-structured with clear sections for purpose, API call, and return structure. It is concise, front-loaded with the main purpose, and every sentence provides useful information without redundancy or fluff.

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 single-parameter detail-fetch tool without an output schema, the description is quite complete: it explains what the tool does, the API endpoint, and the return fields. It even notes consistency with list_delivery_options. However, it could briefly mention error handling or permissions, so it is not a perfect 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 schema already provides 100% coverage for the single parameter, including its type and description (delivery_option_id obtained from list_delivery_options). The tool description does not add extra meaning beyond confirming the parameter's place in the API endpoint, so the baseline of 3 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 the tool's purpose: to retrieve detailed information for a specified delivery option (取得指定配送方式的詳細資訊). It also elaborates that it queries complete settings including rate rules, regional restrictions, weight limits, etc., and distinguishes itself from list_delivery_options by emphasizing '單一' (single) delivery method.

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 when to use this tool: '適合確認特定配送方式的詳細條件' (suitable for confirming detailed conditions of a specific delivery method). It implies differentiation from list_delivery_options, but does not explicitly state when not to use it or mention alternative tools by name, so it falls short of a 5.

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 the HTTP method (GET), implying read-only behavior, and details the return structure (dict with delivery_option_id, total, time_slots[] with fields). However, it doesn't mention pagination behavior, potential errors, or prerequisites beyond the parameter. This is adequate but not rich.

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?

Description is well-structured with clear sections (用途, API, 回傳結構). It is concise, front-loads the main purpose, and each section provides useful information without unnecessary filler.

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 read-only tool with one parameter and no output schema, the description covers purpose, usage context, API call, and return structure. Missing details like pagination or sorting are minor for a time-slot list tool. The description is complete enough for an agent to select and invoke correctly.

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

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

Schema coverage is 100% and the parameter description already explains '物流方式 ID（由 list_delivery_options 回傳的 id 欄位取得）'. The tool description does not add extra parameter semantics beyond the schema, but it does reinforce the context by mentioning '指定配送方式'. 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?

Description uses specific verb+resource ('取得指定配送方式的可用時段清單'), clearly identifying this tool retrieves time slots for a specified delivery method. It distinguishes from siblings like list_delivery_options (listing options) and get_delivery_option_detail (option details) by focusing on time slots.

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?

Provides explicit use cases: '適合確認預約配送時段或分析客戶配送時段偏好' (suitable for confirming appointment delivery time slots or analyzing customer delivery time slot preferences). This tells the agent when to use it, though it doesn't explicitly mention alternatives or when not to use it.

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

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

Since no annotations are provided, the description carries the full burden. It discloses the underlying API call GET /v1/flash_price_campaigns/{campaign_id}, which implies a read-only operation, and outlines the return structure with specific fields. It does not detail auth requirements or error behavior, but for a simple detail getter, the description adequately communicates its behavior.

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

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

The description is concise and well-structured, with a one-line summary followed by focused sections for purpose, API endpoint, and return structure. Every section adds value, and the text is front-loaded with the core purpose, making it easy to scan.

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 one parameter and no output schema, the description covers the essential aspects: what it does, the exact API call, and the return fields list. It does not discuss possible errors or authentication, but these are less critical for a straightforward read operation. The description is adequately complete for an agent to select and invoke 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% for the single parameter campaign_id, which already explains that it is the ID returned by list_flash_price_campaigns. The description only references 'known campaign_id' without adding further semantic detail beyond what the schema provides, so it meets the baseline of 3.

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 immediately states '取得單一快閃價格活動的完整詳情' (get complete details of a single flash price campaign), with a clear verb (get), resource (flash price campaign), and scope (single, full details). It further elaborates on querying discount rules, products, and time settings, and its distinction from the sibling list_flash_price_campaigns is evident through '單一' and '已知 campaign_id'.

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 usage context: '適合在已知 campaign_id 的情況下取得所有欄位' (suitable when campaign_id is known to get all fields). This tells the agent when to use the tool. However, it does not explicitly mention alternatives or exclusions (e.g., 'use list_flash_price_campaigns first'), though this is implied by the parameter description in the schema.

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 partly carries the transparency burden. It discloses that the metrics are calculated from the 'quantity' field of product variations, which adds behavioral context. However, it does not mention whether the operation is read-only, how missing/invalid variation data is handled, or any performance implications. The description is not misleading but could be more transparent.

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, front-loaded with the main purpose, and directly states the key metrics and calculation source. Every sentence earns its place, with no redundant filler. This is highly concise and well-structured.

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 is simple (one optional parameter, no output schema), and the description lists the expected output metrics. It does not describe the exact response structure or field types, but for an overview tool with minimal inputs, this is acceptable. The brand filter is documented in the schema, so the description remains reasonably 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?

Schema coverage is 100% for the single parameter 'brand', which has a description '品牌篩選' (brand filter). The tool description does not elaborate on this parameter, but the schema already provides basic meaning. Since the schema carries the parameter documentation burden, a baseline score of 3 is appropriate; the description adds no extra 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 the tool's function: getting an inventory overview with specific metrics (total quantity, item count, out-of-stock count). It uses a specific verb ('取得') and resource ('全商品庫存總覽'), and the calculation source is identified. This distinguishes it from sibling inventory tools like get_stock_by_warehouse and get_low_stock_alerts.

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 use for a high-level inventory summary but does not explicitly state when to use this tool versus alternatives. No when-not-to-use conditions or alternative tool names are provided. The overall purpose is clear, so usage is somewhat inferred, but explicit guidance is lacking.

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 behavioral transparency burden. It discloses the data requirements and the calculated metrics, but does not explicitly state read-only behavior, potential errors, or return format. Since it is a calculation tool, the read-only nature is implied.

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

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

The description is a single sentence that conveys purpose, outputs, and prerequisites without any filler. It is front-loaded with the key action and every clause 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?

Given no output schema, the description does mention the return metrics (turnover days and rate) and prerequisites, which is adequate for a simple calculation tool. It lacks explicit details on response structure but is sufficient given the tool's low complexity.

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?

Both parameters have complete descriptions in the schema (100% coverage), so the description adds no additional parameter-level information. The baseline of 3 applies because the schema already documents the 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 a specific verb ('calculate') and resource ('inventory turnover metrics'), and specifies the exact outputs (turnover days, turnover rate). This distinguishes it from sibling inventory tools like get_inventory_overview or get_slow_movers.

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 notes the data prerequisite (product inventory + sales data), implying when it is appropriate to use, but it does not explicitly contrast with alternatives or state when not to use it. Sibling tools like get_sales_summary or get_inventory_overview exist but are not mentioned.

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

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

With no annotations provided, the description carries the full burden. It discloses the underlying GET /v1/products call, the aggregation of locked_inventory_count, and the fact that a direct endpoint does not exist, preventing a 422 error. It also lists the return structure fields, adding operational context like products_scanned. However, it does not discuss rate limits or pagination 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?

The description is structured with clear sections: purpose, API call, note, and return structure. It is dense but not bloated; the API note adds transparency about implementation, though some may consider it extra. Every sentence contributes to understanding the tool's behavior.

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

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

For a zero-parameter read-only inventory tool, the description is complete: it states purpose, method, the quirk of the missing endpoint, and the exact return fields. This provides enough information for an agent to invoke and interpret the tool without external documentation.

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 takes no parameters, so schema coverage is 100% and there is nothing to document. The description adds value by describing the return structure, which helps the agent understand the output even though no parameters exist. This is the expected baseline for a zero-parameter tool.

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 gets a list of inventory items currently locked (reserved), with a specific focus on analyzing SKUs with pending shipment reserved quantities. This is a specific verb+resource+scope that distinguishes it from sibling inventory tools like get_inventory_overview or get_low_stock_alerts.

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 an agent needs to analyze which SKUs have reserved quantities pending shipment. It also provides a technical note about the Shopline API endpoint limitation, explaining why the tool exists. However, it does not explicitly name alternative tools to use instead or provide exclusion criteria, so it is clear context without explicit alternatives.

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

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

With no annotations provided, the description carries the full burden and does so well. It discloses the scanning behavior, the threshold condition (quantity <= threshold), the sort order (ascending by stock), and the exact return structure including field details. This is comprehensive for a read-only 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 compact and well-structured: purpose first, then behavior, then alternatives, then return structure. Every sentence provides useful information with no fluff.

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 no output schema, the description covers all essential aspects: behavior, sorting, and return structure. It even details the fields within each alert, making it complete for an agent to understand the tool's output.

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 documents the threshold parameter with a description, and the tool description adds value by specifying the exact comparison operator (<=) and including threshold in the return dict. This clarifies the semantics beyond the schema's general 'below this value' wording.

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 a list of low-stock or out-of-stock SKUs at variant level with a customizable threshold. It uses a specific verb (取得) and resource (SKU list), and distinguishes itself from siblings by naming get_inventory_overview and get_stock_by_warehouse as alternatives.

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 points to alternatives for different needs: use get_inventory_overview for overall inventory stats and get_stock_by_warehouse for warehouse distribution. This gives clear direction on when to use this tool versus other inventory-related 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses the HTTP method (GET) and the return structure (dict with merchant fields), which implies a read-only operation. It does not state safety guarantees explicitly (e.g., no side effects), but the GET method and the '查詢' (query) wording provide reasonable transparency for a simple detail retrieval 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 well-structured with clear headings: purpose, API call, and return structure. It is concise, front-loaded with the main purpose, and every section adds value without redundancy. This is an appropriately sized description for a simple tool.

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?

Since there is no output schema, the description compensates by explicitly listing the return fields (id, name, handle, currency, locale, country, email, phone, address, created_at). It also includes the API endpoint and a clear use case. For a get-by-id detail tool with one parameter, this description is complete and provides sufficient context for an agent to invoke it correctly.

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

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

The input schema has 100% coverage for the single parameter merchant_id, including a helpful description that explains where to obtain it ('由 list_merchants 回傳的 id 欄位取得'). The tool description itself adds no additional parameter semantics beyond what the schema already provides, so the 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 explicitly states '取得指定商家的詳細資訊' (get detailed information for a specified merchant), which is a specific verb+resource combination. It clearly describes a single-merchant detail query, distinguishing it from list-style tools like list_merchants. However, it does not explicitly name sibling tools or contrast its scope with them, so it falls short of 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 【用途】 section states that it is suitable for confirming specific merchant settings or data verification ('適合確認特定商家設定或做資料核對'), providing clear usage context. It does not explicitly list alternatives or when not to use this tool, but the context is sufficient for common use cases.

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 carries the full burden of disclosure. It includes the underlying API endpoint, response structure, and field meanings, giving clarity about the read-only nature and output. It lacks details on pagination, error handling, or rate limits, but the provided specifics are substantial.

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 well-structured with labeled sections (purpose, API call, response structure), front-loading the purpose. It is slightly longer due to the output example, but every section adds value and there is 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?

The tool has a single parameter, and the description provides a sample response with key fields, making the tool's behavior understandable. While no output schema exists, the provided structure fills that gap. The absence of explicit alternative comparisons is a minor omission, but overall the description is complete for a simple read-only 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?

The input schema already provides 100% coverage with a clear description of order_id as the internal ID from query_orders, not order_number. The description adds no additional parameter semantics beyond what the schema provides, 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 retrieves all operation history logs for a specified order, including status changes, operator actions, and timestamps. This specific verb+resource combination distinguishes it from sibling tools like get_order_detail or get_order_transactions.

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 it is suitable for audit tracking, providing clear context for when to use it. However, it does not explicitly name alternatives or state when not to use it, falling short of a complete usage guide.

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

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

With no annotations provided, the description carries the full burden. It discloses the HTTP GET endpoint, the return structure in detail, and the key fields. It does not mention error handling, permissions, or rate limits, but for a read-only retrieval tool, the disclosed information is substantive and exceeds a minimal 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 well-structured and front-loaded, starting with the primary purpose before breaking into clearly labeled sections (用途, API, 回傳結構). Every sentence provides necessary information, and the formatting makes it easy to scan. No redundancy or fluff.

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

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

Given the tool's simplicity (one required parameter, no output schema), the description is comprehensive. It explains what the tool does, when to use it, how to get the required ID, the underlying API call, and the complete return structure. This covers all essential context an agent would need for correct invocation.

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

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

The schema already provides a description for delivery_id, but the tool description adds meaning by noting the ID comes from get_order_detail's shipments/deliveries fields, reinforcing the source and providing field-level context that is not explicitly in the schema. With high schema coverage, this additional context justifies a score above baseline.

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 complete information for a single delivery order, including logistics status, tracking number, and recipient address. It distinguishes itself from siblings by referencing get_order_detail as the source of the delivery ID, making its specific resource and action clear.

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 '用途' section explicitly states use cases (tracking packages, confirming recipient info, customer service) and explains that the delivery ID typically comes from get_order_detail's shipments/deliveries fields. However, it does not explicitly state when not to use it or name alternatives beyond the implied get_order_detail, so it falls short of a 5.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool is a read operation, but does not disclose any potential side effects, permission requirements, rate limits, or details about the response format beyond listing a few content categories.

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 immediately conveys the tool's purpose and scope. It is front-loaded with the main action and resource, followed by specific content examples, with 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?

The tool has no output schema and no annotations, so the description must cover return expectations. It lists several content areas (product, payment, logistics, discounts) but is not exhaustive about the complete response. Given the presence of many sibling order-related tools, a bit more context on coverage would improve completeness, but the description is acceptable for a basic get-detail tool.

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