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?

Despite no annotations, the description discloses key behavioral traits: immediate balance change, transaction history recording, and potential error on insufficient points. This exceeds expectations and provides sufficient 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 sections for purpose, API call, return structure, and side effects. It is concise but includes some extraneous details (e.g., the exact API endpoint) that may not be necessary for an AI agent.

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

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

Given the simple parameter set (3 parameters, no nested objects, no output schema), the description covers purpose, behavior, side effects, and return structure adequately. It is complete 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 has 100% coverage with clear descriptions for each parameter. The description adds no additional parameter semantics beyond what the schema provides, so baseline score applies.

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

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

The description clearly states the tool's action ('adjust customer member points') and explicitly mentions it can add or deduct points, with specific use cases like manual compensation or activity rewards. It is distinct from sibling tools, as no other tool focuses on adjusting member points.

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 use cases (manual points addition, activity rewards, complaint compensation) via a dedicated section. It implies when to use the tool, though it does not explicitly state when not to use it. However, given the distinct function, this is adequate.

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 provided, the description carries the burden. It discloses the API endpoint, return structure, and fields, indicating a read-only query operation. It does not mention rate limits or permissions, but the return structure and purpose are well-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 sections for purpose, API call, and return structure. It is somewhat long due to the included output schema, but that adds value. Every part is useful, though it could be slightly more concise without losing clarity.

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

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

Given the complexity (3 parameters, no output schema), the description fully compensates by detailing the return structure, fields, and types. It also includes the API endpoint, making it complete for agent understanding.

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

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

Schema coverage is 100%, with descriptions already provided for start_date, end_date, and max_results. The description adds no additional meaning beyond what the schema offers, so it meets 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 explicitly states it queries archived/historical order lists, distinguishing it from siblings like 'query_orders' which likely handles active orders. The verb '查詢' and resource '已封存（archived）的歷史訂單列表' are specific and 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 clearly indicates the tool is for accessing long-term archived orders, implying it is not for current orders. It does not explicitly state when not to use or name alternatives, but the context of siblings and the term 'archived' provide clear 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?

No annotations are provided, so the description carries the full burden. It mentions the GET API endpoint, implying it's a read-only operation with no side effects. However, it does not explicitly state idempotency or permissions, which would enhance 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 (用途, API, 回傳結構). It is concise with no unnecessary information, every sentence adds value.

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

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

The description provides the return structure (dict with fields), which is helpful since there is no output schema. It covers the essential information for using the tool. Could mention error scenarios or required permissions, but overall 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 single parameter 'category_id' has a description in the input schema that already explains it comes from get_category_tree. The tool description does not add further semantic value beyond what is already in the schema. With 100% schema coverage, baseline is 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 clearly states it retrieves full details of a single product category, specifying fields like name, description, parent category. It distinguishes itself from sibling tools like get_category_tree (which lists categories) and update_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?

The '用途' section explains when to use: when needing detailed info for a known category ID. It implies that if the ID is unknown, one should first use get_category_tree. It doesn't explicitly state alternatives or when not to use, but the guidance 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 exist, so the description must carry the burden. It reveals that the tool requires multiple API calls (cross-referencing), hinting at potential latency, but lacks details on authentication, rate limits, or handling of missing data.

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 efficiently conveys the purpose and a key constraint (cross-referencing). It is not verbose, but could be slightly more 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?

No output schema exists. The description mentions the returned fields (revenue, sales volume, item count) but lacks details on formatting, pagination, or error handling. Adequate but not comprehensive for a tool with medium 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?

Schema coverage is 100% with clear parameter descriptions. The tool description adds no additional meaning beyond what the schema provides, 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 clearly states the tool summarizes sales data by product category, specifying revenue, sales volume, and item count. It also notes the need to cross-reference multiple APIs, distinguishing it from sibling tools that handle individual aspects like orders or categories.

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

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

The description implies the tool is for category-level sales aggregation and mentions cross-referencing overhead, but does not explicitly state when to use it over alternatives like get_sales_summary or get_top_products, nor does it 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 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?

With no annotations provided, the description bears full responsibility for behavioral disclosure. It only states that the tool compares performance but gives no insight into whether it is read-only, destructive, or has limits. The agent cannot infer safety or side effects from this 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 extremely concise with two sentences. The first sentence captures the core action and metrics; the second adds supported comparison types. No extraneous words. Information is front-loaded and efficiently presented.

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?

While the description lists example metrics, it does not explain the output structure (e.g., whether it returns a table, percentages, or raw numbers). Given the lack of an output schema and annotations, the description should provide more context on the expected results to ensure correct tool invocation.

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

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

Schema description coverage is 100% for both parameters (start_date and end_date). The description adds no additional meaning beyond what the schema already provides; it merely re-emphasizes the date range concept. Baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: comparing performance metrics (revenue, orders, average order value) across channels/stores over the same period. It also specifies supported comparisons (online vs. store, between stores), which distinguishes it from siblings like get_channel_detail or get_sales_summary.

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 comparative analysis but does not explicitly state when to use this tool over alternatives, nor does it provide exclusions or prerequisites. The context of sibling tools offers some guidance, but the description itself lacks explicit usage directives.

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?

