shopline-mcp

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v0.1.0
Disambiguation4/5
Tools are thoroughly described with cross-references to distinguish them, and each targets a specific resource or metric. However, the large number of analytics tools (sales summary, sales trend, channel comparison, category sales, promotion analysis, promotion ROI) creates some risk of misselection without careful reading.
Naming Consistency4/5
Most tools follow a consistent verb_noun snake_case pattern (list_*, get_*, create_*, update_*, delete_*). Minor deviations exist, such as 'query_orders' instead of list_orders and 'search_promotions' instead of list_promotions/search, but the overall pattern remains predictable.
Tool Count1/5
With 144 tools, this server is far beyond what is manageable or scoped, exceeding the 50+ threshold for extreme mismatch. While it covers many commerce domains, the sheer number makes agent navigation and tool selection unnecessarily difficult.
Completeness4/5
The tool surface provides broad CRUD coverage across orders, products, customers, promotions, returns, inventory, reviews, and conversations, with few significant gaps. Some limitations exist, such as get_customer_group_members returning an error and no staff listing or tax write operations, but these are minor given the overall breadth.
Average 4.3/5 across 144 of 144 tools scored. Lowest: 2.9/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 8 commits in the last 12 weeks
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI status not available
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior2/5
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 does disclose a useful limitation—only customers with order records can be analyzed (Customers API returns 403)—but it does not describe the output format, how thresholds affect segmentation, or the exact data scope, leaving significant behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, consisting of two short sentences: one stating the purpose and one adding a warning. Every word earns its place, and the purpose is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an analytical tool with no annotations and no output schema, the description is incomplete. It clarifies the data source (orders) and a limitation, but does not explain what the RFM output contains, how thresholds are used, or how customers without orders are handled beyond the 403 note. Significant context is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with descriptions for all five parameters, including thresholds and date range. The description adds no extra parameter semantics 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.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool performs RFM (Recency/Frequency/Monetary) segmentation analysis based on order data, which is a specific verb and resource. However, it does not explicitly distinguish itself from sibling analytical tools such as get_repurchase_analysis or get_customer_lifecycle, so it lacks sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternative analytics tools. The only note is a limitation (only customers with order records can be analyzed), which is a constraint rather than a selection criterion or when-to-use instruction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool is a read operation, but does not disclose any potential side effects, permission requirements, rate limits, or details about the response format beyond listing a few content categories.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that immediately conveys the tool's purpose and scope. It is front-loaded with the main action and resource, followed by specific content examples, with no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema and no annotations, so the description must cover return expectations. It lists several content areas (product, payment, logistics, discounts) but is not exhaustive about the complete response. Given the presence of many sibling order-related tools, a bit more context on coverage would improve completeness, but the description is acceptable for a basic get-detail tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, as the single parameter order_id is well-described with its source (query_orders) and clarification that it is not order_number. The tool description adds no additional parameter semantics, 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.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves complete information for a single order, listing product details, payment, logistics, and discounts. This distinguishes it from list-oriented tools like query_orders, though it doesn't explicitly differentiate from more specific order detail tools such as get_order_delivery or get_order_transactions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance is provided on when to use this tool versus alternatives. While the mention of 'complete information' implies a general-purpose use, there are no clear when-to-use or when-not-to-use instructions, and no alternative tools are named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
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 does disclose the main side effect: the quantity is overwritten and takes effect immediately. However, it does not mention idempotency, required permissions, or error conditions. Given the absence of annotations, this gap is significant 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.
Conciseness4/5
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 front-loaded with a WRITE tag and concise. Slight redundancy exists between the title and first line, but overall it is efficiently organized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter write operation, the description covers the main behavior, API endpoint, and side effects. It lacks permission requirements and error handling expectations, but the tool is relatively simple. The return structure is described even without an output schema, which adds completeness. Adequate but not thorough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameters are documented. The description adds value by explaining that quantity is an absolute value, not a delta, which reinforces the schema description. It also clarifies the purpose of addon_product_id. This is above the baseline since it adds meaningful semantic context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool updates the inventory quantity of a specified add-on product by ID, using the verb '更新' (update) with a specific resource (addon product quantity). It distinguishes from the sibling tool update_addon_product_quantity_by_sku by explicitly using ID-based targeting.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use it (when updating quantity by ID) but does not explicitly state when not to use it or mention the alternative by-SKU tool. It provides the calling API path but no explicit exclusions or alternative comparison, so it's adequate but lacks clear selection guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full responsibility for behavioral disclosure. It only states functional behavior and does not mention performance implications (e.g., scanning all orders for large ranges), required permissions, or potential 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences that front-load the key metrics and filter capabilities, with no wasted words. The structure is clear and scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and the absence of an output schema, the description provides a reasonable overview of what it returns and the available filters. It could be enhanced with a note about the default status or performance caveats, but these are covered in the schema, making it adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions cover 100% of parameters, so the baseline is 3. The main description adds no further parameter detail beyond mentioning channel/store filters, which are already in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool gets a sales summary for a specified time range, listing concrete metrics (revenue, order count, average order value, etc.) and mentions channel/store filtering. This distinguishes it from siblings like get_refund_summary or get_sales_trend.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives such as get_sales_trend or get_channel_comparison. The description implies a use case (time-range summary) but provides no exclusions or references to sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the HTTP method (GET) and the return structure, implying a read-only operation. However, with no annotations provided, the description carries the full burden for behavioral transparency. It does not explicitly state the operation has no side effects, nor does it mention prerequisites, permissions, or error behavior. It adds some context but leaves notable gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured into three clear sections: purpose, API call, and return structure. It is concise, front-loaded with the purpose, and every sentence serves a clear function. There is no redundant fluff, making it an exemplar of efficient description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter read tool with no output schema, the description is nearly complete: it covers the purpose, the exact API endpoint, and the return structure. It compensates well for the missing output schema. However, it does not address potential error conditions or explicitly distinguish from the similar tool 'get_order_labels', so it is not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% coverage for the single parameter 'order_id' with a detailed description (internal ID from query_orders, not order_number). The description's return structure includes 'order_id' but does not add additional parameter semantics beyond what the schema already provides, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the purpose: '取得指定訂單上附加的所有標籤' (get all tags attached to a specified order), with a specific verb and resource. It also mentions use cases for classification and filtering. However, it does not explicitly differentiate from the similar sibling tool 'get_order_labels', so it lacks explicit sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a usage context ('可用於分類管理或篩選特殊訂單'), but it does not specify when to use this tool versus alternatives, nor does it mention exclusions. There is no comparison with sibling tools like 'get_order_labels' or 'update_order_tags', leaving the guidance implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden for behavioral disclosure. It describes the analysis outputs (usage counts, discount type, status distribution) which implies a read-only aggregation behavior. However, it does not explicitly state safety, response format, pagination, or any side effects. Given the absence of annotations, this is a partial but not complete disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences, front-loaded with the primary purpose and specific output details. Every sentence adds value, and there is no superfluous text. It is well-structured for quick scanning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple analysis tool with two optional filters and no output schema, the description communicates the key outputs (usage count, discount type, status distribution) and suggests a use case (ROI evaluation with sales data). It lacks explicit return format or pagination details, but given the tool's simplicity, it is fairly complete. The mention of ROI could be clearer, given the sibling tool get_promotion_roi exists.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%: both 'status' and 'discount_type' have descriptions in the schema. The description mentions discount type and status as part of the analysis output but does not add extra meaning to the parameter semantics beyond what the schema already provides. Baseline 3 is appropriate as the schema carries the load.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool analyzes promotion effectiveness, listing specific outputs: usage count, discount type, status distribution. It uses the specific verb '分析' (analyze) and resource '促銷活動' (promotions), and the scope is differentiated from sibling tools like list_promotions by focusing on aggregated analysis rather than listing or detail. However, it does not explicitly name sibling tools or contrast itself, so it loses a point.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides some usage context: '可搭配銷售數據評估促銷 ROI' indicates it can be used with sales data to evaluate ROI, implying a complementary role. However, it does not explicitly state when to prefer this tool over alternatives like get_promotion_roi or list_promotions, nor does it mention any exclusions. The guidance is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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 is transparent about the computed metrics, but does not explicitly state that it is a read-only operation, nor describe the output format or aggregation level. This does not contradict annotations (none exist), but it leaves some ambiguity about the nature of the analysis.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two short sentences that front-load the core function and list key metrics. Every word earns its place, with no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple two-parameter input and the explicit enumeration of output metrics in the description, the tool's behavior is mostly covered. The lack of an output schema is mitigated by listing exactly what is calculated. However, it does not describe the return format or edge cases (e.g., empty date ranges), which prevents a perfect score.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides 100% coverage with descriptions for both parameters (start_date and end_date). The description adds no additional parameter context beyond what the schema already contains. Baseline 3 is appropriate since the schema handles parameter semantics adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear purpose: '分析客戶回購率與回購週期' (analyze customer repurchase rate and repurchase cycle), and lists specific metrics (新客 vs 舊客比例, 回購率, 平均回購天數). This clearly distinguishes it from sibling tools like get_rfm_analysis or get_customer_lifecycle, which focus on different customer analytics dimensions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention exclusions, prerequisites, or contrast with overlapping analysis tools such as get_rfm_analysis or get_customer_lifecycle. The only implied usage is for repurchase analysis, but explicit guidance is missing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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 adds a useful behavioral trait via the start_date warning: the tool scans all orders page by page for the date range, so larger intervals degrade performance. It does not disclose return format or pagination behavior, and there is no output schema to fill that gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that immediately states the core function and key options. No filler, no redundancy, and it earns its place by conveying both purpose and granularity support.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema or annotations, and while the schema descriptions are detailed and provide performance warnings, the high-level description does not specify what the response contains (e.g., time series of sales amounts) or how trend data is structured. It is adequate for a simple read-only query but leaves gaps for an agent needing to parse results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The tool description adds no additional parameter meaning beyond the schema; it merely restates granularity options already present in the enum and descriptions, and does not elaborate on channel semantics beyond '通路篩選'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('取得' - get) and resource ('銷售趨勢數據' - sales trend data), clearly indicating its purpose. It explicitly mentions granularity options for daily/weekly/monthly, which distinguishes it from sibling tools like get_sales_summary or get_channel_comparison by focusing on time-series trend data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for trend charting with configurable granularity, and the start_date schema provides explicit performance guidance to keep intervals minimal. However, it does not state when to prefer this tool over alternatives like get_sales_summary, nor any exclusion criteria such as 'not for aggregate totals'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It does state that it returns a concise order summary and lists the underlying GET APIs, implying a read-only operation. However, it does not disclose pagination behavior, performance impact of large date ranges, or any rate limits directly in the description field.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, with two sentences that state the purpose and return type, followed by a relevant list of underlying APIs. Every sentence earns its place; there is no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has six parameters, no output schema, and no annotations. The description explains what the tool does and the return type, but does not describe the response structure, clarify scope relative to archived orders, or mention error handling/pagination. Given the complexity, this is adequate but not complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already fully documents all six parameters. The description adds no additional meaning beyond the filter dimensions (time range, status, channel) already present in the schema, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb '查詢' (query) with a clear resource '訂單列表' (order list) and specifies filter dimensions (time range, status, channel). It clearly distinguishes from sibling tools like get_order_detail (detail lookup) and cancel_order (mutation).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for order list queries with filters, but does not explicitly state when to use this tool versus alternatives such as get_archived_orders (archived orders) or get_order_detail (single order details). No exclusions or alternative recommendations are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses an important implementation detail: '需交叉 Categories API + Products + Orders' (requires cross-referencing multiple APIs), which signals potential complexity. However, it does not mention performance, side effects, or return format beyond listing the metrics, leaving room for more transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, information-dense sentence that front-loads the main function, lists key output fields, and notes the data dependency. Every part adds value with no redundancy, making it concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the essential output metrics (revenue, volume, product count) and the cross-API dependency, which is sufficient for an agent to select and invoke the tool. It does not mention the channel filter or explicitly differentiate from channel comparison, but the schema covers those details, and with no output schema, the listed metrics provide adequate context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with detailed descriptions for start_date, end_date, and channel, including performance warnings. The tool description itself adds no parameter-specific guidance, so it does not go beyond the schema; the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool aggregates sales data '依商品分類' (by product category) and specifies the exact output metrics: revenue, sales volume, and product count. This distinguishes it from sibling tools like get_sales_summary or get_channel_comparison, which focus on different breakdowns.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for category-level sales reporting but does not explicitly state when to use this tool over alternatives among the many report siblings. No exclusions or comparisons are provided, so the usage context is only implied by the purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines3/5
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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description partly carries the transparency burden. It discloses that the metrics are calculated from the 'quantity' field of product variations, which adds behavioral context. However, it does not mention whether the operation is read-only, how missing/invalid variation data is handled, or any performance implications. The description is not misleading but could be more transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the main purpose, and directly states the key metrics and calculation source. Every sentence earns its place, with no redundant filler. This is highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (one optional parameter, no output schema), and the description lists the expected output metrics. It does not describe the exact response structure or field types, but for an overview tool with minimal inputs, this is acceptable. The brand filter is documented in the schema, so the description remains reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single parameter 'brand', which has a description '品牌篩選' (brand filter). The tool description does not elaborate on this parameter, but the schema already provides basic meaning. Since the schema carries the parameter documentation burden, a baseline score of 3 is appropriate; the description adds no extra value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: getting an inventory overview with specific metrics (total quantity, item count, out-of-stock count). It uses a specific verb ('取得') and resource ('全商品庫存總覽'), and the calculation source is identified. This distinguishes it from sibling inventory tools like get_stock_by_warehouse and get_low_stock_alerts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for a high-level inventory summary but does not explicitly state when to use this tool versus alternatives. No when-not-to-use conditions or alternative tool names are provided. The overall purpose is clear, so usage is somewhat inferred, but explicit guidance is lacking.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the behavioral transparency burden. It discloses the data requirements and the calculated metrics, but does not explicitly state read-only behavior, potential errors, or return format. Since it is a calculation tool, the read-only nature is implied.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that conveys purpose, outputs, and prerequisites without any filler. It is front-loaded with the key action and every clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description does mention the return metrics (turnover days and rate) and prerequisites, which is adequate for a simple calculation tool. It lacks explicit details on response structure but is sufficient given the tool's low complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Both parameters have complete descriptions in the schema (100% coverage), so the description adds no additional parameter-level information. The baseline of 3 applies because the schema already documents the parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb ('calculate') and resource ('inventory turnover metrics'), and specifies the exact outputs (turnover days, turnover rate). This distinguishes it from sibling inventory tools like get_inventory_overview or get_slow_movers.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description notes the data prerequisite (product inventory + sales data), implying when it is appropriate to use, but it does not explicitly contrast with alternatives or state when not to use it. Sibling tools like get_sales_summary or get_inventory_overview exist but are not mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
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 only states that a list is returned, with no mention of data source, ordering, pagination, or edge cases. This is minimal and lacks depth beyond the obvious.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that delivers the full purpose without any extraneous words. It is front-loaded and easy to parse, making it highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter list with no output schema, the description is essentially complete. It clearly identifies the action and resource. It could add minor details like return format or potential limitations, but given the simplicity, the description suffices.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the schema covers them vacuously at 100%. The description adds no parameter-specific semantics, but none are needed. Baseline 4 is appropriate for a parameterless tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves all warehouse/store location lists with the specific verb '取得' and resource '所有倉庫/門市據點'. It is unambiguous and distinguishes itself from sibling tools, none of which list warehouses directly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool versus alternatives, but the use case is implied: when you need a list of all warehouses/store locations. No exclusionary or alternative guidance is provided, making it adequate but not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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.
Conciseness4/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines3/5
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.
Behavior4/5
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.
Conciseness4/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines3/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines3/5
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.
Behavior3/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the HTTP method (GET), implying read-only behavior, and details the return structure (dict with delivery_option_id, total, time_slots[] with fields). However, it doesn't mention pagination behavior, potential errors, or prerequisites beyond the parameter. This is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is well-structured with clear sections (用途, API, 回傳結構). It is concise, front-loads the main purpose, and each section provides useful information without unnecessary filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with one parameter and no output schema, the description covers purpose, usage context, API call, and return structure. Missing details like pagination or sorting are minor for a time-slot list tool. The description is complete enough for an agent to select and invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the parameter description already explains '物流方式 ID（由 list_delivery_options 回傳的 id 欄位取得）'. The tool description does not add extra parameter semantics beyond the schema, but it does reinforce the context by mentioning '指定配送方式'. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses specific verb+resource ('取得指定配送方式的可用時段清單'), clearly identifying this tool retrieves time slots for a specified delivery method. It distinguishes from siblings like list_delivery_options (listing options) and get_delivery_option_detail (option details) by focusing on time slots.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit use cases: '適合確認預約配送時段或分析客戶配送時段偏好' (suitable for confirming appointment delivery time slots or analyzing customer delivery time slot preferences). This tells the agent when to use it, though it doesn't explicitly mention alternatives or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavior; it includes the HTTP GET endpoint and a detailed return structure, which implies a read-only operation. It does not explicitly state permissions, error cases, or side effects, so transparency is only partial.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (purpose, API, return structure) and no redundant text. The JSON example is succinct and informative, earning a high score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has only one parameter and no output schema, but the description compensates with a return structure outline and a usage context. It lacks mention of error handling or pagination, but for a simple read-only GET tool, it is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The sole parameter order_id is already fully described in the schema (internal ID from query_orders, not order_number), and the description itself adds no additional parameter semantics. 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool retrieves all payment transaction records for a specified order, enumerating key fields (payment amount, status, method). This differentiates it from sibling tools like get_order_detail or get_refund_summary, which focus on different aspects.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly mentions that it is suitable for reconciliation and financial audits, providing clear context for when to use it. It does not, however, name alternative tools or specify when not to use it, which keeps it from a perfect score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. The description clearly discloses the read-only nature (a 'get' tool) and the performance implication in the start_date parameter description, warning that the tool scans every order in the range. However, it does not disclose details about return value structure, pagination, or potential limitations (e.g., whether refund rates are based on orders or items), which prevents a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The main description is a single, focused sentence that enumerates the key outputs in a structured list. The parameter descriptions are also concise yet informative. Every word adds value, and the overall structure is clean and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description compensates by listing the main return metrics (refund amount, count, rate, item details) and mentions the net revenue support. The performance warning is helpful. However, it lacks a breakdown of the returned items structure and does not clarify how this tool relates to nearby siblings like get_refund_by_store, leaving some ambiguity for the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, meaning both start_date and end_date have descriptive text in the schema. The main description adds no additional parameter information, but the schema descriptions themselves are detailed, including a warning about query scope. Since the schema already does the heavy lifting, a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('取得' meaning 'get') and resource ('退貨退款統計' refund/return statistics) with a clear scope (指定時間區間, a specified date range). It enumerates concrete outputs: refund amount, number of returns, return rate, and returned item details, which distinguishes it from sibling tools like get_refund_by_store or list_return_orders.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for obtaining aggregate refund metrics over a time range, but it does not explicitly contrast with alternatives such as get_refund_by_store or get_return_order_detail. Parameter descriptions provide advice about using short date ranges for performance, which is a form of when-to-use guidance, but there is no explicit exclusion or alternative recommendation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of behavioral disclosure. It transparently reveals the API endpoint (GET /v1/promotions) and the return structure (dict with total_found, returned, items[] and item fields), which is valuable behavioral context beyond the schema. It does not mention pagination, authentication, or error behavior, but it goes well beyond a minimal description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized with clear sections (用途, API, 回傳結構). Every sentence adds information—use cases, endpoint, and return structure—without redundancy or filler. The main 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.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with no annotations and no output schema, the description is fairly complete: it provides the endpoint, return shape, and common fields, plus use-case context. It could be enhanced by explicitly explaining pagination semantics or naming complementary tools like search_promotions or get_promotion_detail, but it is adequate for an agent to select and invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% parameter description coverage for status and max_results. The description adds little beyond '支援依狀態篩選' and the return field list; it does not enrich the parameter semantics meaningfully. Baseline 3 is appropriate because the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the core function ('取得促銷活動列表') and adds the status-filter capability, making the purpose specific to listing promotions. It implies a distinction from detail/analysis tools by mentioning using promotion_id for further detail, but it does not explicitly contrast with sibling search_promotions, so it stops short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The '用途' section gives clear context: browse all promotions, analyze promotion strategy, or retrieve a promotion_id for later detail queries. This indicates when to use the tool, though it does not explicitly state when not to use it or name alternative tools, so it lacks full exclusion guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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.
Conciseness4/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the return structure with a dict containing specific fields and notes an important behavioral nuance: Shopline categories lack a general description field, and seo_description comes from seo_description_translations. This adds value beyond the schema. No annotations are provided, so the description carries the burden, and it does well by mentioning the returned fields and the caveat about description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with sections for purpose, API endpoint, and return structure. It is concise but contains useful details without redundancy. Minor issue: the API endpoint is somewhat redundant with the tool name, but it adds specific method and path info that helps clarify behavior.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple tool with one parameter and no output schema, the description is sufficiently complete. It explains what the tool returns, notes a caveat about the description field, and provides the API endpoint. It could arguably mention error cases (e.g., category not found), but for a detail-retrieval tool with this complexity, it's largely complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The parameter schema includes a description for category_id, pointing out it comes from get_category_tree's id field. This provides added context about where the ID comes from, which is helpful. Since schema description coverage is 100%, the description doesn't need to add much; the mention of the ID source is a slight bonus.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves complete details for a single product category, including name, description, and parent category. It differentiates from the sibling tool 'get_category_tree' by focusing on a single category's full detail while the tree likely provides a hierarchical overview.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states '適合在已知分類 ID 的情況下取得詳細欄位' (suitable when the category ID is known), giving clear context for use. It doesn't explicitly name alternatives or exclusions, but the sibling list and the mention of the API endpoint imply this is for fetching details rather than listing or tree traversal.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses the HTTP method (GET) and the return structure (dict with merchant fields), which implies a read-only operation. It does not state safety guarantees explicitly (e.g., no side effects), but the GET method and the '查詢' (query) wording provide reasonable transparency for a simple detail retrieval tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear headings: purpose, API call, and return structure. It is concise, front-loaded with the main purpose, and every section adds value without redundancy. This is an appropriately sized description for a simple tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Since there is no output schema, the description compensates by explicitly listing the return fields (id, name, handle, currency, locale, country, email, phone, address, created_at). It also includes the API endpoint and a clear use case. For a get-by-id detail tool with one parameter, this description is complete and provides sufficient context for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage for the single parameter merchant_id, including a helpful description that explains where to obtain it ('由 list_merchants 回傳的 id 欄位取得'). The tool description itself adds no additional parameter semantics beyond what the schema already provides, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states '取得指定商家的詳細資訊' (get detailed information for a specified merchant), which is a specific verb+resource combination. It clearly describes a single-merchant detail query, distinguishing it from list-style tools like list_merchants. However, it does not explicitly name sibling tools or contrast its scope with them, so it falls short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 【用途】 section states that it is suitable for confirming specific merchant settings or data verification ('適合確認特定商家設定或做資料核對'), providing clear usage context. It does not explicitly list alternatives or when not to use this tool, but the context is sufficient for common use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of disclosure. It includes the underlying API endpoint, response structure, and field meanings, giving clarity about the read-only nature and output. It lacks details on pagination, error handling, or rate limits, but the provided specifics are substantial.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with labeled sections (purpose, API call, response structure), front-loading the purpose. It is slightly longer due to the output example, but every section adds value and there is no redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has a single parameter, and the description provides a sample response with key fields, making the tool's behavior understandable. While no output schema exists, the provided structure fills that gap. The absence of explicit alternative comparisons is a minor omission, but overall the description is complete for a simple read-only tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% coverage with a clear description of order_id as the internal ID from query_orders, not order_number. The description adds no additional parameter semantics beyond what the schema provides, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves all operation history logs for a specified order, including status changes, operator actions, and timestamps. This specific verb+resource combination distinguishes it from sibling tools like get_order_detail or get_order_transactions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions it is suitable for audit tracking, providing clear context for when to use it. However, it does not explicitly name alternatives or state when not to use it, falling short of a complete usage guide.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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 transparently lists the associated Shopline API (GET /v1/product_review_comments/{comment_id}) and details the return structure, implying a read-only operation without mutation. However, it does not mention authentication requirements, rate limits, or error behavior, leaving a moderate gap in transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (用途, 呼叫的 Shopline API, 回傳結構) and a one-sentence summary upfront. It is concise yet packed with necessary information—purpose, use cases, API endpoint, and return fields—without any redundant content. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a low-complexity tool with one parameter, no annotations, and no output schema, this description is remarkably complete. It explains what the tool does, when to use it, which API it calls, and exactly what the returned dictionary contains. This is sufficient for an agent to select and correctly invoke the tool with minimal ambiguity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already describes comment_id as 評價 ID, achieving 100% parameter coverage. The description adds a small but useful note that the ID comes from the id field returned by list_product_reviews, which helps agents trace the data provenance. This extra context slightly elevates the description beyond the schema baseline, but not substantially.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear, specific statement: 取得單一商品評價的完整內容，包含圖片與店家回覆 (Get full content of a single product review, including images and merchant reply). This precisely identifies the resource (single product review detail) and the action (get), distinguishing it from sibling tools like list_product_reviews, update_product_review, and delete_product_review.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes a dedicated section listing suitable use cases: 客服處理評價問題、追蹤店家回應進度，或人工審核評價內容 (customer service handling review issues, tracking merchant response progress, or manually auditing review content). This provides clear usage context, but it does not explicitly mention alternatives or exclusion criteria, which keeps it a notch below a perfect score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the transparency burden. It discloses the underlying API method (GET) and endpoint, which implies a read-only operation, and lists the return structure (id, status, created_at, total, items with key fields). This provides meaningful behavioral context beyond the schema, though it stops short of detailing auth requirements or error cases.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is succinct, organized into labeled sections (purpose, API, return structure), and front-loaded with the main purpose. Every sentence contributes value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a straightforward get-detail tool with one parameter and no output schema, the description covers purpose, underlying API, and return structure. This is complete enough for an agent to know what the tool does and what it returns.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (single parameter with description '採購單 ID'). The description does not add extra detail about the parameter beyond its presence in the endpoint path. Baseline 3 applies because the schema already documents the parameter adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description states '取得單一 POS 採購單的完整明細' (get complete details of a single POS purchase order) with specific content like items, quantity, and amount. The verb+resource is clear and distinguishes this from sibling list_purchase_orders which lists orders.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the purpose: use when you need details of a single purchase order. However, no explicit when/when-not guidance is given, and the alternative list_purchase_orders is not mentioned. For a simple get-by-id tool, this is adequate but lacks differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It discloses that it calls two underlying Shopline APIs (GET /v1/return_orders and GET /v1/orders/{order_id}), implying per-order lookups, and describes the return structure (dict with period, total_return_orders, stores). It doesn't explicitly state read-only or rate limits, but the 'get/analyze' nature and API calls provide reasonable behavioral expectations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is structured with clear sections (purpose, APIs, return structure) and is appropriately sized for a moderately complex tool. The first line states the core function, and each subsequent line adds distinct value without padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of output schema, the description compensates by outlining the return structure and the APIs involved. It covers the tool's analytical purpose, inputs (implicitly via schema), and output shape, though it doesn't detail the 'stores' subfields or error handling, leaving minor gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides 100% coverage for both parameters, including format and performance warnings. The description itself doesn't add parameter-specific details, 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description specifies a clear action: '依門市/通路分析退貨退款分佈' (analyze return/refund distribution by store/channel) and details the computation (counts, refund amounts, top products). This distinguishes it from siblings like get_refund_summary or list_return_orders, which are broader or different in scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides context that this is for evaluating channel return status ('協助評估各通路退貨狀況') and specifies the operational scope (date range, grouping by store). It doesn't explicitly name alternative tools or exclusion conditions, but the purpose statement makes its niche clear relative to summary/list tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description discloses the underlying GET /v1/return_orders/{return_order_id} call and the read-only '查閱' intent, avoiding destructive ambiguity. It also details the return structure, though it omits auth/error behavior and lists fields that don't fully cover the stated logistics/customer-contact contents.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description uses clear sections (用途, API, 回傳結構) and leads with the primary purpose. There is slight redundancy between '完整明細' and '完整資訊' and between the stated contents and the return-structure list, so it is not fully polished.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter read-only GET with no output schema, the description supplies the endpoint, purpose, parameter source, and return field structure. It could be more complete by aligning the promised logistics/customer-contact fields with the return structure and noting error behavior, but it is sufficient for basic invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100% for return_order_id, with the schema already explaining it as the id from list_return_orders. The description adds no additional parameter syntax or constraints beyond the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with '取得單一退貨單的完整明細' clearly identifying a single-return-order detail retrieval. It specifies the contents (return reason, items, logistics, customer contact) and is distinct from sibling list_return_orders and get_order_detail by focusing on one return order.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The dedicated 用途 section states this is for customer-service case handling or return review, providing clear context. It does not explicitly name alternatives or when not to use the tool, but the scope is readily inferred from the sibling names and description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses the return structure (dict with total_found, returned, items[] and field names) and the underlying API endpoint. It does not mention pagination, ordering, or authorization, but for a read-only list operation, this is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (purpose, API, return structure) and is concise. There is minor redundancy between the opening line and the purpose section, but overall it is efficient and organized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple, and the description provides the return structure (compensating for the absence of an output schema), explains the purpose, and suggests the detail tool. It could mention pagination behavior, but the max_results parameter in the schema covers that, so the description is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents the only parameter (max_results) with a description, so the description adds no additional parameter meaning. With 100% schema coverage, the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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 flash price campaigns, specifies the scope (all flash sales with name, status, time range), and distinguishes it from get_flash_price_campaign_detail by explaining that campaign_id can be used for further detail lookup.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides a clear usage context (browsing all flash sale campaigns) and explicitly points to get_flash_price_campaign_detail as the next step for full details, implying when to use each. However, it does not discuss alternatives like list_promotions or search_promotions, so it's not a full exclusionary guide.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
無 annotations，描述自行承擔行為揭露責任。清楚列出副作用：無法撤回/修改、客戶即時通知、大量發送需注意頻率限制，並附上 API 路徑與回傳結構，提供相當豐富的上下文。
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
以段落式結構呈現，四段各司其職，沒有冗詞。長度稍長但每段都提供實用資訊，適合複雜工具。
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
對一個寫操作工具而言，已涵蓋目的、API、回傳結構與副作用，資訊足以讓 agent 正確使用。未提及錯誤處理或權限需求，但考量單一參數的簡單度，完整度已相當高。
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
schema 對唯一的 message_data 參數描述已達 100% 涵蓋，且包含範例。描述中並未進一步補充參數語義，故依規則給出基準分 3。
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
明確指出「發送一般商店對話訊息」，以及「非特定訂單的通用訊息」，與兄弟工具 send_order_message 做出區隔。動詞+資源+適用情境清楚，具備明確目的。
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
說明適用於行銷通知、活動公告、客服主動聯繫等場景，並強調「非特定訂單」，隱含排除了 order-specific 訊息。但未明確提及「當需要發送訂單相關訊息時請改用 send_order_message」，因此略少一分。
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It marks the operation as [WRITE], discloses the exact Shopline API endpoint, return structure, and side effects (immediate effect, irreversible but can be overwritten). This is strong disclosure, though it omits permission requirements and error/failure behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description uses clear section headers (Purpose, API, Return Structure, Side Effects) with bullets, and each section contributes non-redundant information. It is slightly verbose but well-organized and front-loaded with the [WRITE] tag.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given two parameters, no output schema, and no annotations, the description covers the essential context: purpose, partial-update semantics, the underlying API call, return structure, and side effects. It does not cover error conditions or permission requirements, but the core information is present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions cover both parameters (100%), and the description adds the key semantic that addon_data is a partial update object—only fields to change need to be passed—with examples like {name, price, ...}. This clarifies intent beyond the schema's generic object definition.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool updates addon product data (更新加購商品資料) and specifies the fields that can be modified (name, price, image). It also implies partial updates by saying only the fields to change are passed, distinguishing it from list/create/quantity-specific sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides usage context by noting 'only pass in the fields to modify' (僅傳入要修改的欄位), which clarifies partial update behavior. However, it does not explicitly state when to use this tool over the alternative sibling tools (e.g., update_addon_product_quantity) or when not to use it, so guidance is incomplete.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior3/5
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.
Conciseness4/5
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.
Completeness5/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations 完全未提供，描述須承擔揭露行為的責任。描述揭露了工具會逐頁掃描訂單、區間越大越慢等重要效能特性，但未說明回傳格式、是否需要特殊權限、或是否僅包含已完成的訂單等細節，因此僅達中等水準。
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
描述以單一重點句開頭，直接點出工具功能（比較各門市/通路的同期業績），第二句補充支援的比較類型。文字精簡、無冗詞贅字，每句皆具備資訊價值，結構前重後輕，易於快速理解。
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
此工具僅有 2 個參數且 Schema 已完整說明，無輸出 Schema 需要描述補足；描述已涵蓋工具目的、比較維度、使用警示（掃描成本），並在上下文中與眾多分析型 sibling tools 有所區隔。若補充回傳結構或比較對象的選擇方式會更完整，但以現有條件已算充分。
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
輸入 Schema 對兩個參數的描述已達 100% 覆蓋，且 start_date 特別補充了「逐頁掃描、區間越大越慢」的使用警告，超越 Schema 原本的欄位說明；描述本身也隱含日期區間與比較目的之關聯，因此在 Schema 高覆蓋率的基礎上額外加分。
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
描述以明確動詞「比較」指出工具用途，並具體列出比較維度（營業額、訂單數、客單價）及比較對象（線上 vs 門市、門市之間），能與 sibling tools 如 get_sales_summary、query_orders 明確區隔，聚焦於跨通路比較而非單一彙總或明細查詢。
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
描述明確說明支援「線上 vs 門市」或「門市之間」的比較情境，讓使用者知道何時採用此工具；雖然未明確列出「何時不該用」或替代工具名稱，但已提供足夠的使用情境脈絡，因此給 4 分。
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the underlying API endpoint (GET /v1/delivery_options/{delivery_option_id}), which indicates a read-only operation, and details the return structure with a list of fields. However, it does not explicitly mention error behavior, authentication requirements, or confirm there are no side effects, though the GET method inherently implies safety.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections for purpose, API call, and return structure. It is concise, front-loaded with the main purpose, and every sentence provides useful information without redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-parameter detail-fetch tool without an output schema, the description is quite complete: it explains what the tool does, the API endpoint, and the return fields. It even notes consistency with list_delivery_options. However, it could briefly mention error handling or permissions, so it is not a perfect 5.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides 100% coverage for the single parameter, including its type and description (delivery_option_id obtained from list_delivery_options). The tool description does not add extra meaning beyond confirming the parameter's place in the API endpoint, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: to retrieve detailed information for a specified delivery option (取得指定配送方式的詳細資訊). It also elaborates that it queries complete settings including rate rules, regional restrictions, weight limits, etc., and distinguishes itself from list_delivery_options by emphasizing '單一' (single) delivery method.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool: '適合確認特定配送方式的詳細條件' (suitable for confirming detailed conditions of a specific delivery method). It implies differentiation from list_delivery_options, but does not explicitly state when not to use it or mention alternative tools by name, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Since no annotations are provided, the description carries the full burden. It discloses the underlying API call GET /v1/flash_price_campaigns/{campaign_id}, which implies a read-only operation, and outlines the return structure with specific fields. It does not detail auth requirements or error behavior, but for a simple detail getter, the description adequately communicates its behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured, with a one-line summary followed by focused sections for purpose, API endpoint, and return structure. Every section adds value, and the text is front-loaded with the core purpose, making it easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with one parameter and no output schema, the description covers the essential aspects: what it does, the exact API call, and the return fields list. It does not discuss possible errors or authentication, but these are less critical for a straightforward read operation. The description is adequately complete for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for the single parameter campaign_id, which already explains that it is the ID returned by list_flash_price_campaigns. The description only references 'known campaign_id' without adding further semantic detail beyond what the schema provides, so it meets the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description immediately states '取得單一快閃價格活動的完整詳情' (get complete details of a single flash price campaign), with a clear verb (get), resource (flash price campaign), and scope (single, full details). It further elaborates on querying discount rules, products, and time settings, and its distinction from the sibling list_flash_price_campaigns is evident through '單一' and '已知 campaign_id'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context: '適合在已知 campaign_id 的情況下取得所有欄位' (suitable when campaign_id is known to get all fields). This tells the agent when to use the tool. However, it does not explicitly mention alternatives or exclusions (e.g., 'use list_flash_price_campaigns first'), though this is implied by the parameter description in the schema.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the transparency burden and does well by exposing the underlying API calls (GET /v1/promotions, GET /v1/orders/search), the page-by-page scanning behavior, and performance cost in the start_date warning. It implies read-only via GET but does not explicitly state side effects 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a one-line summary, 用途 section, API list, and return structure. Each section earns its place with distinct, useful information, and the purpose is front-loaded. There is no redundant filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose, method, underlying APIs, return shape, and performance caveats, which compensates for the lack of annotations and output schema. It could be slightly more precise about the exact ROI formula, but for an agent selecting and invoking the tool it is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with both parameters already described in detail (including data format and performance warnings). The tool description itself adds no new parameter semantics beyond what the schema provides, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific action ('交叉比對促銷活動與銷售數據，計算各活動的 ROI') and clearly identifies the resource (promotions + sales data) and output (ROI per promotion). The 用途 section adds detail on computed metrics (order count, revenue, discount amount), making it distinct from siblings like list_promotions or get_promotion_analysis.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear usage context: retrieve promotions active in a date range and match order promotion_items. It also includes practical guidance to keep date ranges short for performance. However, it does not explicitly name alternatives or when-not-to-use conditions, so it stops 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears the full burden. It transparently lists the calculation logic, the underlying Shopline API endpoints (GET /v1/products and GET /v1/orders/search), and the return structure. This reveals that the tool aggregates data and is read-only in nature (GET calls), though it does not explicitly state side-effect-free behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with header sections for purpose, API calls, and return structure. It is concise and front-loaded; each section provides essential information without unnecessary fluff. The mild redundancy between the opening line and the 用途 section is negligible.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema, and the description adequately describes the return structure (period, period_days, total_products, slow_movers). It also covers the data sources and calculation method, giving an agent sufficient context to invoke the tool. However, it does not describe edge cases or error conditions, which would elevate it further.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the description adds no further meaning beyond the schema. The tool description mentions the use of start/end dates and the threshold concept, but the schema already explains each parameter's role and the default value. No additional parameter context is provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: identifying slow-moving products with high inventory and low sales. It explains the specific metric (days_of_supply) and the threshold/zero-sales criteria, which distinguishes it from sibling inventory analysis tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives a clear business context ('協助清倉決策' – assists clearance decisions), but doesn't explicitly mention when to use this instead of alternatives like get_inventory_turnover. No exclusions or alternative tool references are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the underlying API call (GET /v1/staffs/{staff_id}/permissions), which implies read-only behavior without side effects. It also describes the return structure (dict with staff_id and permissions array), helping the agent understand what to expect. Since no annotations are provided, this transparency is valuable. However, it does not explicitly state 'read-only' or mention auth requirements or potential errors, so it stops short of full transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and concise. It opens with a one-line summary, followed by clearly labeled sections for purpose, API call, and return structure. Every section adds value and there is no redundant or filler content. It is front-loaded with the key information and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with one parameter and no output schema, the description provides sufficient context: it explains the purpose, the affiliated API, and the basic return structure. It does not elaborate on how to interpret the permissions array or handle edge cases, but these may not be necessary for correct invocation. Overall, it is complete enough for an agent to use the tool effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully documents the only parameter, staff_id, including a descriptive note on how to obtain it (from get_token_info). The description itself only refers to '指定員工' (specified employee) without adding any further semantic detail beyond what the schema already provides. With 100% schema coverage, the description does not need to compensate, 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.
Purpose5/5
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 get the permission settings for a specified staff member. It uses a specific verb ('取得/查詢' - get/query) and identifies the resource (staff account's backend access permissions). It also differentiates this tool from the many sibling tools focused on orders, products, and customers by targeting staff permissions, making it unique in the list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit use cases: '適合確認員工權限配置或排查存取問題' (suitable for confirming staff permission configuration or troubleshooting access issues). This gives clear context on when to use the tool. It does not explicitly mention alternatives or when not to use it, but given that no sibling tool provides similar functionality, this is sufficient context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the HTTP GET API endpoint, the return structure (dict with total_found, returned, items[]), and key fields in each item. This indicates a read-only operation and sets expectations for the response. It doesn't mention rate limits or side effects, but for a simple list operation this is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear section headers (【用途】【呼叫的 Shopline API】【回傳結構】). It is concise, front-loaded with the purpose, and each sentence earns its place. No fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
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 is fairly complete: it explains the API call, response structure, item fields, and next-step usage. It doesn't explicitly mention pagination behavior beyond the max_results parameter, but the 'total_found' and 'returned' fields imply pagination without full explanation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% because max_results has a clear Chinese description ('最多回傳筆數'). The tool description itself doesn't add extra meaning to this parameter, but the schema already covers it. The return structure description indirectly clarifies how max_results relates to 'returned', but this is not explicit.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with '取得聯盟行銷活動列表' (Get list of affiliate campaigns), clearly stating the verb+resource. It specifies the purpose: browse all affiliate campaigns, and differentiates from siblings by mentioning that after obtaining campaign_id, one can call get_affiliate_campaign_detail or get_affiliate_campaign_usage.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: use to browse all affiliate campaigns and then proceed to detail or usage endpoints. It names specific sibling tools and explains when to use them (after getting campaign_id). However, it doesn't explicitly state when not to use this tool, but the guidance is strong enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It implies a read-only operation ('查看') and provides the API endpoint (GET /v1/agents), but it doesn't explicitly state side effects, permissions, or rate limits. The return structure is detailed, which adds some transparency, but safety characteristics are not explicitly stated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections for purpose, API call, and return structure. It is concise and front-loaded with the main purpose, and every sentence adds value without unnecessary fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that this is a simple zero-parameter list tool with no output schema, the description provides a solid return structure and API endpoint. It lacks details like pagination or error behavior, but for a basic list operation, it is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline is 4. The description doesn't need to explain parameters; it correctly focuses on the output. No additional parameter semantics are needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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 list of agent accounts for the store). It clearly states the tool's function and distinguishes it from sibling tools by focusing on agents, not other entities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear use case: to confirm agent configuration or understand which external accounts have store operation permissions. It gives context for when to use the tool, though it doesn't explicitly name alternatives or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses the conditional API calls (GET /v1/gifts vs GET /v1/gifts/search), the overall return structure (dict with total_found, returned, items[]), and the fields per item. This adds meaningful behavioral context beyond the schema, though it does not explicitly state it is read-only.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured with clear sections for usage, API endpoints, and return structure. Each section contributes useful information without fluff or repetition, keeping the entire description compact.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
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 provides a detailed return structure including fields like id, name, sku, quantity, status, and created_at, which is helpful. However, it mentions '適用條件' (applicable conditions) in the purpose but does not list such a field in the return structure, leaving a slight ambiguity. Overall, it is sufficient for a simple list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description reinforces the search keyword's role (gift name) but adds no new parameter-specific details beyond the schema. The return structure mention is not directly about parameters, so it doesn't elevate the score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states '取得贈品列表' (get gift list) and explains it is for browsing or searching all gift settings, covering name, stock, and applicable conditions. It distinguishes from sibling tools like create_gift/update_gift by focusing on listing and provides two endpoints based on search condition.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly specifies when to use each endpoint: if a search keyword is provided, the search endpoint is called; otherwise, the list endpoint. It states the purpose (browse/search) but does not explicitly contrast with alternatives (e.g., create/update), though the context makes this fairly obvious.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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 exact API endpoint (GET /v1/pos/purchase_orders), the read-only nature (via GET), and outlines the return structure (total_found, returned, purchase_orders with fields). This goes beyond a minimal statement and provides useful behavioral context. However, it doesn't discuss pagination or limits beyond the schema, so a 4.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
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 each sentence provides distinct value. It is concise and front-loaded with the purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
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 optional parameter, the description covers purpose, API call, and return structure. It lacks explicit pagination guidance, but the schema handles the max_results default. This is complete enough for an agent to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 100% of the single parameter (max_results) with a description. The tool description does not repeat or add parameter semantics, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb '取得' (get) and resource 'POS 採購單列表' (POS purchase order list), and explains its purpose ('了解進貨狀況與採購歷史' / understand stocking status and purchase history). This clearly distinguishes it from sibling tools like get_purchase_order_detail or create_purchase_order.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides a clear use case: understanding purchase status and history. It doesn't explicitly mention alternatives or exclusions, but the list-vs-detail distinction is implied by naming the resource as a list. This is clear context without exclusions, so a 4.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the underlying API endpoint (GET /v1/promotions/search) and the return structure (dict with total_found, returned, items[] and per-item fields). This gives the agent a clear picture of what will happen, though it doesn't detail edge cases like exact-match semantics or pagination behavior beyond the response counts.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is highly structured with clear sections (用途, API, 回傳結構). It is concise, uses bullet-like formatting, and every sentence contributes meaningful information. No fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple search tool with 2 parameters and no output schema, the description provides the essential information: purpose, API endpoint, and return fields. It even mentions the next step (get_promotion_detail) and includes pagination-related counts (total_found, returned). Lacks examples of actual requests or deeper pagination logic, but overall it is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%: both keyword and max_results are described in the input schema. The description adds examples of keyword values and explains that results contain ids for further lookup, but it mostly reinforces what the schema already says. No substantial new parameter semantics are introduced.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: searching promotions by keyword (依關鍵字搜尋促銷活動). It provides concrete examples (週年慶, 黑五) and distinguishes it from siblings by noting it returns ids for further use with get_promotion_detail, setting it apart from list_promotions and inspection tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The '用途' section provides clear context: use this to quickly find promotions by specific name. It implies this is for targeted search rather than general listing, and points to get_promotion_detail for follow-up. It stops short of explicitly naming list_promotions as the alternative for full listings, but 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.
Behavior4/5
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 side effects: '指定 SKU 的加購商品庫存數量將被覆蓋為新值' (the quantity will be overwritten to the new value) and '庫存變動立即生效' (changes take effect immediately). It also documents the return structure, which is strong for an unannotated 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.
Conciseness5/5
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 is information-dense and adds value, with no waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity, the description covers the essential aspects: purpose, API endpoint, return format, and side effects. It does not mention error/edge cases or permission prerequisites, but these are not critical for such a simple operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with both parameters clearly documented (sku and quantity, including that quantity is an absolute value, not a delta). The tool description adds minimal extra 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states '依 SKU 更新加購商品庫存數量' (update add-on product inventory quantity by SKU), which is a specific verb+resource+scope. The [WRITE] prefix and the emphasis on SKU-indexed updating clearly distinguish this from the sibling tool update_addon_product_quantity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear usage scenario: '適合批次庫存同步場景' (suitable for batch inventory synchronization scenarios). This gives the agent a concrete context, but it does not explicitly name alternatives or provide when-not-to-use conditions, so it falls short of full 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses that changes take effect immediately (including live frontend updates) and that the operation is not reversible but can be overwritten. It also includes the return structure. This is strong disclosure for a write operation, 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.
Conciseness5/5
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. It is concise, front-loaded with the primary purpose, and every sentence adds valuable information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a write tool with no output schema and no annotations, the description covers key aspects: purpose, API endpoint, return structure, and side effects. It could mention preconditions (e.g., campaign status restrictions) but given the tool's simplicity and schema coverage, it is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for both parameters. The description adds examples of what campaign_data can contain (special price, schedule, product range), but does not specify the full nested structure or field names, which is a gap given additionalProperties is true. Thus the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: update an existing flash price campaign, with examples of what can be adjusted (price, time period, product range). It distinguishes from siblings by specifying '修改已建立的' (modify existing), contrasting with create and delete tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for modifying existing campaigns and provides examples of fields to adjust. It does not explicitly name alternatives or state when not to use, but the context is clear given the sibling set; thus it provides clear context without explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full behavioral disclosure. It clearly states side effects: immediate and irreversible changes (訂單資料立即變更，不可復原), the ability to overwrite via another call, and status-based field restrictions. It also documents the API endpoint and return structure, which exceeds 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized with clear sections (purpose, API, return, side effects), uses bullet-style formatting, and front-loads the write indicator [WRITE]. Every sentence contributes useful information without repetition or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simple two-parameter interface and lack of output schema, the description covers essential aspects: the exact API method, return structure, and side effects. It does not address error cases or authentication requirements, but these are somewhat self-evident from the context and schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already describes both parameters, but the description adds critical partial-update semantics (僅傳入要修改的欄位，未傳入欄位不受影響), clarifying that only provided fields are modified. It also documents the return structure (dict with success, resource_id, message), which is not in an output schema. This meaningfully enhances the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool updates order fields (更新訂單欄位), lists example fields (備註, 配送地址), and distinguishes it from sibling order operations by specifying PATCH /v1/orders/{order_id} and partial-update behavior. This makes the tool's purpose specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for modifying editable order fields and notes that some fields may be restricted by order status. However, it does not explicitly state when to use this tool over siblings like update_order_status or update_order_tags, nor does it provide explicit exclusion criteria. The guidance is contextual but not directive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior5/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters3/5
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.
Purpose4/5
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.
Usage Guidelines4/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It adds valuable context by revealing that the tool scans all orders page by page and that larger date ranges degrade performance, and it provides a detailed return structure. It does not explicitly state read-only behavior, but the verb '查詢' implies a safe read operation, and the performance warning is a meaningful behavioral trait beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections for purpose, API endpoint, and return structure. It is front-loaded with the purpose and contains no redundant or filler content. The return structure is detailed but necessary for an agent to understand what to expect, and the entire description is compact given the information it conveys.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite lacking annotations and an output schema, the description compensates fully by including the exact API endpoint, a complete return structure with field names and types, and performance-related behavior. It gives an agent everything needed to invoke the tool and interpret results, making it contextually complete for a read-only list operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the structured parameter descriptions already handle parameter meaning. The tool description itself does not add extra semantic detail about parameters; the useful caveats (short date range, pagination) are already present in the input schema, which is the appropriate place. Baseline 3 is warranted because the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool queries archived historical order lists with a specific verb and resource, and distinguishes it from order-related siblings by focusing on archived data. It explicitly says '查詢已封存（archived）的歷史訂單列表' and notes it is suitable for reviewing long-term archived old orders, leaving no ambiguity about scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear use case ('適合調閱長期歸檔的舊訂單資料') and implies it is for archived orders as opposed to regular order queries. However, it does not explicitly name alternatives (e.g., query_orders) or state when not to use this tool, so it stops short of full alternative-driven guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses that the endpoint may return 403 or 422 under certain token permissions, identifies the underlying API (GET /v1/channels/{channel_id}), and lists the response fields. It implies a read-only operation via '查詢', though it does not explicitly state side-effect absence or rate limits. This is solid but not exhaustive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (purpose, usage, note, API, return structure) and is front-loaded with the main action. No redundant sentences; each section adds valuable information without unnecessary length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get-detail tool with one parameter and no output schema, the description provides everything needed: the action, usage scenario, potential errors, actual API endpoint, and return fields. It is complete enough for an agent to invoke and interpret the response correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%: the channel_id parameter already has a clear description ('銷售渠道 ID（由 list_channels 回傳的 id 欄位取得）'). The tool description adds little beyond this, essentially just mentioning the parameter in context. Baseline 3 is appropriate since the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the purpose: '取得指定銷售渠道的詳細資訊' (get detailed info for a specified sales channel), and the usage section specifies it queries a single channel's complete settings including type, status, and link config. This distinguishes it from siblings like list_channels (listing) and get_channel_comparison (comparison) by emphasizing the singular scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The usage section says '查詢單一銷售渠道的完整設定...適合確認特定渠道的詳細配置', giving clear context for when to use the tool. However, it does not explicitly name alternative tools or state when not to use it, so it falls short of a 5. The note about token permissions adds a caution but not an explicit alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses the underlying API call (GET /v1/product_subscriptions/{subscription_id}) and the return structure, which implies read-only behavior. The word '查詢' (query) also signals a non-mutating operation. However, it does not mention error handling or authorization, leaving some gaps, but for a simple GET tool this is acceptable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections for purpose, API call, and return structure. Each section is concise and relevant, with no redundant wording. The first line clearly states the core function, making it easy for an agent to quickly grasp the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and no output schema, the description is remarkably complete. It explains the purpose, usage context, underlying API, and return fields. This is sufficient for an agent to invoke the tool correctly and understand the output. No critical information appears to be missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% coverage for subscription_id, including a helpful note that it comes from list_product_subscriptions. The description does not add further parameter semantics beyond what the schema states. Since schema coverage is high, 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.
Purpose5/5
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 details of a single product subscription). It specifies the verb, resource, and scope (single vs. list), effectively distinguishing it from sibling tools like list_product_subscriptions. The mention of included fields further clarifies its purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage context: '適合客服場景或個別訂閱狀態確認' (suitable for customer service scenarios or individual subscription status confirmation). It clearly implies this is for individual lookups but does not explicitly mention alternatives or when not to use it. Since sibling list_product_subscriptions exists, a direct comparison would have earned a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses the exact API endpoint (GET /v1/promotions/{promotion_id}) and the return structure (a dict with specific fields), which are useful behavioral traits. It does not mention error handling or permissions, but the tool is a simple read-only lookup and the description provides sufficient transparency beyond minimal requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (用途, API, 回傳結構), front-loaded with a one-sentence summary, and every section provides valuable information. It is concise without unnecessary verbosity, and the use of bullets and labels improves scannability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
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 complete: it explains the purpose, when to use, the underlying API, and the return structure. It does not need to explain return values further since it lists the key fields. The level of detail is appropriate for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already covers the single parameter with a clear description (promotion_id from list_promotions or search_promotions). The tool description adds no additional semantic details about the parameter itself beyond reaffirming the 'known promotion_id' usage context. 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: to retrieve the complete details of a single promotion, including discount rules, applicable products, and usage restrictions. It specifies the resource (a single promotion by ID) and differentiates itself from listing/searching siblings by emphasizing 'single' and 'known promotion_id'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use: when the promotion_id is known, to get all fields. It does not explicitly mention when not to use or name alternatives, but the schema's parameter description (promotion_id from list_promotions or search_promotions) provides related context. This meets 'clear context, no exclusions' rather than full 'when/when-not/alternatives'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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 lists the exact Shopline APIs called (all GETs, implying read-only), explains the underlying algorithm, discloses the 30-product limit to avoid rate limiting, and describes the return structure. It does not mention permissions or error scenarios, but for a read-only analytical tool this is reasonably transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with labeled sections for purpose, API calls, and return structure. Each section provides useful information without excessive verbosity. The only slight redundancy is that the parameter logic appears in both the purpose and the schema, but this is acceptable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool of moderate complexity (multi-API calls, algorithm, rate-limit caveat), the description is quite complete. It explains input (optional threshold), output fields, and underlying data sources. With no output schema, the return structure is explicitly described. Missing details like error handling or explicit permission requirements are minor gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents min_stock_diff with 100% coverage, including its default and meaning. The description adds value by embedding the parameter in the algorithmic logic ('差值 >= min_stock_diff') and clarifying its role in triggering suggestions, which reinforces the schema's description and provides behavioral context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb '自動產生' (auto-generate) and the resource '跨倉庫庫存調撥建議' (cross-warehouse stock transfer suggestions). It explains the specific logic (threshold-based transfer suggestions) and distinguishes itself from sibling tools like get_stock_by_warehouse or get_inventory_overview by focusing on actionable suggestions rather than raw stock views.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly outlines the use case: to generate transfer recommendations based on inter-warehouse stock differences. It does not explicitly name alternatives or exclusions, but the purpose is self-evident and the tool's unique value proposition is clear. The note about analyzing only the first 30 products also provides context for when this might be insufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It transparently discloses the conditional selection of API endpoints based on search_keyword, and describes the return structure including fields and currency (TWD). It does not explicitly state read-only safety, but the verb '取得' implies a non-mutating operation. It also does not cover rate limits or authentication, but for a simple list tool this is acceptable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with distinct sections for purpose, API calls, and return structure. The opening line serves as a concise summary, and each section adds relevant detail. There is a slight redundancy between the opening line and the purpose section, but it does not detract from overall clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that there is no output schema, the description compensates by outlining the return structure (dict with total_found, returned, items[]) and the item fields. It also explains the two API endpoints and the search behavior. Missing details such as maximum limit enforcement or error handling are not critical for a straightforward listing tool, making this sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although the input schema already describes both parameters (100% coverage), the description adds meaningful behavior beyond the schema by stating that providing a search keyword triggers the search endpoint, otherwise the list endpoint is used. It also clarifies that search_keyword refers to the addon product name. This extra context elevates the parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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 addon products list) and supports keyword search. It specifies the resource (Addon Products) and distinguishes it from sibling create/update/addon tools by being a read/list operation. The conditional endpoint behavior further clarifies its purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit context for when to use the tool: '瀏覽或搜尋商店所有加購商品' and '適合分析加購策略與商品搭配情況'. It also explains the conditional behavior between list and search endpoints. However, it does not explicitly mention when not to use it or name alternative tools, just missing the exclusionary guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes beyond the basic function by disclosing potential 403 errors under certain token permissions, and explains that platforms_failed indicates partial failures, warning against interpreting empty results as 'no channels'. This is valuable behavioral context, especially with no annotations provided.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with sections for purpose, usage, API endpoint, and return structure. Each section provides essential information without unnecessary fluff, making it easy for an agent to quickly parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given a single optional parameter, no annotations, and no output schema, the description is remarkably complete. It explains the return structure, fields, failure modes, and caveats, giving the agent all necessary context to use the tool correctly and interpret results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter `platform` is fully documented in the schema with examples and default behavior (auto-query common platforms and merge results). The description adds no extra semantic value beyond repeating the schema, so a baseline score of 3 is appropriate for full schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves the list of all sales channels (取得商店所有銷售渠道清單) with examples like online store, POS, Facebook, Instagram. It is clear about the resource and action, but does not explicitly differentiate from sibling tools like get_channel_detail, though the 'list' vs 'detail' distinction is implied.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides use cases: '適合了解多渠道銷售佈局，或做渠道業績分析前的渠道資料確認' (suitable for understanding multi-channel layout or confirming channel data before performance analysis). It does not mention alternative tools to use instead, but gives clear contextual guidance on when to invoke this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It does disclose the HTTP method (GET /v1/custom_fields) and return structure, implying a read-only operation. However, it omits details like authentication requirements, potential rate limits, or whether empty results are handled, so transparency is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured with sections for purpose, API call, and return structure. Each line adds value without redundancy, and the main summary is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity (no parameters, no output schema) the description is complete: it defines the tool's purpose, the exact API endpoint, and the return format with field examples. This 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.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters and the schema is empty, so the baseline is 4. The description adds no parameter semantics because none exist, but it does explain what the return dict contains, which is more relevant here.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states '取得商店定義的客戶自訂欄位清單' (get the store's list of custom fields for customers), specifying a concrete verb and resource. It distinguishes itself from sibling tools like list_customers or list_customer_groups by focusing on custom field definitions rather than customer data or groups.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use it: to understand customer data structure or analyze data completeness. It provides clear context but does not explicitly mention when not to use it or name alternative tools, so it falls short of full guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses the underlying API endpoint (GET /v1/payments), the return structure (dict with total and payments[]), and key fields. It also clarifies that only enabled payments are returned. This goes beyond a minimal description, though it omits potential edge cases like pagination or error behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured into purpose, API, and return sections. It is slightly verbose but every section adds relevant information. The main sentence is front-loaded and clear, with no redundant filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple zero-parameter list tool, the description covers purpose, use cases, API endpoint, and return structure. It lacks details like pagination or authentication requirements, but those are likely unnecessary for this tool's simplicity. Overall, it is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the input schema is empty and schema coverage is 100%. The description adds value by detailing the return structure and field names, which is useful for an agent even without parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function as retrieving the store's enabled payment methods (取得商店啟用的付款方式清單), with specific examples like credit card, ATM, and cash on delivery. This is a specific verb+resource statement that distinguishes it from other list_* siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear use cases: confirming available payment channels and as a reference for order payment analysis. It does not explicitly mention exclusions or alternatives, but the context is clear enough for an agent to decide when to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully carries the burden of behavioral disclosure. It explicitly lists side effects (coupon becomes used, affects statistics, irreversible), gives the return structure, and notes the API endpoint. This exceeds typical transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized with clear sections for purpose, usage, API, return structure, and side effects. Every section is informative and no content is redundant. It is appropriately sized and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is complete for a mutation tool with no annotations and no output schema: it covers purpose, appropriate scenarios, the underlying API call, return structure, and side effects including irreversibility. It provides sufficient context for an agent to invoke the tool safely.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter is coupon_data, and the schema description already provides a basic meaning (usually contains coupon_code and order/customer info). The tool description adds no additional parameter elaboration, so the score stays at the baseline of 3 given 100% schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: '核銷（使用）優惠券' (redeem/use coupon) and marks it as used. However, it does not explicitly differentiate from sibling tools like claim_coupon, so it misses the top score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when to use this tool ('適合 POS 場景或 API 整合的結帳流程' - suitable for POS scenarios or API-integrated checkout flows), but it does not mention alternatives or exclusions, such as not using it for claiming coupons.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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 side effects: coupon appears in customer account, quantity limits may cause errors, and some coupon types cannot be recalled. It also mentions the API call and error conditions. However, it does not discuss idempotency, auth requirements, or rate limits, which are relevant 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized with clear sections: purpose, API endpoint, return structure, and side effects. It starts with a concise one-line summary and each section contributes valuable information without redundancy. The length is appropriate for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description explicitly defines the return structure (dict with success, resource_id, message, result). It covers purpose, API, side effects, and error conditions. For a simple write tool with one parameter, this is highly complete and leaves no significant gaps for an agent to misuse it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has one parameter, coupon_data, with a description: "優惠券發送資料，通常包含 coupon_id 與目標客戶識別資訊". Since schema description coverage is 100%, the baseline is 3. The tool description itself does not add further detail about the parameter structure beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear, specific statement: "[WRITE] 發送優惠券給指定客戶" (Send coupon to specified customer). This directly states the action (send), resource (coupon), and target (specified customer), and also lists common use cases like marketing campaigns and CRM triggers, which differentiate it from sibling tools such as claim_coupon and redeem_coupon.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context: "常用於行銷活動、客戶回饋、CRM 觸發場景" (commonly used in marketing campaigns, customer feedback, CRM trigger scenarios). It does not explicitly name alternatives or state when not to use the tool, but the '主動' (proactive) framing implies distinction from customer-initiated actions like claim_coupon.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior5/5
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.
Conciseness4/5
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.
Completeness5/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior5/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior5/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior5/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses the underlying GET /v1/products call, the aggregation of locked_inventory_count, and the fact that a direct endpoint does not exist, preventing a 422 error. It also lists the return structure fields, adding operational context like products_scanned. However, it does not discuss rate limits or pagination details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is structured with clear sections: purpose, API call, note, and return structure. It is dense but not bloated; the API note adds transparency about implementation, though some may consider it extra. Every sentence contributes to understanding the tool's behavior.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter read-only inventory tool, the description is complete: it states purpose, method, the quirk of the missing endpoint, and the exact return fields. This provides enough information for an agent to invoke and interpret the tool without external documentation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes no parameters, so schema coverage is 100% and there is nothing to document. The description adds value by describing the return structure, which helps the agent understand the output even though no parameters exist. This is the expected baseline for a zero-parameter tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it gets a list of inventory items currently locked (reserved), with a specific focus on analyzing SKUs with pending shipment reserved quantities. This is a specific verb+resource+scope that distinguishes it from sibling inventory tools like get_inventory_overview or get_low_stock_alerts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when an agent needs to analyze which SKUs have reserved quantities pending shipment. It also provides a technical note about the Shopline API endpoint limitation, explaining why the tool exists. However, it does not explicitly name alternative tools to use instead or provide exclusion criteria, so it is clear context without explicit alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the burden. It discloses the underlying Shopline API endpoint (GET /v1/orders/{order_id}/labels) and the raw response structure with labels array containing tracking_number, carrier, and label_url. It does not cover error handling or side effects, but for a read-only GET tool this is reasonable transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with sections for purpose, note, API call, and return structure. Each section provides distinct value: disambiguation, endpoint, and output shape. No wasted sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter) and lack of annotations/output schema, the description provides a complete picture: what it returns, how to access it, and how it differs from a similarly named tool. It could mention when not to use it beyond the tags distinction, but overall it's adequately complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already describes the only parameter order_id with clear documentation that it is the internal ID from query_orders, so description coverage is 100%. The tool description adds no extra parameter semantics beyond the schema, meriting the baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves shipping label information (物流面單/寄送單) for a specified order, including tracking number and carrier. It explicitly distinguishes from get_order_tags, showing precise scope and verb usage.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides an explicit alternative: '要查訂單分類用的標記請用 get_order_tags' (use get_order_tags for order classification tags), and clarifies that label here is not the same as tags. This is a clear when-not/alternative statement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full responsibility for behavioral disclosure. It transparently describes the operation as a query (查詢) and specifies the underlying Shopline API call as GET /v1/products/search?sku={sku}, implying a read-only side-effect-free action. It also discloses that it returns variant details (matched_variants) beyond the basic product info. However, it does not explicitly state error behavior or response structure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three concise, information-dense sentences plus the API endpoint. It front-loads the primary purpose, then the usage comparison, then guidance, with no redundant filler. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
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 adequately covers the purpose, usage context, return content (stock, price, image URL, matched_variants), and the underlying API. It misses exact response structure/format, but this is acceptable given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides 100% coverage for the single parameter `sku`, describing it as '商品或變體的 SKU（完全相符）' (product/variant SKU, exact match). The description adds minimal extra meaning — it reiterates the precise SKU query and mentions variant details, but does not introduce new parameter semantics beyond what the schema already contains.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: '以 SKU 精準查詢單一商品的貨況（庫存、價格）與商品圖 URL' (query a single product's stock/price and image URL by SKU). It also distinguishes itself from the sibling get_product_list by noting it extracts matched_variants for a single SKU, making it more direct for single-item queries.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit usage guidance is provided: use this tool for single-SKU queries ('查單一貨品時讀起來更直接'), and use get_product_list when querying multiple conditions or listing items ('需要一次查多個條件或列清單時請用 get_product_list'). It also mentions the functional equivalence to get_product_list(sku=...), clarifying the relationship.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of disclosing behavior. It explains that full scans make one API call per product, are constrained by max_products, and return scan_truncated to indicate truncation. This is valuable operational context, though it does not cover the full return shape or 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded, using two short paragraphs to convey purpose, query modes, and an important truncation caveat. Each sentence earns its place with no filler or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no output schema and no annotations, the description covers the primary invocation modes, the warehouse filter concept, and the critical max_products/scan_truncated edge case. It does not specify the exact fields of the returned matrix, but the core usage and behavioral caveats are sufficiently addressed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already describes all four parameters, providing a baseline of 3. The description adds meaningful context by explaining the performance implications of max_products and by recommending sku or product_id for fast, complete lookups. It also links the scan_truncated flag to the full-scan behavior, which goes beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as retrieving a stock distribution matrix across warehouses and stores, for either a single product or all products. This is a specific verb-plus-resource statement that distinguishes it from broader inventory tools by emphasizing per-warehouse/store granularity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly instructs users to pass sku or product_id when querying a specific item and warns that an unconditional full scan is slower and limited by max_products. It provides clear parameter-selection context, though it does not name alternative tools or state explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full transparency burden. It discloses that the tool scans all orders in the range (performance implication) and only includes sold products. It doesn't mention read-only status explicitly, but the behavior is consistent with a read-only ranking tool and no side effects are implied.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences: first states what the tool does, second states exclusions and directs to an alternative. Every word serves a purpose, and the structure front-loads the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose, exclusions, and performance considerations for a 5-parameter tool with no output schema. It does not explicitly describe the return structure (e.g., product fields), but the tool name and ranking nature make this somewhat predictable, and the performance warning adds valuable context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds no extra parameter-level detail beyond the schema, though it reinforces the role of sort_by and mentions date-range performance in the start_date description within the schema itself. The tool description itself does not add new parameter meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool gets a product sales ranking for a specified time range, sorted by quantity or revenue. It distinguishes itself from related tools by explicitly excluding unsold/slow-moving items and pointing to get_slow_movers as the alternative.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit usage context: use for ranking products that have been sold, and explicitly directs users to get_slow_movers for unsold or low-moving items. Also includes performance guidance to keep date ranges short, helping agents decide how to invoke the tool efficiently.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full behavioral burden. It discloses important traits: the return structure (fetched, returned, platforms_queried, platforms_failed, conversations), per-conversation fields, and a caveat that fetched is not the total but the actual count due to quota limits. It stops short of explicitly stating auth requirements or confirming read-only behavior, but for a list operation 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with labeled sections (用途, 呼叫的 Shopline API, 回傳結構) and front-loaded with purpose. It is slightly longer than necessary due to the detailed return structure, but every section adds value and it remains focused.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 optional params, no output schema), the description is thorough: it explains the purpose, API call, return structure, and a notable behavioral nuance about quota limits. It even directs the user to the appropriate next-step tool, making it complete for successful invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%: both platform and max_results have detailed descriptions in the schema, including enum-like values and default behavior. The tool description adds some context via the API endpoint and return structure, but does not meaningfully enhance parameter understanding beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear verb+resource statement ('取得客服對話列表' – get customer service conversation list), then explains it provides a summary list of all conversations. It explicitly distinguishes itself from the sibling tool get_conversation_messages by noting that full message history requires that tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states the use case: to browse conversation summaries and identify which conversations need further inspection. It then provides a direct call-to-action to use get_conversation_messages for full chat history, making the when-to-use and alternative clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses the underlying API endpoint (GET /v1/user_credits), and the complete return structure including all fields (total_found, returned, total_balance, credits[] with customer_id and balance). This is substantial behavioral context. It does not explicitly state that this is a read-only operation or mention rate limits, but for a listing tool with no mutation, this is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized with clear sections (用途, API, 回傳結構). Every sentence adds value, and the information is presented in a scannable structure. It is neither too terse nor excessively verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is highly complete for a list tool: it states the purpose, use cases, underlying API, and detailed output structure. Since no output schema exists in the tool definition, this in-description return schema is essential. It lacks explicit pointers to sibling operations or pagination behavior, but remains sufficient 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.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter max_results is fully described in the schema ('最多回傳筆數'), giving 100% coverage. The description adds context by explaining the response contains 'total_found' and 'returned', helping the agent understand the effect of max_results. It does not fully compensate for any ambiguity about 'all customers' vs. the maximum results limit, but the schema already handles the parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear verb+resource statement: '取得所有客戶的儲值金餘額列表' (get all customers' store credit balance list). It specifies the resource (store credit balances) and distinguishes this from sibling tools like update_customer_store_credits, which is a write operation. It also adds use cases, reinforcing specificity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly explains when to use the tool: '瀏覽客戶儲值金餘額概況' (browse overview), and gives concrete applications like calculating store credit liability ('計算儲值金負債') and identifying high-balance customers ('找出高餘額客戶'). However, it does not mention alternatives or when not to use it, so it stops short of a full 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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 reveals side effects: immediate status change, impact on frontend/reports, possible customer notifications, and errors for invalid statuses. It also discloses that each non-None parameter invokes a separate API call, adding transparency beyond just saying 'update'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with headers (用途, API calls, 回傳結構, 副作用) and bullet lists. Every section delivers distinct information, and there is no redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is complex due to multiple possible API calls per invocation. The description compensates for lacking an output schema by stating the return dict structure and lists side effects and error conditions. However, it does not address partial success scenarios or permission requirements, leaving some completeness gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage with examples for all four parameters. The description adds significant meaning by explaining the non-None conditional behavior and mapping each parameter to a specific PATCH endpoint, which is not apparent from the schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with '[WRITE] 更新訂單狀態（支援同時更新多種狀態）', which clearly identifies the verb (update) and resource (order status). It further distinguishes the three sub-statuses (main, delivery, payment), setting it apart from sibling tools like update_order or cancel_order.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 【用途】 section explicitly says the tool updates main, delivery, and payment statuses individually or together, giving clear context for when to use it. It also explains that only non-None parameters trigger API calls, but it does not name alternative tools or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It discloses the write nature, immediate front-end effect, irreversibility, and the partial-update behavior. It could add error conditions or permission requirements, but covers key side effects well beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (purpose, API, return, side effects), front-loaded with [WRITE] and purpose. It is concise for the information it conveys, with no redundant sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no output schema, it covers purpose, endpoint, return structure, side effects, and partial update behavior. Missing details like error handling or authorization are minor given the tool's complexity and the richness of the provided information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds value by giving concrete examples of updatable fields (name, description, category, status) and explaining the partial-update semantics, which is not fully captured by the schema's generic product_data description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it updates existing product basic information, listing specific fields (name, description, category, status). The [WRITE] marker and API endpoint reinforce the action. It distinguishes itself from sibling tools like update_product_quantity and update_product_price by focusing on '基本資料' rather than specific attributes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear context for when to use—when modifying existing product fields—and describes partial-update behavior ('only pass fields to modify, unspecified fields are not overwritten'). It does not explicitly name alternatives or exclusions, but the field focus and sibling context make appropriate usage clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It discloses that changes take effect immediately, that changing the rating will sync the product's average rating, and that the operation is irreversible but can be overridden by calling again. It also provides the return structure (dict with success, resource_id, message). This is rich, non-obvious behavioral context far beyond a simple 'update' statement.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections: 用途 (purpose), 呼叫的 Shopline API (called API), 回傳結構 (return structure), and 副作用 (side effects). Every section provides necessary information without redundancy. The opening line is front-loaded with the action and resource. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (2 params, no output schema) and the description covers purpose, usage context, API endpoint, return structure, and side effects. This is near-complete for an update operation. It lacks mention of error cases or prerequisites (e.g., what happens if comment_id does not exist), but given the tool's straightforward nature and the presence of return structure, the description is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%: both comment_id and review_data have meaningful descriptions, with review_data including an example object. The tool description adds minimal extra parameter info, only hinting at updatable fields in the purpose section. Baseline of 3 is appropriate since the schema already does the heavy lifting and the description does not significantly enhance parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with '更新單筆商品評論' (update single product review), clearly stating the verb and resource. It further specifies fields like content, moderation status, and rating, and names the exact API endpoint PATCH /v1/product_review_comments/{comment_id}. This clearly distinguishes it from sibling tools like create_product_review or bulk_update_product_reviews.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states an explicit use case: '適用於客服審核或編輯不當評論' (suitable for customer service moderation or editing inappropriate reviews), providing clear context. However, it does not explicitly contrast with alternatives such as bulk_update_product_reviews or delete_product_review, nor does it state when not to use this tool. Thus it has clear context but lacks exclusions/alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses side effects (immediate balance change, points history recording), an error condition (deduction may fail if insufficient points), and the return structure. This is rich behavioral context well beyond a basic operation statement.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear section headers (用途, API, 回傳結構, 副作用), front-loaded with the [WRITE] flag and purpose. Every section adds value and the length is justified for a write operation with no annotations.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a write tool with no annotations and no output schema, the description covers purpose, usage scenarios, the underlying API endpoint, return structure, and side effects. It even references a sibling tool for verification. It is fully sufficient for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for all three parameters, including the sign convention for points. The description does not add additional parameter-level meaning beyond what the schema already provides, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with '[WRITE]' and explicitly states the tool's function: increasing or deducting customer member points, with concrete use cases (manual top-up, promotional gifts, complaint compensation). This clearly identifies the action and resource, distinguishing it from sibling read-only tools like list_member_point_rules.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description specifies when to use the tool: '常用於手動補點、活動贈點、客訴補償等場景' (commonly used for manual point additions, promotions, and complaint compensation). It provides clear context but does not explicitly state when not to use it or name alternative tools, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior5/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior5/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior5/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior5/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior5/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior5/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior5/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior5/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior5/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior5/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior5/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior5/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior5/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior5/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior5/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It discloses that the tool aggregates data from five different API calls and returns a dict with five sections. It also notes that amounts are float in TWD. It does not explicitly state read-only behavior or potential latency from multiple calls, but the 'get' semantics and endpoint listing make it sufficiently transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized with a summary, usage section, API list, and return structure. Each sentence adds value; it is longer than minimal but justified by the tool's aggregation complexity. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having no output schema, the description clearly explains the return structure (dict with five sections) and data types. It names all involved endpoints, which helps the agent anticipate the tool's scope. The differentiation from get_rfm_analysis covers a key sibling relationship. Complete for practical use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (customer_id is documented as the internal ID from list_customers). The description adds no additional parameter-specific detail beyond the schema, but it does reinforce that this is a single-customer query. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves a single customer's complete profile (basic info, store credit, points, tier history, coupons) with a specific verb ('取得') and resource. It distinguishes itself from the sibling get_rfm_analysis for batch analysis, making its purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit usage context: suitable for customer service or individual member analysis, and explicitly directs batch analysis to get_rfm_analysis. It also lists the exact underlying Shopline API endpoints, giving the agent clear expectations of scope.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses the HTTP GET endpoint, the return structure in detail, and the key fields. It does not mention error handling, permissions, or rate limits, but for a read-only retrieval tool, the disclosed information is substantive and exceeds a minimal description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and front-loaded, starting with the primary purpose before breaking into clearly labeled sections (用途, API, 回傳結構). Every sentence provides necessary information, and the formatting makes it easy to scan. No redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one required parameter, no output schema), the description is comprehensive. It explains what the tool does, when to use it, how to get the required ID, the underlying API call, and the complete return structure. This covers all essential context an agent would need for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides a description for delivery_id, but the tool description adds meaning by noting the ID comes from get_order_detail's shipments/deliveries fields, reinforcing the source and providing field-level context that is not explicitly in the schema. With high schema coverage, this additional context justifies a score above baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves complete information for a single delivery order, including logistics status, tracking number, and recipient address. It distinguishes itself from siblings by referencing get_order_detail as the source of the delivery ID, making its specific resource and action clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The '用途' section explicitly states use cases (tracking packages, confirming recipient info, customer service) and explains that the delivery ID typically comes from get_order_detail's shipments/deliveries fields. However, it does not explicitly state when not to use it or name alternatives beyond the implied get_order_detail, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the transparency burden. It discloses the output contents (inventory matrix and image URL) and even mentions the underlying Shopline API endpoint. However, it does not address error cases (e.g., invalid product_id) or response structure in detail, though for a read-only query this is a minor gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: first sentence states the purpose, second provides usage guidance, third offers an alternative, and the final block gives the API endpoint. Every sentence is essential, and the key information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool with one parameter and no output schema, the description is complete: it specifies the use case, the required input, the return content, and even the underlying API call. It fully compensates for the lack of annotations and output schema given the tool's low complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with the product_id parameter already described as coming from get_product_list / get_product_by_sku. The description reinforces this prerequisite, but adds no new semantic detail beyond the schema, so it stays at the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb '取得' (get) and the resource '特定商品的所有 SKU 變體明細' (all SKU variant details for a specific product), further detailing the size×color inventory matrix and image URL. This clearly distinguishes it from sibling tools like get_product_list and get_product_by_sku by emphasizing the variant matrix scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use the tool: when the product_id is already known and a complete variant matrix is needed. It also explicitly directs users to get_product_by_sku / get_product_list first if only SKU or product name is known, providing clear alternatives and exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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 /v1/token/info) and the return structure, and uses '查詢' to imply a read-only operation. However, it doesn't explicitly state there are no side effects or mention any auth requirements for the call itself.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear headings (用途, 呼叫的 Shopline API, 回傳結構). It is concise yet informative, with every section adding value and no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter read-only tool, the description covers the purpose, use case, underlying API endpoint, and return structure fields. Since there is no output schema, this description adequately compensates.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, so the baseline is 4. No additional parameter semantics are needed, and the description appropriately focuses on the return structure.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verbs '取得/查詢' and clearly states it retrieves the current API token's information including merchant, scopes, and expiry. This is unique among siblings, all of which focus on other domains, making it easy to distinguish.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly describes use cases: troubleshooting API access issues and verifying token permissions. This gives clear context for when to use the tool, though it does not mention alternatives or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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 discloses the two underlying API endpoints (GET /customer_groups and /search) and the return structure, which provides meaningful transparency. It does not mention pagination limits or error behavior, but the disclosed info is substantial.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized with sections for purpose, API calls, and return structure. The main summary sentence is front-loaded, and every section earns its place without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
As a simple list tool with no output schema, the description fully compensates by explaining the return structure (total_found, returned, groups[]) and the group fields. It also covers use cases and API behavior, 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.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for both parameters, so the baseline is 3. The description adds value by clarifying that search_keyword determines which API is called (search endpoint vs. list endpoint), giving behavioral context beyond the schema's simple field descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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 customer group list, supports searching by name). It distinguishes itself from sibling tools like get_customer_group_members by noting it provides group IDs for further member queries.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The '【用途】' section explains when to use the tool (browse/search groups, confirm segmentation strategy, get group ID for member lookup). It implies a workflow but does not explicitly name alternatives or state when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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 reveals the underlying API call (GET /v1/delivery_options), which implies a read-only operation, and describes the return structure with fields like id, name, delivery_type, status, fee_type, rates, supported_countries, and support_cod. This exceeds a bare listing but stops short of disclosing pagination, auth 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear headings: purpose, API call, and return structure. It is front-loaded with a one-sentence summary and then expands with useful details. Every section adds value and nothing is redundant or verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with no parameters and no output schema, the description covers all necessary aspects: purpose, use cases, the exact API endpoint, and the return structure including key fields. It is self-contained and gives the agent enough 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.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema is empty (0 parameters), so there is no parameter detail to clarify. Per the guidelines, 0 params yields a baseline of 4. The description appropriately focuses on output rather than parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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 the list of enabled delivery options). It specifies the resource (delivery options), the verb (list/get), and the scope (enabled ones). This distinguishes it from the sibling tool get_delivery_option_detail, which fetches a single option.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 【用途】section explicitly states suitable use cases: '適合確認可用配送渠道或分析訂單配送偏好' (suitable for confirming available delivery channels or analyzing order delivery preferences). It provides clear context but does not mention exclusions or alternatives, so it earns a 4 rather than a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of disclosing behavior. It explicitly reveals the API endpoint (GET /v1/member_point_rules) implying a read-only operation, and outlines the return structure (dict with total and rules[]). It stops short of discussing authentication, rate limits, or error handling, but for a simple listing tool the level of detail 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections: a one-line summary, purpose, API call, and return structure. Each section adds value without redundancy. The main verb and resource are front-loaded, making it easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given its simplicity (zero parameters, no output schema), the description provides the essential details: what the tool does, the API call, and what the response contains. It names fields like id, name, type, value, and conditions, which is enough for an agent to understand the tool's output. No additional context appears necessary.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, so the baseline is 4. The description adds no parameter-specific information, and none is needed. It also does not contradict the schema, as the schema remains complete with 100% coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves the store's member point rules settings, with specific examples of rule types (consumption reward ratio, point expiration). This distinguishes it from sibling tools like list_membership_tiers (tiers) or adjust_customer_member_points (modification) since it focuses on rules configuration.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly notes the intended use cases: analyzing membership loyalty programs and comparing customer point changes. It does not identify when to avoid this tool or mention specific alternatives, but the clear purpose provides adequate contextual guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses the underlying Shopline API endpoint (GET /v1/membership_tiers) and the return structure (dict with total and tiers[] including id, name, threshold, benefits), implicitly signaling a read-only operation. It lacks explicit statements about safety, rate limits, or pagination, but for a zero-parameter list operation, this is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured, with labeled sections for purpose, API, and return structure. It is front-loaded with the main action, and every sentence provides useful information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no params, no output schema), the description is complete: it specifies the exact purpose, the API call, and the expected return shape with key fields. An agent can confidently invoke this tool without additional context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and an empty schema, so there is nothing to describe. The baseline for zero-parameter tools is 4, and the description appropriately adds no parameter-specific information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states it retrieves all membership tier definitions for a store, using a specific verb '取得' and resource '會員等級'. It also mentions the use cases (analyzing membership structure or confirming tier settings), which clearly distinguishes it from related sibling tools like list_member_point_rules or get_customer_tier_history.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
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: to view membership tier definitions, upgrade thresholds, and benefits, for analyzing membership structure or confirming settings. However, it does not explicitly state when not to use it or name alternative tools, so it falls short of a perfect 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Since no annotations are provided, the description carries the full burden. It discloses the underlying API endpoint, the return structure (dict with total and merchants[]), and the fields per merchant. It does not mention pagination, errors, or rate limits, but for a simple read-only list tool, this is reasonable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
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 uses concise, information-dense sentences. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, no-output-schema tool, the description is highly comprehensive. It explains the merchant scope, the exact API path, and the response shape including field names, which is more than sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the schema is empty. Per the rubric, 0 params yields a baseline of 4. The description adds no parameter-specific info because none are needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves all merchants ('取得所有商家清單') and elaborates that it lists merchant accounts accessible by the API token. This distinguishes it from siblings like get_merchant_detail, which retrieves a single merchant, and other list tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides a clear usage context: confirming the merchant scope in multi-merchant environments ('適合多商家環境下確認可操作的商家範圍'). However, it does not explicitly name alternatives or state when not to use it, 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description properly carries the burden by disclosing the API endpoint (GET /v1/product_review_comments), the return structure (dict with total_found, returned, reviews[]), and per-review fields (id, product_id, product_name, rating, content, created_at). It also notes that content is a summary and product_name defaults to Chinese, adding useful behavioral context. It doesn't explicitly state pagination or rate limits, but the provided details are solid.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections for purpose, usage, API, and return structure. Each sentence delivers useful information without redundancy or fluff, making it appropriately sized and easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (1 optional parameter, no output schema), and the description covers all essential aspects: purpose, usage alternative, API endpoint, and detailed return structure. It is complete enough for an agent to invoke correctly without needing further elaboration.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema already fully describes the only parameter (max_results with default 50 and Chinese description). The tool description does not add extra semantics beyond what the schema provides, so the baseline of 3 applies; the schema covers 100% of parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb '取得' (get/list) and resource '商品評價列表' (product review list), clearly stating it lists product review summaries. It also distinguishes itself from get_product_review_detail by noting the sibling handles full review content, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit use cases: monitoring review quality, finding low-rated products, tracking recent comments. It also directly names the alternative tool (get_product_review_detail) for full content with images and merchant replies, making when-to-use and when-not-to-use crystal clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the behavioral transparency burden. It compensates by disclosing the return structure (dict with total_found, returned, items[] and item fields) and the API endpoint GET /v1/product_subscriptions. This goes beyond a basic statement, though it does not explicitly mention it is read-only or discuss pagination behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with sections for purpose, usage, API endpoint, and return structure. The first sentence front-loads the purpose, and every section adds meaningful information without redundancy. It is appropriately sized for the tool's simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
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 provides a complete overview: it explains what the tool does, how to use it (with a pointer to the detail tool), the API endpoint, and the exact return structure. This is fully sufficient for a list tool with one optional parameter.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for the only parameter (max_results with '最多回傳筆數'), so the schema already fully documents it. The description adds no additional parameter semantics, leaving the baseline at 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool '取得商品訂閱列表' (get product subscription list) with a specific verb and resource. It further elaborates on listing all subscription records to understand customer subscriptions, statuses, and cycle settings, and explicitly references the sibling tool get_product_subscription_detail for full details, distinguishing it from similar list tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit usage context: it is suitable for analyzing subscription revenue and customer retention, and it advises calling get_product_subscription_detail after obtaining subscription_id for complete details. This provides a clear alternative and conditions for use, fulfilling the when/alternatives guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses the underlying API call (GET /v1/taxes) and the return structure (dict with total, taxes[], and fields like id, name, rate, included_in_price). This gives the agent a clear expectation of output, though it does not explicitly state read-only semantics, the name 'list' and 'GET' imply it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear headers (【用途】, 【呼叫的 Shopline API】, 【回傳結構】) and every sentence provides value. It is compact, front-loaded with the main purpose, and avoids any filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple no-argument list operation, the description is complete: it covers purpose, usage context, API endpoint, and return structure. Since there is no output schema, the description properly fulfills the need to explain the return format.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema coverage is trivially 100%. The description correctly does not add unnecessary parameter details, earning the baseline of 4 for a no-parameter tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with '取得商店設定的稅率清單' (get the store's configured tax rate list), which is a specific verb+resource statement. It also provides examples (營業稅、消費稅) and clearly distinguishes itself from all sibling tools that focus on orders, products, customers, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 【用途】 section states when to use this tool: '適合確認稅率設定或在財務分析時核對稅務規則' (suitable for confirming tax settings or checking tax rules during financial analysis). This provides clear context, though it does not explicitly mention alternatives or when-not-to-use, which is acceptable given no comparable tax tool exists among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
由於沒有 annotations，描述完全承擔了行為揭露的責任。它明確說明副作用：在買家對話收件匣新增訊息、買家即時收到通知、訊息送出後無法撤回或修改，並提供回傳結構與呼叫的 API，讓 agent 充分理解此操作的不可逆性及影響。
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
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.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
作為一個帶有巢狀物件參數的寫入工具，描述完整涵蓋了副作用、回傳結構、適用情境與底層 API。雖然無輸出 schema，但已提供足夠資訊供 agent 判斷是否使用及預期結果，整體完整性高。
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
輸入 schema 對唯一參數 message_data 有 100% 描述覆蓋，包含型別與範例，因此 schema 已承擔主要說明責任。描述本身未額外補充參數語法或格式細節，符合 baseline 3 的情境。
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
描述以明確的動詞與資源說明工具用途：'發送與特定訂單相關的對話訊息'，並補充適用於出貨通知、客服回覆等情境。這與兄弟工具 send_shop_message 形成對比，能清楚區分這是一個針對特定訂單的訊息發送工具，而非一般店鋪訊息。
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
描述列出具體適用場景（出貨通知、客服回覆、訂單異常說明），提供清晰的使用情境。但未明確指出何時不應使用此工具，也未提及替代工具（如 send_shop_message），因此缺少排除性指引。
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully discloses the write behavior via the '[WRITE]' tag and side effects: immediate balance change, history record via get_customer_profile, and possible insufficient-balance error. It also gives the return structure, making behavioral expectations transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is well-structured with clear sections (purpose, API, return, side effects) and front-loaded with the write intent. Every sentence provides distinct value; no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is complete for a mutation tool: it states purpose, underlying API, return schema, and side effects/error conditions. Without an output schema annotation, providing the return structure is valuable. No significant gaps are apparent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 100% of parameters with descriptions, including amount's positive/negative semantics and note as a reason. The description adds no additional parameter-level detail beyond the schema, so it meets the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with '[WRITE] 調整客戶儲值金餘額' and explicitly states '增加或扣除客戶儲值金', using a specific verb and resource. It clearly identifies the tool as adjusting store credit balances, distinguishing it from sibling read tools like list_store_credits and point adjustment tools like adjust_customer_member_points.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description lists concrete use cases: '儲值金充值、退款補償、活動贈送' (top-up, refund compensation, event gifting), giving clear context for when to use. However, it does not explicitly name alternatives or state when not to use this tool, so it falls short of the top score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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 that modifications take effect immediately, are irreversible, but can be overwritten by calling again. It also specifies the return structure (success, resource_id, message). This goes beyond a basic functional statement and provides meaningful 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.
Conciseness5/5
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), starting with the core action. Every section provides necessary information without fluff, making it concise and easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description fully covers return values. It also addresses side effects and API details, which are essential for a write operation. The tool has only two parameters, and the description covers its purpose, usage, and behavior completely.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 100% coverage for both parameters, but the description adds value by clarifying the partial-update behavior ('僅傳入要修改的欄位') and listing example fields (name, quantity, image). This helps the agent understand that gift_data should be a partial object, not a full replacement.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with '更新贈品資料' and specifies '修改指定贈品的名稱、數量、圖片等欄位', clearly stating the tool updates gift data and which fields are involved. This provides a specific verb+resource+scope, distinguishing it from generic actions. Though a sibling tool update_gift_quantity_by_sku exists, the description's field list makes the general-purpose nature clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes the explicit usage note '僅傳入要修改的欄位', telling the agent to pass only fields to be updated for a partial update. This is clear contextual guidance on how to use the tool, but it does not mention alternatives or explicitly when not to use it, so it misses the highest tier.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It explicitly labels the operation as [WRITE], details side effects (quantity will be overwritten, changes take effect immediately, affecting gift availability), and describes the return structure. This is thorough behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (Purpose, API Called, Return Structure, Side Effects) and is appropriately sized. The [WRITE] prefix and main action are front-loaded, and every sentence contributes to understanding the tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple 2-param write tool with no output schema or annotations, the description is complete. It covers purpose, usage context, exact API endpoint, return structure, and side effects. No critical information is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with both sku and quantity described meaningfully (quantity as absolute value, not difference). The description reinforces this by noting the overwrite behavior, but adds little new parameter-specific information beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: '依 SKU 更新贈品庫存數量' (update gift inventory quantity by SKU). It uses a specific verb (update), identifies the resource (gift inventory quantity), and specifies the indexing method (by SKU), distinguishing it from sibling tools like update_gift or update_addon_product_quantity_by_sku.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides usage context: '適合批次庫存同步場景' (suitable for batch inventory sync scenarios) and notes the direct SKU-indexed approach. It does not explicitly mention when not to use this tool or alternative tools, 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.
Behavior5/5
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 changes take effect immediately, status changes may trigger automatic notifications (e.g., shipping confirmation emails), and the operation is irreversible but can be overwritten by calling the tool again. This is comprehensive and goes well beyond the minimum.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear labeled sections: purpose, usage, API call, return structure, and side effects. It is concise but information-dense, with every section providing relevant detail. The [WRITE] prefix immediately signals the operation type.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description compensates for the lack of an output schema by explicitly describing the return structure (dict with success, resource_id, message). It covers usage context, the underlying API endpoint, side effects, and potential notifications. This is complete for a mutation tool with no annotations or output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers both parameters with descriptions that already explain delivery_id and delivery_data (including an example). The tool description adds only a brief mention of fields like tracking_number, carrier, and status, which the schema already covers. With 100% schema coverage, the description adds little extra parameter meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool updates delivery information for a specific order delivery record (修改指定訂單配送記錄的物流資訊). It names concrete fields (tracking number, carrier, delivery status) and is easily distinguished from sibling tools like get_order_delivery (read), execute_order_shipment (shipment execution), and update_order (general order update).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
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 writing back delivery status after integrating a third-party logistics system (適合整合第三方物流系統後回寫配送狀態). This gives context for when to use the tool, though it doesn't explicitly mention alternatives or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully carries the burden of behavioral disclosure. It details the API call (PUT /v1/promotions/{promotion_id}), states that changes take effect immediately and may affect consumers in checkout, and explicitly notes irreversibility (though it can be overwritten). It also describes the return structure, providing excellent transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear section headers (Purpose, API, Return Structure, Side Effects). Each section is concise and serves a distinct purpose, with no wasted wording. It is front-loaded with the essential purpose and write indicator.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a write tool with no annotations or output schema, this description is remarkably complete. It covers the purpose, API endpoint, return structure, and side effects—including irreversibility and impact on active checkout flows. The only missing detail is the full promotion_data schema, but that is provided in the input schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with both parameters having descriptions. The description adds examples of what can be updated (discount amount, validity, conditions) but does not substantially explain the structure of promotion_data beyond the schema. It meets the baseline for high schema coverage but does not go beyond it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'update existing promotion' with specific examples of modifiable attributes (discount amount, validity period, conditions). The [WRITE] marker and verb 'update' distinguish it from sibling tools like create_promotion, delete_promotion, and get_promotion_detail.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The purpose section explicitly indicates this tool is for modifying existing promotions, providing clear context for when to use it. However, it does not explicitly mention alternatives or when not to use it, 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.
Behavior5/5
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 exceeds expectations by disclosing side effects: '售價立即更新，前台同步顯示新價格' (price updates immediately, storefront syncs) and '不影響進行中的訂單' (does not affect existing orders). It also provides the return structure and the exact API endpoint, giving a transparent view of the tool'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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured with clear sections: title, purpose, API call, return structure, and side effects. Every sentence adds value—no fluff or redundancy. It is concise yet comprehensive for a tool of this simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (3 simple required params, no output schema), the description is complete. It includes the purpose, API endpoint, return structure, and side effects. The presence of side-effect information is especially valuable since annotations are absent. Nothing critical is missing for an agent to correctly invoke and understand the outcome.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage, with each parameter (product_id, variation_id, price) already described in detail. The description does not add significant semantic meaning beyond what the schema provides, though it does imply the relationship between the IDs through the API path. Since schema coverage is high, a baseline of 3 is appropriate per the scoring guidelines.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: '更新商品變體售價' (update product variation price) and '直接設定特定變體的售價' (directly set a specific variation's price). This specific verb+resource combination distinguishes it from sibling tools like update_product_price (which likely updates base product price) and update_variation_quantity (which updates stock). The use cases '個別規格調價、限時特價' further clarify the intended scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly provides a 'purpose' section that states when to use the tool: '適用於個別規格調價、限時特價等場景' (suitable for individual spec price adjustments, limited-time promotions). This gives clear context for appropriate use. However, it does not explicitly mention when NOT to use it or name alternative tools (e.g., update_product_price), so it misses the full 'when/when-not/alternatives' guidance 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.
Behavior4/5
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 the stock quantity updates immediately, affects front-end purchasable quantity, and if set to 0 with no oversell allowed, front-end will show out of stock. It also includes the API endpoint. While it doesn't mention auth requirements, it thoroughly explains side effects and operational context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear sections (用途, 呼叫的 Shopline API, 回傳結構, 副作用). Information is concise and front-loaded, with the write indicator '[WRITE]' at the start. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple 3-parameter update tool with no output schema, the description explains the purpose, the API endpoint, the return structure, and side effects. It is complete for the tool's complexity, and the sibling differentiation further enhances context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so each parameter already has descriptions. The description adds clarity that quantity is an absolute value '新庫存數量（絕對值，非增減量）', which is already in the schema. According to the rubric, baseline is 3 when schema coverage is high, and the description doesn't significantly extend beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states '直接設定特定變體的庫存數量' (directly set specific variation's stock quantity), which precisely describes the verb+resource+scope. It also distinguishes from sibling tools like bulk_update_quantities by noting it's for a single variance.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: '適用於盤點後調整庫存或手動補貨場景' (for inventory adjustment after stocktake or manual replenishment). It also gives an alternative: '若要批次更新多個 SKU 庫存，可改用 bulk_update_quantities' (for batch updates, use bulk_update_quantities), clearly naming the alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It explicitly discloses side effects (adds a media record, consumes storage space) and a known behavioral limitation (JSON body may be rejected; may need multipart). This is more transparent than typical descriptions and goes beyond what annotations would convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
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. Every section is informative and earns its place. It's concise without being underspecified.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description provides the return structure, API endpoint, side effects, and a caveat about the JSON/multipart issue. This is complete for a simple upload tool, covering all essential aspects for an agent to invoke and interpret results correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides a detailed description of media_data with an example, achieving 100% coverage. The tool description does not add significant parameter-specific meaning beyond noting the media ID in the return structure. This matches the baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb (upload) and resource (media files to Shopline media library), and clarifies the outcome (obtain media ID for product images). It distinguishes itself from sibling tools by focusing on the media library, whereas tools like add_product_images likely attach images directly to products.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: use this to upload media and receive an ID for later use in product images. It also notes the JSON body limitation and advises fallback to multipart on format errors. However, it doesn't explicitly mention alternatives or exclusions, 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.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully discloses the tool's behavior: it always returns an explicit error, describes the two failing API approaches, and specifies the return dict fields (error, group_id, supported_alternative). This is exemplary transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized with clear sections (function, limitations, return structure). It is slightly long but every part earns its place, given the unusual unsupported nature of the tool. A single sentence would not suffice.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description completely explains the tool's purpose, limitations, and return structure. Even without an output schema, the return dict is described. For a tool that exists primarily to surface an API limitation, this is exceptionally complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides 100% coverage for the single parameter, including its source (list_customer_groups). The description doesn't add new parameter details, but the schema adequately handles semantics, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description first states the apparent purpose (get customer IDs in a group) but then immediately clarifies the actual behavior: the API doesn't support this and the tool always returns an error. This is a specific, honest depiction that distinguishes it from sibling list tools that actually return data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly explains when not to use the tool (the endpoint doesn't exist, filter params are ignored) and provides a concrete alternative: export from Shopline backend. This gives clear usage guidance beyond just the tool's behavior.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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 return structure (dict with total_found, returned, return_orders[]) and explains that it returns summary info, not full item details. It also names the underlying API endpoint. Missing an explicit statement about read-only nature or edge-case behavior, but the GET method and general clarity earn it a 4.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with distinct sections (purpose, usage, API, return structure), making it easy to scan. There is some redundancy between the opening line and the usage section, but overall it is efficient and each section contributes useful information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a list tool with no output schema, the description compensates by detailing the return structure and field meanings. It also provides the API endpoint and sibling distinctions, giving an agent all necessary context to select and invoke the tool correctly. No significant gaps are present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with each parameter described. The description adds value by clarifying that the date range filters by '建立日期' (creation date), which is not explicit in the schema. This interpretive context enhances parameter understanding beyond the schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists return orders and can be filtered by creation date range. It explicitly differentiates from siblings by mentioning get_return_order_detail for full item details and get_refund_summary for aggregate analysis, making its role distinct.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit usage context: querying return orders in a time period for status and quantity review. It also gives clear alternatives: use get_return_order_detail for single-order detail and get_refund_summary for aggregate analysis, effectively stating when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Since no annotations are provided, the description carries the full transparency burden. It discloses the PUT endpoint, immediate effect on frontend navigation, non-reversibility but overwritability via repeated calls, and the return dict structure (success, resource_id, message). This is thorough behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized into labeled sections (purpose, API, return, side effects), each providing distinct and relevant information without redundancy. It is appropriately sized for the tool's complexity and front-loads the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a moderate-complexity update tool with a simple schema and no output schema, the description covers purpose, partial-update behavior, return structure, and side effects. It lacks explicit error-handling or prerequisite details (e.g., category existence validation), but is otherwise comprehensive enough 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.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Both parameters are already documented in the schema (100% coverage), but the description adds meaningful context by explaining partial-update semantics and giving example attribute keys (name, sort, parent) that clarify the shape of category_data beyond the schema's generic example.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool updates product category data and lists specific attributes (name, sort order, parent category), clearly distinguishing it from create/delete category siblings. The [WRITE] marker and PUT endpoint reinforce its update purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context with the partial-update instruction ('only fields passed are modified; unpassed fields won't be overwritten'), which explains when and how to use it. However, it doesn't explicitly contrast with alternatives like create_category or delete_category, so it stops short of a full 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full responsibility for disclosing behavioral traits. It explicitly lists side effects: '修改客戶資料，變更立即生效' (changes take effect immediately) and '不可復原（無版本歷史），但可再次呼叫此工具覆蓋' (not reversible, no version history, but can be overwritten). It also states the return structure, making it highly transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections: [WRITE], purpose, API, return structure, and side effects. Each section is concise and necessary, providing essential information without redundancy. It is front-loaded with purpose and immediately tells the agent what the tool does.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 6-parameter update tool with no annotations and no output schema, the description covers the key aspects: purpose, partial-update usage, API endpoint, return structure, and side effects. It lacks details on authentication requirements or error conditions, but these are not critical for the basic update operation. Overall, it is sufficiently 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.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (all 6 parameters described in the schema). The description adds valuable beyond-schema semantics: '僅傳入要修改的欄位，未傳入的欄位不會被覆蓋' (only pass fields to modify; omitted fields are not overwritten). This clarifies the partial-update behavior for all optional fields, which is not evident from the schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states '更新客戶基本資料' (update customer basic info) and elaborates with '修改客戶姓名、聯絡方式、生日等基本資料' (modify name, contact, birthday, etc.). This distinguishes it from sibling tools like update_customer_tags and update_customer_store_credits, which target different aspects of a customer.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on how to use the tool: '僅傳入要修改的欄位，未傳入的欄位不會被覆蓋' (only pass fields to modify; omitted fields are not overwritten). This explains partial-update usage. However, it does not explicitly mention alternatives or when not to use this tool, so it stops short of fully contrasting with sibling update tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description self-discloses key behaviors: changes take effect immediately ('變更立即生效'), may appear on customer-visible pages (receipts, emails), and are non-reversible but can be overwritten by calling again. It also mentions the PUT API and return structure, which is excellent 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (用途, API, 回傳結構, 副作用) and front-loads the purpose. It is somewhat lengthy, but each section provides distinct value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and no output schema, the description covers purpose, usage, API endpoint, return structure, and side effects comprehensively. For a write operation with two parameters (including a nested object), this is complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Both parameters have schema descriptions (100% coverage), but the description adds the crucial partial-update semantics for merchant_data, explicitly stating that only passed fields are modified. This goes beyond the schema's example JSON and enhances understanding of how to use the parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states '更新商家基本資料' and elaborates on modifying specific merchant fields (name, contact info, address). It distinguishes itself from read-only siblings like get_merchant_detail by emphasizing the update operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: '僅傳入要修改的欄位，未傳入的欄位不會被覆蓋' (only pass fields to modify, untouched fields won't be overwritten) and suggests a use case (搬遷、更名). It does not explicitly mention alternatives, but no other update-merchant tool exists, so context is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden for behavioral disclosure. It explicitly lists side effects: changes take effect immediately, refund status may trigger actual financial refunds, and changes are irreversible. It also states the return structure (success, resource_id, message), providing a clear picture of consequences beyond the basic 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured using sections like 【用途】, 【呼叫的 Shopline API】, 【回傳結構】, and 【副作用】. It is appropriately concise, with each section delivering essential information without redundancy. The front-loaded '[WRITE]' tag immediately signals the operation type.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the main necessary contexts: the exact API endpoint, the use case, return structure, and side effects. Given that the output schema is absent, the return structure explanation is especially helpful. It lacks details on error handling or validation rules, but for a write tool with a flexible nested object, this is quite complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already has 100% coverage for both parameters, so the baseline is 3. The description adds meaningful context by clarifying that setting the status to '已退款' may cause actual refunds and financial impact, and gives a concrete example of the data object structure. This goes beyond schema explanations and helps agents understand the implications of parameter values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with '[WRITE] 更新退貨單狀態或資料' (Update return order status or data), which clearly states the specific action and resource. It further lists concrete fields (審核狀態, 退款金額, 備註), making it distinct from read-only return order tools like get_return_order_detail or list_return_orders.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states '適用於客服審核退貨申請流程' (suitable for customer service review return application process), providing clear context for when this tool is appropriate. It does not explicitly name alternatives or exclusion cases, but the use case is well-defined enough to distinguish it from other operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden and delivers extensively: it explains the brand filter's 10,000-item scan limit, the scan_incomplete flag, the exact Shopline APIs used, backend matching behavior with no truncation, and return structure flags. This goes far beyond what the schema provides.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear sections, front-loaded with the main purpose, and every paragraph delivers essential caveats or behavioral details. The length is justified because of the non-obvious brand limitation and return flags; no filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having no output schema or annotations, the description fully explains return structure, the meaning of truncated and scan_incomplete, API selection logic, and parameter behavior. It is comprehensive enough for an agent to invoke the tool correctly in most scenarios.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema already describes all 7 parameters (100% coverage), giving a baseline of 3. The description adds extra meaning by explaining the brand scan limit in depth, clarifying that max_results has no 500 cap, and describing how the backend handles each filter, which elevates it above baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it searches/lists products with specific attributes (SKU variants, price, brand, stock, image URL). It distinguishes itself from sibling read tools like get_product_by_sku and get_product_variants by being the general search/list entry point.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear usage context, including when to narrow using category_id or keyword when brand scan is incomplete, and notes that other filters are backend-handled. It does not explicitly name alternative tools, but the guidance on when to use and when not to trust results is strong.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses the underlying Shopline API endpoints (GET /v1/customers vs /v1/customers/search) and return structure (total_found, returned, customers[]). This adds valuable behavioral context beyond the basic listing, though it doesn't mention pagination or 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear sections (用途, API, 回傳結構). Every sentence provides useful information, no redundancy, and it is front-loaded with the core purpose. Appropriate length for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description compensates by documenting the return structure. It covers the different API paths based on search, differentiates from the profile tool, and lists the customer fields returned. Complete for a list tool with two parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds meaning by explaining that search_keyword triggers the search API and lists searchable fields (姓名、email、電話), which clarifies parameter behavior beyond the schema. max_results is not elaborated but the return structure hints at its role.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description states '取得客戶列表' (get customer list) with keyword search support, and explicitly distinguishes from get_customer_profile for full customer info. The verb+resource is specific and differentiates from the sibling tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear usage context: '查詢特定客戶或瀏覽客戶清單' (query specific customer or browse customer list). Explicitly names get_customer_profile as the alternative when full profile is needed, fulfilling the when-to-use and alternative guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully carries the burden of behavioral disclosure. It explicitly lists side effects: original order status may change, operation is usually irreversible, and shipped orders cannot be split. It also includes the API endpoint and return structure, providing comprehensive 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections: [WRITE], 用途 (purpose), API call, return structure, and side effects. It is concise, front-loaded with the main action, and every sentence provides meaningful information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (write operation, nested object, no output schema), the description is remarkably complete. It covers purpose, use cases, API endpoint, return structure, side effects, and constraints (shipped orders cannot be split). No critical information is missing for an agent to decide and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for both parameters. The description adds value by explaining split_config is a dictionary following Shopline API specifications, and clarifies that it defines each sub-order. It does not detail the internal structure, but the reference to the spec is useful guidance beyond the schema's generic description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: '拆分訂單為多個子出貨單' (split an order into multiple sub-shipments), with a specific verb (split) and resource (order). It distinguishes from siblings by focusing on the split operation, which is unique among the listed tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear context for when to use: '適用於商品分批到貨或不同倉庫分開出貨的場景' (scenarios of goods arriving in batches or separate warehouses). It also gives an exclusion: '已出貨的訂單無法拆單' (shipped orders cannot be split). However, it does not explicitly name alternative tools or provide broader when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full disclosure burden and handles it excellently. It reveals immediate effect of changes, that new orders apply new rules while existing commission records are unaffected (snapshot-dependent), irreversibility, and the ability to overwrite by calling again. The return structure (success, resource_id, message) is also disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized into labeled sections (用途, API, 回傳結構, 副作用) with no filler. It is front-loaded with the [WRITE] marker and purpose, and every section provides distinct actionable information, making it efficiently scannable for an agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no annotations and no output schema, the description is remarkably complete: it covers the purpose, maps to the underlying API endpoint, specifies the return format, and details side effects. The partial-update semantics of campaign_data are implicit in the schema and reinforced with examples, so the agent has enough context to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with clear descriptions already present for campaign_id and campaign_data. The description adds value by giving concrete examples of campaign_data fields (commission ratio, duration, applicable conditions), which is especially helpful given additionalProperties:true and no fixed sub-schema for the nested object.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb and resource: '修改已建立的聯盟行銷活動' (modify existing affiliate campaign) with concrete examples like commission rate, duration, and conditions. The [WRITE] prefix reinforces the mutation nature, and the focus on updating existing campaigns distinguishes it from sibling tools such as create_affiliate_campaign, delete_affiliate_campaign, and list_affiliate_campaigns.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 【用途】 section explicitly frames when to use this tool: to modify already-created affiliate campaigns, with examples of adjustable fields. This provides clear usage context, though it does not explicitly name alternatives or state when NOT to use it (e.g., 'use create_affiliate_campaign for new campaigns'), which keeps it from a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It explicitly discloses the destructive side effect: '覆蓋客戶的所有現有標籤為新的標籤列表' (overwrites all existing tags). The '[WRITE]' prefix signals mutation, and the '副作用' section further elaborates on the overwrite and the safe alternative. This goes beyond minimal disclosure and effectively 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections ('[WRITE]', '用途', '呼叫的 Shopline API', '回傳結構', '副作用') and every sentence adds value. It is concise yet thorough, front-loading the most important overwrite warning. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter mutation tool, the description covers purpose, side effects, return structure, API endpoints, and usage guidance. It even suggests a safe alternative workflow. Despite lacking annotations and an output schema, the description compensates fully, making it complete for an agent to select and invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%: both customer_id and tags are described in the schema. The description reinforces the overwrite semantics for tags, but the schema already states '標籤列表（會取代現有標籤）'. The description adds context about usage but does not provide additional parameter-level details beyond schema. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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 (set customer tags) and the critical behavior (overwrites existing tags). It distinguishes itself from sibling tools like update_order_tags and update_product_tags by explicitly mentioning customer tags, and also contrasts with an 'add' operation via the overwrite note.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The '用途' section gives typical use cases (marketing segmentation, VIP marking). More importantly, it provides explicit guidance on when NOT to use this tool for adding tags, directing the agent to first use get_customer_profile to fetch existing tags and merge them. This clearly addresses alternatives and exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
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 excellently. It discloses the [WRITE] nature, immediate effect, customer-facing visibility, and irreversibility (though overwrite is possible). This gives the agent important risk awareness beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections for purpose, API mapping, return structure, and side effects. Every section earns its place, and the [WRITE] prefix plus front-loaded purpose make it scannable for an agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a mutation tool with no output schema and a nested object parameter. The description compensates fully by including the API endpoint, expected return dict structure, side effects, and an example payload. Given the complexity, the description is complete enough for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds genuine value by providing a concrete JSON example for pickup_store_data and explaining the role of delivery_option_id. This goes beyond mere schema repetition and helps the agent construct inputs correctly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('修改'/'更新') and a concrete resource (自取門市 under a delivery option), clearly distinguishing it from siblings like get_delivery_option_detail or update_order_delivery. It also lists the kinds of fields that can be updated, making the purpose immediately understandable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states when this tool is appropriate ('適合門市資訊異動時同步更新 Shopline 的自取門市設定'), giving clear usage context. However, it does not explicitly mention when not to use it or name alternative tools, so it stops short of full exclusion guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It discloses the write nature with [WRITE], the exact API endpoint, return structure, and side effects including immediate price display and lack of impact on existing orders. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized into concise sections, front-loading the core purpose. Every sentence provides useful information without padding, and the structure (purpose, API, return, side effects) makes it easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with two required parameters and no output schema, and the description covers usage, alternatives, API, return structure, and side effects. It is fully sufficient for an agent to invoke correctly without ambiguity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already describes both parameters (product_id as internal ID, price as new TWD amount) with 100% coverage. The description does not add significant additional parameter syntax or format details beyond the schema, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it updates the selling price for products without variants, with a specific verb and resource. It distinguishes from the sibling update_variation_price by explicitly noting the variant-product constraint. Applicable scenarios like price adjustments and promo-end restorations add clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says to use this tool for setting prices of non-variant products and provides context (price adjustments, restoring original price). It directly instructs to use update_variation_price for variant products, making the alternative and when-not-to-use explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
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 write operation, immediate frontend impact, and out-of-stock behavior when quantity is set to zero. Also includes API endpoint and return structure, providing comprehensive 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear sections (purpose, API, return, side effects) and no redundant text. The main purpose is front-loaded, and each sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, usage context, alternative tools, API endpoint, return structure, and side effects. Fully complete for a simple mutation tool, leaving no significant gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema already covers both parameters with descriptions, including absolute vs. incremental quantity. The description adds minimal extra parameter meaning, so baseline 3 applies given 100% schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool updates inventory quantity for non-variant products, with a specific verb and resource. It explicitly distinguishes from sibling tools by directing variant products to update_variation_quantity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use context (stocktaking, manual replenishment) and an explicit alternative for products with variations. This fully clarifies usage versus alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full responsibility and does an excellent job. It discloses the overwrite side effect, the underlying API endpoint (POST /v1/products/{product_id}/tags), the return structure (dict with success, resource_id, message), and explicitly warns that existing tags are replaced. This goes well beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with labeled sections (用途, API, 回傳結構, 副作用), each providing necessary information without redundancy. It is concise yet comprehensive, using headings and bullet-like formatting for readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter mutation tool with no output schema, the description covers everything needed: purpose, side effects, API endpoint, return structure, and even an alternate workflow. It is fully contextual and leaves no critical gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% coverage with clear descriptions for both parameters (product_id and tags). The description adds some context about tag usage and the merge workflow, but most of the parameter semantics are already in the schema, so the description contributes only marginal additional value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 設定商品標籤 (set product tags), and immediately notes that it overwrites existing tags. This distinguishes it from sibling tools like update_customer_tags and update_order_tags by specifying the resource (product).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 【用途】 section explains common use cases (product grouping, promotion marking, SEO), and the 【副作用】 section explicitly warns about overwriting and provides an alternative workflow: use get_product_list first to merge tags. This gives clear when-to and when-not-to guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description discloses important behavioral traits: immediate effect, front-end synchronization, and irreversibility (no version history) but can be overridden by calling again. Also specifies the exact API endpoint and return structure, giving the agent a full picture of side effects and outcome.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (purpose, API endpoint, return structure, side effects). Each section provides meaningful information without fluff, making it easy to scan and digest.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no annotations and no output schema, the description is complete: it explains what it does, how to use it (partial update), the expected return shape, and side effects. This covers all critical information an agent needs to invoke and interpret the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for all three parameters, so the schema already documents IDs and variation_data. The description adds meaning by clarifying variation_data is a partial update and listing example fields (SKU, spec options, status), which helps the agent construct the nested object correctly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool updates product variation data with a specific verb (更新) and resource (商品變體資料). It mentions modifying SKU, spec options, status, etc., which distinguishes it from sibling tools that target specific fields like quantity or price.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear usage context: only pass fields to be modified, untouched fields will not be overwritten. Does not explicitly compare with sibling tools like update_variation_quantity or update_variation_price, but the partial-update note is actionable and helps an agent decide when to call this generic variation update.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and does so well. It discloses the scanning behavior, the threshold condition (quantity <= threshold), the sort order (ascending by stock), and the exact return structure including field details. This is comprehensive for a read-only tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured: purpose first, then behavior, then alternatives, then return structure. Every sentence provides useful information with no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given a single parameter and no output schema, the description covers all essential aspects: behavior, sorting, and return structure. It even details the fields within each alert, making it complete for an agent to understand the tool's output.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents the threshold parameter with a description, and the tool description adds value by specifying the exact comparison operator (<=) and including threshold in the return dict. This clarifies the semantics beyond the schema's general 'below this value' wording.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves a list of low-stock or out-of-stock SKUs at variant level with a customizable threshold. It uses a specific verb (取得) and resource (SKU list), and distinguishes itself from siblings by naming get_inventory_overview and get_stock_by_warehouse as alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly points to alternatives for different needs: use get_inventory_overview for overall inventory stats and get_stock_by_warehouse for warehouse distribution. This gives clear direction on when to use this tool versus other inventory-related tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses behavioral traits: it marks the operation as [WRITE], states it overwrites all existing tags, specifies the underlying PATCH API, describes the return structure, and lists side effects including a merge strategy. This is comprehensive and transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (Purpose, API, Return, Side Effects), front-loaded with the key overwrite warning. Every sentence provides necessary information, with no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given it's a write tool with no annotations or output schema, the description covers all necessary aspects: purpose, API endpoint, return structure, side effects, and usage guidance. An agent has enough 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.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for both parameters (order_id and tags), so the baseline is 3. The description adds extra semantic context by explaining that tags replaces the entire set and providing a concrete workflow for merging existing tags via get_order_detail, which goes beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: setting order tags and overwriting existing tags. It uses a specific verb ('set') and resource ('order tags'), and explicitly notes the overwrite behavior, distinguishing it from read-only siblings like get_order_tags and generic update tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage context: order categorization, priority marking, customer service grouping. It also gives clear guidance on when NOT to use it (when appending tags) and suggests an alternative approach with get_order_detail, which is excellent practical advice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

Copy to your README.md:

[![shoplinemcp MCP server](https://glama.ai/mcp/servers/tzangms/shoplinemcp/badges/card.svg)](https://glama.ai/mcp/servers/tzangms/shoplinemcp)

Score Badge

Copy to your README.md:

[![shoplinemcp MCP server](https://glama.ai/mcp/servers/tzangms/shoplinemcp/badges/score.svg)](https://glama.ai/mcp/servers/tzangms/shoplinemcp)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/tzangms/shoplinemcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server