Discloses potential error responses (403/422) and implies read-only via API endpoint method (GET). With no annotations, additional details like rate limits or data limits would improve completeness.

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?

Structured with clear sections (intro, usage, note, API, return). Concise without unnecessary repetition, though some sections could be slightly tighter.

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?

Provides return structure with example fields and API endpoint. For a simple single-parameter get tool with no output schema, it covers essential context. Missing details like whether the channel ID is required (already in schema) and potential error handling beyond 403/422.

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

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

With 0% schema coverage, description implicitly defines channel_id through context (path and mention of 'specified sales channel'), but does not explicitly state its type, format, or required status beyond 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 retrieves detailed information of a specific sales channel, listing included fields like type, status, and link settings. However, it does not explicitly differentiate from sibling tools like list_channels or get_channel_comparison.

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 usage context ('suitable for confirming configuration') and a note about potential 403/422 errors under certain token permissions. Lacks explicit guidance on when not to use 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 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?

No annotations exist, so the description carries the burden. It describes the HTTP GET call and return structure, implying a read-only operation. However, it does not explicitly state side effects, permissions, or rate limits, which are common for such calls.

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 clear sections for purpose, API endpoint, and return format. No unnecessary words; every sentence adds value.

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

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

For a simple list tool with one parameter and no output schema, the description provides sufficient information: API path, return structure, and a usage hint. It could mention pagination if the list may be large, but it is not a critical 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% (only one parameter with a clear description). The tool description adds no new parameter details beyond what the schema already provides, so it meets the baseline but does not exceed it.

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

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

The description clearly states the tool retrieves a list of customer IDs in a given group (verb 'get', resource 'customer group members'), and it explicitly differentiates from sibling tools like list_customer_groups and get_customer_profile by suggesting chaining.

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 explains the use case: querying which customers belong to a specific group. It also recommends combining with get_customer_profile. However, it does not provide explicit when-not-to-use scenarios or compare with other customer-listing 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, 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?

No annotations are provided, but the description discloses that the tool calls five Shopline APIs internally and returns a dict with specific data sections. It mentions amounts are floats in TWD. While it doesn't discuss rate limits or performance, the behavior is well-described for a read-only 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 concise and well-structured with sections for purpose, usage, API calls, and return structure. It front-loads the key information and every sentence adds value.

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

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

Given there is no output schema, the description adequately explains the return structure (dict with five sections). It also lists the internal APIs called. The tool is read-only, and the description provides complete context for an AI agent to use 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?

There is only one parameter (customer_id) with a description in the schema that explains it's the internal ID from list_customers. The tool description does not add additional semantics beyond the schema. With 100% schema coverage, baseline is 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 clearly states the tool retrieves a single customer's complete profile including basic info and multiple data sections. It uses specific verbs ('取得') and lists the five sections. It distinguishes from the sibling get_rfm_analysis for batch 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 explicitly provides usage context: answering questions about a customer's profile for customer service or individual analysis. It also directs to get_rfm_analysis for batch analysis, giving a clear when-to-use and when-not-to.

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 must disclose behavioral traits. It indicates a read operation via the API method (GET) and describes the return structure (a dict with fields like id, name, etc.). It does not mention side effects or contradictions.

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

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

The description is well-structured with clear sections (用途, API, 回傳結構) and provides all necessary information in a concise, front-loaded manner without superfluous 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?

While the description includes the API endpoint and return fields, it lacks parameter details and does not fully compensate for the missing output schema. Given the tool's simplicity, it is marginally adequate but has 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?

The single parameter delivery_option_id has no description in the input schema (schema_description_coverage = 0%). The tool description does not explain its purpose, format, or how to obtain it, leaving the agent without guidance beyond the name.

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

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

The description clearly states the verb (取得) and resource (指定配送方式的詳細資訊), distinguishing it from sibling list_delivery_options. It specifies that it retrieves detailed settings for a 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 '用途' section explains when to use this tool: to query a single delivery method's complete settings and confirm specific conditions. It mentions the API endpoint but does not explicitly state when not to use it or list alternative tools.

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

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

No annotations provided, so the description should disclose side effects. It describes the API call and return structure, implying a read operation, but does not explicitly state read-only or mention auth requirements. Adds value with endpoint and return format.

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 sections and is concise. It front-loads the main purpose. However, the parameter section is missing, slightly reducing efficiency.

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

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

For a simple 1-parameter tool with no output schema, the description provides the API endpoint, return structure, and usage examples. It covers the essential aspects, though it lacks error handling or pagination details.

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

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

Schema coverage is 0%, and the description only indirectly refers to the parameter as '指定配送方式' (specified delivery method). It does not explain how to obtain the delivery_option_id or any constraints, offering minimal 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 clearly states the tool retrieves available time slots for a specified delivery method. It provides usage examples and differentiates from siblings like get_delivery_option_detail 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.