MCP Shopline

Server Quality Checklist

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

Latest release: v0.3.0
Disambiguation4/5
Most tools target distinct resource-action combinations, with clear descriptions. However, the sheer number (143) creates potential confusion between similar operations like update_product_price vs update_variation_price, and the presence of both single and bulk variants for reviews and other entities may cause misselection.
Naming Consistency5/5
Tools follow a consistent verb_noun pattern (e.g., create_product, update_order, get_customer_profile). The naming convention is uniform across all tools, with only minor deviations like query_orders instead of list_orders, which are still predictable.
Tool Count2/5
With 143 tools, the server is far beyond the typical well-scoped range of 3-15. This suggests the server tries to cover the entire Shopline platform in one server, which is overwhelming and reduces coherence. It would be better split into multiple focused servers.
Completeness4/5
The tool surface is extremely comprehensive, covering CRUD operations for most entities (products, categories, customers, orders, promotions, etc.), analytics, and inventory management. Minor gaps exist (e.g., no create_customer_group, no update_customer_group), but overall it's very complete for a full e-commerce platform.
Average 4.2/5 across 143 of 143 tools scored. Lowest: 3.1/5.
See the Tool Scores section below for per-tool breakdowns.
- 2 of 2 community issues answered or closed in the last 6 months
- 0 commits in the last 12 weeks
- Last stable release on May 7, 2026
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
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?
With no annotations provided, the description carries full burden for behavioral disclosure. It only states the analytical purpose and source data, but does not reveal any behavioral traits such as required permissions, data aggregation method, return format, or limitations. This is inadequate for a getter 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 a single, front-loaded sentence that efficiently conveys the tool's purpose. It has no wasted words, but could benefit from slightly more structure for completeness.
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?
The tool lacks an output schema and the description does not explain what the tool returns (e.g., aggregated counts, percentages, or raw data). For an analysis tool, this is a significant gap in 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?
Schema coverage is 100% and all parameters have descriptions. The description adds no additional semantic context beyond the schema; it merely restates the tool's purpose. Baseline of 3 is appropriate for high coverage without extra 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 analyzes customer geographic distribution from order shipping addresses at the city/district level. This is a specific verb-resource combination that distinguishes it from sibling analysis tools like get_rfm_analysis or get_sales_summary.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for geographic analysis but does not provide explicit guidance on when to use this tool versus alternatives, nor does it mention exclusions or prerequisites. Given the large sibling list, this is a gap.
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 present, so the description must disclose behavioral traits. It does not discuss pagination, what 'slow movers' means exactly, authorization requirements, or the impact of parameters on results. The description adds no behavioral context 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence covering two modes (ranking and slow movers), which is concise. However, the dual purpose might cause slight ambiguity. It front-loads the main function.
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?
With 5 parameters, no output schema, and no annotations, the description lacks critical details such as output format, pagination, definition of 'slow movers', and how channel filtering affects results. It does not fully equip an agent to use the tool correctly without additional inference.
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 parameter descriptions that are clear (e.g., date format, enum values, default). The description adds interpretive context like '依銷量或營業額排序' (sorted by volume or revenue) but does not explain the slow-mover mode parameter (possibly implied by negative top_n?). Minimal value added beyond 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 retrieves a product sales ranking for a specified time period, sorted by quantity or revenue, or a list of slow-moving products. It uses a specific verb ('取得') and resource ('商品銷售排行榜'), distinguishing it from sibling tools like get_sales_summary or get_product_list, though it overlaps with 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 Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as get_slow_movers or get_category_sales. There is no mention of prerequisites, limitations, or context for selecting between sorting options or slow-mover mode.
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 bears the full burden. It notes that querying all products is slower, which is a useful behavioral hint. However, it omits details like data freshness, authentication requirements, or the structure of the 'matrix'.
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 two sentences, covering purpose and a key performance consideration. It is efficient and front-loaded with the core function.
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, so the description should explain return values. Calling it a 'distribution matrix' is vague. With only two optional parameters, the description is adequate but leaves room for confusion among many sibling tools.
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 are fully documented in the input schema with descriptions. The description adds a performance note about all-product queries but does not significantly enhance understanding beyond the schema.
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 inventory distribution by product and warehouse, mentioning single or all products. However, it does not explicitly differentiate from sibling tools like get_inventory_overview, which also deal with inventory data.
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 such as get_inventory_overview or get_locked_inventory. Users must infer from the name alone.
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 provided, so description must carry the burden. It mentions prerequisites and outputs, but does not disclose read-only nature, authorization needs, or side effects. For a calculation tool, more transparency is expected.
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 output, second states prerequisite. No wasted words, front-loaded efficiently.
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 2-param tool with no output schema, the description covers what it does and what data it needs, but lacks details on return format and any limitations, making it 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 coverage is 100% with clear descriptions for start_date and end_date. The description adds no extra meaning beyond the schema, so baseline 3 applies.
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 calculates inventory turnover metrics (turnover days and rate). It distinguishes from siblings like get_inventory_overview and get_slow_movers by naming specific indicators, though not explicitly differentiating.
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 prerequisite (requires inventory and sales data), which implies when to use, but does not provide explicit when-not or alternative tool suggestions.
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 reveals it calls two API endpoints (GET /v1/products and GET /v1/products/search), which provides some transparency about backend operations. However, since no annotations are present, it should have disclosed additional behavioral traits such as read-only status, pagination, or rate limits. It partially compensates but is insufficient.
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 exceptionally concise, with only two lines of text plus a list of API endpoints. It is front-loaded with the main purpose and follows a clear, structured format. No superfluous information is included.
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?
While the description covers the basic purpose and data returned, it lacks details on pagination, sorting, default behavior, or the output format. Given the absence of an output schema and annotations, more completeness would be expected for a list tool with three parameters.
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?
All three parameters (keyword, brand, max_results) are fully described in the input schema (100% coverage). The description does not add any additional meaning or usage context for the parameters beyond what the schema already provides, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/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 a product list including SKU variants, price, brand, inventory, etc., and mentions the underlying APIs. However, it does not differentiate it from sibling tools like list_addon_products or get_product_variants, which may have overlapping functionality.
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 lacks any guidance on when to use this tool versus alternatives. It does not specify prerequisites, context, or conditions for use, leaving the agent without direction for tool selection.
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, the description carries the full burden but only mentions the API method (GET) and return structure; it omits explicit disclosure of read-only behavior, authentication needs, rate limits, or any 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured with clear sections, though the API endpoint detail is not essential for tool usage; overall it is effective and 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?
Given a simple list tool with one parameter and no output schema, the description covers purpose and return structure adequately. However, it could mention pagination or filtering behavior beyond max_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, max_results, is described in the schema with '最多回傳筆數' (max returned count). The description adds no further meaning 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 retrieves a list of purchase orders to understand inventory status and purchase history, distinguishing it from sibling tools like get_purchase_order_detail and 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 Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide any guidance on when to use this tool versus alternatives such as get_purchase_order_detail for specific orders, nor does it mention conditions or prerequisites.
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 bears full responsibility for behavioral disclosure. It only states that the tool compares performance but gives no insight into whether it is read-only, destructive, or has limits. The agent cannot infer safety or side effects from this description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with two sentences. The first sentence captures the core action and metrics; the second adds supported comparison types. No extraneous words. Information is front-loaded and efficiently presented.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the description lists example metrics, it does not explain the output structure (e.g., whether it returns a table, percentages, or raw numbers). Given the lack of an output schema and annotations, the description should provide more context on the expected results to ensure correct tool invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 (start_date and end_date). The description adds no additional meaning beyond what the schema already provides; it merely re-emphasizes the date range concept. Baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
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: comparing performance metrics (revenue, orders, average order value) across channels/stores over the same period. It also specifies supported comparisons (online vs. store, between stores), which distinguishes it from siblings like get_channel_detail or get_sales_summary.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for comparative analysis but does not explicitly state when to use this tool over alternatives, nor does it provide exclusions or prerequisites. The context of sibling tools offers some guidance, but the description itself lacks explicit usage directives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. Description lacks any behavioral details such as data limits, performance, or prerequisites beyond basic functionality.
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?
Single sentence that is concise and front-loaded with key information.
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?
No output schema and description does not explain return format or data structure, leaving agent uninformed about what to expect.
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%, description adds no additional meaning beyond 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?
Description clearly states it retrieves sales trend data with daily/weekly/monthly granularity for charting. Differentiates from sibling tools like get_sales_summary.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implied usage for trend visualization, but no explicit guidance on when to use versus alternatives or when not to use.
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 provided; description carries full burden. It specifies the API endpoint (GET /v1/member_point_rules) and return structure (dict with total and rules array). Does not disclose rate limits, authentication requirements, or potential side effects, but the read-only nature is clear from the GET call.
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 concise, front-loads purpose, and uses clear sections (用途, API呼叫, 回傳結構). Each sentence adds value 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?
Despite no output schema, the description adequately explains the return structure (dict with total and rules array, each rule containing fields like id, name, type, value, conditions). Covers all necessary context for a simple parameterless 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?
Input schema has zero parameters, so there is nothing to describe. Baseline score of 4 is appropriate per guidelines.
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?
Description clearly states the tool retrieves member point rules, including consumption reward ratio and expiration rules. It also mentions analytical use cases, but does not explicitly differentiate from sibling tools like adjust_customer_member_points or list_store_credits.
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?
Description provides purpose but no guidance on when to use this tool versus alternatives. No explicit when-to-use or when-not-to-use information.
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 bears full responsibility. It mentions the GET API endpoint (safe operation) and return fields, but it does not disclose authentication requirements, rate limits, error behavior, or any edge cases. Basic read behavior is implied but not thoroughly documented.
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 concise with three clear sections: purpose, API endpoint, return structure. It is front-loaded and contains no redundant text. While compact, it could slightly improve by using more explicit structure (e.g., bullet points), but overall it is efficient 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 adequately details the return structure (id, status, created_at, total, items with fields). It lacks guidance on error conditions or differentiation from similar tools like get_order_detail, but for a simple read operation on a specific resource, it covers the essentials.
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 a description for purchase_order_id ('採購單 ID'). The description adds that it's for a single purchase order, but does not provide additional context like format or constraints beyond the schema. Baseline 3 as schema already covers 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 it retrieves complete details of a single POS purchase order, specifying the data included (items, quantities, amounts). It distinguishes itself from sibling tools like list_purchase_orders (list) and delete_purchase_orders (delete) by indicating it's for a single 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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when needing details of one purchase order, but it does not explicitly state when to use this tool over alternatives, such as get_order_detail (for non-POS orders) or list_purchase_orders (for listing). No exclusions or prerequisites are 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 full burden. It does not disclose whether the operation is read-only, authentication requirements, or rate limits. For a data retrieval tool, this is a 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?
Two concise sentences in Chinese, front-loaded with action and purpose. No wasted 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?
For a simple date-range analysis tool, the description lists computed metrics but lacks details on return format or behavioral traits. Without an output schema, more context on expected results would be helpful.
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 baseline is 3. The description does not add semantic value beyond what the schema already provides for the two date 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 it analyzes repurchase rate and cycle, listing specific metrics. It distinguishes from siblings like get_sales_summary and get_rfm_analysis by focusing on repurchase behavior.
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 name and description, but no explicit guidance on when to use this tool versus alternatives like get_customer_lifecycle or get_rfm_analysis is provided.
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 must carry the full burden. It states the tool is a retrieval operation but does not disclose return format, pagination, rate limits, or permissions. For a read-only tool, this is insufficient.
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 sentences that concisely state purpose and filtering capability. No redundant information; every clause adds value.
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 description covers purpose and filtering but lacks details on return structure, ordering, or limitations. For a summary tool, it is adequate but not comprehensive.
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 baseline is 3. The description adds context about metrics included (revenue, order count, etc.) but does not elaborate on parameter formats or constraints 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 retrieves sales summary for a specified time period, listing core metrics (revenue, order count, etc.) and noting filtering by channel/store. It distinguishes from sibling tools like get_category_sales or get_channel_comparison.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for basic sales summary but does not explicitly state when to use this versus alternatives like get_sales_trend or get_channel_comparison. No exclusions or prerequisites are mentioned.
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?
Discloses the API endpoint and return structure, which is useful. However, no annotations exist, so the description should also mention that this is a read-only operation or require any permissions, but it doesn't.
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?
Well-structured with sections, front-loading the purpose. Each sentence adds value, though it could be slightly shorter without losing 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 no output schema, it adequately describes the return structure and fields. It also explains integration with get_promotion_detail. However, it lacks information on pagination or error responses.
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 description adds marginal value beyond the schema. It re-iterates keyword and max_results but does not explain how they affect search behavior (e.g., partial match) beyond the schema.
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?
Clearly states it searches promotions by keyword, with examples like '週年慶'. Although it differentiates from get_promotion_detail by noting results include IDs for that call, it could explicitly distinguish from list_promotions.
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?
Provides context for when to use (finding specific promotions by name) and mentions get_promotion_detail as next step, but does not explicitly say when not to use or provide alternatives like list_promotions.
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 exist, so the description must carry the burden. It reveals that the tool requires multiple API calls (cross-referencing), hinting at potential latency, but lacks details on authentication, rate limits, or handling of missing data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that efficiently conveys the purpose and a key constraint (cross-referencing). It is not verbose, but could be slightly more structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists. The description mentions the returned fields (revenue, sales volume, item count) but lacks details on formatting, pagination, or error handling. Adequate but not comprehensive for a tool with medium complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear parameter descriptions. The tool description adds no additional meaning beyond what the schema provides, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool summarizes sales data by product category, specifying revenue, sales volume, and item count. It also notes the need to cross-reference multiple APIs, distinguishing it from sibling tools that handle individual aspects like orders or categories.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for category-level sales aggregation and mentions cross-referencing overhead, but does not explicitly state when to use it over alternatives like get_sales_summary or get_top_products, nor does it provide exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavior. It mentions the API call (GET /v1/orders/search) and output keys, implying a read-only operation. However, it does not explicitly state that it is read-only, does not describe side effects, authorization needs, or rate limits. The transparency is adequate but incomplete.
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 sections (purpose, API, return structure) and is front-loaded with the main action. It is moderately concise, but could be shortened by removing the redundant 【用途】header. Overall, it is well-organized and every sentence provides useful information.
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?
Given the moderate complexity (7 parameters, no output schema, no annotations), the description covers the purpose, API call, and return keys. However, it lacks details on error handling, data limits, prerequisites, or explicit read-only declaration. Without an output schema, the description of the return structure is somewhat helpful 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%, so baseline is 3. The description provides context for the thresholds (r_days, f_threshold, m_threshold) by explaining their roles in segment migration, but does not add significant meaning beyond the schema descriptions. No enums or nested objects require further detail.
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: comparing RFM segment migration between two time periods for customer lifecycle analysis. It uses specific verbs (比較, 分析) and resources (RFM分群, 客戶生命週期). It is distinguishable from sibling tools like get_rfm_analysis by emphasizing the two-period comparison.
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 explains the use case (分析客戶生命週期變化) and mentions it can help formulate strategies, but it does not explicitly specify when to use this tool versus alternatives (e.g., for single-period RFM, use get_rfm_analysis). The purpose section implies the context, but no direct exclusion guidance is given.
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 provided, so the description should disclose side effects. It describes the API call and return structure, implying a read operation, but does not explicitly state read-only or mention auth requirements. Adds value with endpoint and return format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is structured with sections and is concise. It front-loads the main purpose. However, the parameter section is missing, slightly reducing efficiency.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple 1-parameter tool with no output schema, the description provides the API endpoint, return structure, and usage examples. It covers the essential aspects, though it lacks error handling or pagination details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, and the description only indirectly refers to the parameter as '指定配送方式' (specified delivery method). It does not explain how to obtain the delivery_option_id or any constraints, offering minimal additional meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
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 available time slots for a specified delivery method. It provides usage examples and differentiates from siblings like get_delivery_option_detail by focusing on time slots.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives context for using the tool (confirming slots, analyzing preferences) but does not explicitly mention when not to use it or suggest alternative tools. It lacks exclusion criteria.
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 burden. It mentions the calculation source but does not disclose if the operation is read-only, any side effects, authentication requirements, or rate limits. More behavioral context is needed.
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 deliver the core purpose and data derivation without unnecessary words. Information is front-loaded and every sentence adds value.
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 tool with one optional parameter and no output schema, the description adequately explains what the tool returns and how. However, it lacks details on response format or potential edge cases, but these gaps are minor given the 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% and the parameter 'brand' already has a description in the schema. The tool description does not add additional meaning about the parameter's effect or acceptable values beyond what the schema provides, so baseline score 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 provides an inventory overview with specific metrics (total quantity, item count, out-of-stock count) and explains the data source (from product variations' quantity field). This distinguishes it from sibling tools like get_inventory_turnover or get_stock_by_warehouse by being a high-level aggregate.
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 provide any guidance on when to use this tool versus alternatives. It lacks explicit when-to-use or when-not-to-use context, leaving the agent to infer from the tool's name and sibling tools.
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 only states the function without disclosing behaviors such as read-only nature, auth requirements, rate limits, or potential side effects. This minimal disclosure is insufficient.
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?
A single, clear sentence with no superfluous words or structure.
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-retrieval tool with one optional parameter and no output schema, the description is largely sufficient. However, it could briefly mention return type or pagination 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 schema coverage is 100% with a description for the threshold parameter. The description adds the same meaning (customizable threshold) without exceeding the schema. Thus 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 retrieves a list of SKUs with low or out-of-stock status and allows a customizable inventory threshold. The verb 'get' and resource 'low stock SKUs' are specific, and it differentiates from siblings like get_stock_by_warehouse or get_inventory_overview.
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 low stock alerts with a custom threshold, but does not explicitly state when to use this tool versus alternatives or provide when-not-to-use guidance.
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 bears full responsibility. It explains the analysis scope and a limitation, but does not disclose if the tool is read-only, any side effects, or performance characteristics. Adequate 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?
Two sentences succinctly convey the core purpose and a critical limitation without any extraneous information. Every word is necessary.
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?
The tool has 5 parameters, no output schema, and no annotations. The description fails to explain what the tool returns (e.g., segment labels, counts, or customer lists). For a complex analysis tool, this is a significant gap that hinders proper 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 description coverage is 100%, so the schema already documents all parameters. The description does not add any further meaning beyond what is in the schema, meeting but not exceeding expectations.
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 'perform RFM segmentation analysis based on order data', which is a specific verb+resource. It distinguishes from sibling analysis tools like get_customer_geo_analysis, but it does not explicitly contrast itself.
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 crucial usage constraint: only works for customers with order records, and hints at Customers API returning 403. This gives clear context on when it is applicable, though it does not mention alternative 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?
No annotations are provided, so the description must carry behavioral transparency. It mentions calling two GET endpoints ('GET /v1/orders/search' and 'GET /v1/orders'), indicating a read-only operation, but does not explicitly state non-destructiveness or other traits like 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is relatively concise with two sentences and an API list. It front-loads the purpose, but the API list adds some redundancy. No wasted sentences.
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?
Given 6 parameters and no output schema, the description misses details like output format, pagination, and ordering. It is adequate but lacks complete context for an agent to fully understand 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?
Schema description coverage is 100%, so baseline is 3. The description does not add significant meaning beyond the schema; it only reiterates filter categories already defined in the input 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 explicitly states it queries order lists by time range, status, and channel, returning a concise summary. It clearly distinguishes from sibling tools like get_order_detail or get_archived_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 filtering orders but does not explicitly contrast with alternatives or provide when-not conditions. Usage is implied by the tool name and sibling list.
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 lists side effects (binding, visibility, errors, per-customer limit) and notes it's a write operation, but lacks details on idempotency, reversibility, 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear sections and front-loaded purpose, but some redundancy (e.g., [WRITE] is evident from side effects). Overall efficient for a mutation tool.
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 lacking output schema, the description explains the return structure and side effects, covering key behavioral aspects. It could be more detailed on error handling, but sufficient for a simple claim 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?
Input schema has 100% description coverage for the only parameter, and the description does not add significant new information beyond what the schema already provides, so 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?
Clearly states verb 'claim' and resource 'coupon' in the title and description, and distinguishes from sibling tools like 'redeem_coupon' and 'send_coupon' by specifying that it binds the coupon to a customer account.
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?
Provides context for suitable scenarios (redemption code, API integration) but does not explicitly state when not to use or mention alternatives. The difference from 'redeem_coupon' is not addressed.
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?
Discloses potential error responses (403/422) and implies read-only via API endpoint method (GET). With no annotations, additional details like rate limits or data limits would improve completeness.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Structured with clear sections (intro, usage, note, API, return). Concise without unnecessary repetition, though some sections could be slightly tighter.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Provides return structure with example fields and API endpoint. For a simple single-parameter get tool with no output schema, it covers essential context. Missing details like whether the channel ID is required (already in schema) and potential error handling beyond 403/422.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema coverage, description implicitly defines channel_id through context (path and mention of 'specified sales channel'), but does not explicitly state its type, format, or required status beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves detailed information of a specific sales channel, listing included fields like type, status, and link settings. However, it does not explicitly differentiate from sibling tools like list_channels or get_channel_comparison.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides usage context ('suitable for confirming configuration') and a note about potential 403/422 errors under certain token permissions. Lacks explicit guidance on when not to use or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description is the sole source of behavioral info. It indicates a read operation ('取得') and provides the return structure, but does not disclose error handling, rate limits, or permissions required. The API endpoint is given, but not all details of tool behavior beyond the basic read.
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 into sections (purpose, API, return structure) and is relatively concise. However, it includes Chinese formatting that may reduce readability for some agents. It could be slightly more succinct, but overall well-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?
For a simple getter tool with one parameter and no output schema, the description covers the purpose, the specific API call, and the return format. It lacks mention of error conditions or prerequisites, but is largely complete for basic usage.
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 clear description for the only parameter (order_id as internal ID). The tool description adds no additional meaning beyond the schema. With 100% schema coverage, score is 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?
The description clearly states the tool's purpose: retrieving all tags attached to a specific order for classification or filtering. It uses specific verbs ('取得' = get) and resource ('訂單標籤' = order tags), effectively distinguishing it from sibling tools like get_order_detail or update_order_tags.
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 mentions that tags can be used for classification or filtering but does not explicitly state when to use this tool over alternatives. There is no guidance on prerequisites (e.g., order must exist) or comparisons to related tools like get_order_labels or update_order_tags.
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 cover behavioral traits. It discloses the return structure (dict with staff_id, permissions) and references the API call, but does not address authorization requirements, rate limits, or side effects. For a read tool, this is adequate but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with sections for purpose, API call, and return structure. It is concise yet informative, front-loading the main purpose. Every section adds value without redundancy.
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?
Given the tool's simplicity (one parameter, no output schema), the description provides a reasonable overview. However, it lacks details about the permissions structure (e.g., possible actions) that would be useful for an agent, especially without an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter staff_id has no description in the schema (0% coverage), and the tool description does not add any additional meaning, format, or constraints beyond its name. Since schema coverage is low, the description should compensate but fails to do so.
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 '取得指定員工的權限設定' (get specified staff's permission settings) and explains it queries backend access permissions for functional modules and operation levels. This clearly distinguishes it from sibling get_* tools by specifying the exact resource (staff permissions).
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 '適合確認員工權限配置或排查存取問題' (suitable for confirming permission configuration or troubleshooting access issues), providing clear usage context. Although it doesn't explicitly exclude alternatives, the purpose 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?
No annotations provided, so description carries full burden. It discloses that the message cannot be withdrawn or modified after sending, and that it adds a message to the buyer's inbox with immediate notification. This provides useful behavioral context 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is efficiently structured with bullet points for usage, API, return, and side effects. It is front-loaded with the action and concise, though could be slightly more 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?
Given no output schema, description explains return structure (dict with success, resource_id, etc.) and side effects. It also provides the API endpoint. However, it lacks prerequisites (e.g., order existence) and does not clarify differentiation from 'send_shop_message'.
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% due to example within the schema itself. The tool description does not add new semantic information about the parameter; it merely restates example usage. Thus, no additional value is provided.
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?
Description clearly identifies the tool as sending order-related conversation messages to buyers. It specifies the verb 'send' and resource 'order message' and provides usage scenarios like order notifications and customer service replies. However, it does not explicitly distinguish from the sibling tool '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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description lists relevant use cases (e.g., shipping notifications, customer service replies) but does not specify when not to use or mention alternatives like 'send_shop_message'. It gives clear context but lacks 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?
No annotations provided, so the description carries full burden. It lists side effects such as commission calculation and financial risks, adding transparency 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear sections and front-loaded purpose. Each section is concise and informative, though some redundancy exists (e.g., API endpoint in multiple places).
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?
Covers creation context and side effects, but lacks details on required fields within campaign_data and does not explain the return structge thoroughly. Missing output schema increases need, but description partially addresses 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?
Only one parameter (campaign_data) with 100% schema coverage. The schema description is vague, and the tool description does not add meaningful detail about the object structure, so it adds little beyond the schema.
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?
Clearly states it creates an affiliate campaign with reward rules, distinguishing it from siblings like update or delete. However, it does not explicitly contrast with update or other creation 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?
Includes a usage section explaining when to use the tool for setting up affiliate campaigns, but lacks explicit when-not-to-use or alternative tool references.
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, description fully discloses side effects (auto-activation, price display, overlap considerations) and API details, adding behavioral context 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?
Well-structured with sections for purpose, use cases, API, return, side effects. Front-loaded and concise without redundancy.
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?
Covers purpose, side effects, return structure, but fails to elaborate on campaign_data parameter structure, which is critical for correct invocation given no output schema and nested object.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Single parameter campaign_data lacks detailed semantic explanation; schema only defines it as an object with additionalProperties, and description only references external structure, leaving agent without guidance on required fields.
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 tool creates a flash price campaign for limited-time sales, with use cases like holiday sales and clearance. Differentiates from siblings like create_promotion and update_flash_price_campaign by specifying flash sale context.
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?
Provides use cases (holiday, clearance, limited-time) but lacks explicit comparison to sibling tools or when-not-to-use guidance. Implicit differentiation but not 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 were provided, so the description carries the full burden. It implies a read operation (GET API, retrieving history) but does not explicitly state side effects, rate limits, pagination, or error conditions. The return structure is given, but behavioral guarantees are lacking.
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). It is front-loaded and efficient, though the inclusion of a full JSON example adds length but aids understanding. Every sentence contributes meaning.
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, parameter source, and return format adequately. It lacks error handling or edge cases, but these are acceptable for this complexity level.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 100% of parameters, and the description adds crucial context: the order_id is the internal ID from query_orders, not the order_number. This prevents misuse and clarifies data source, adding significant 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 retrieves all operation history for a specified order, including status changes, personnel, timestamps, and is suitable for audit trails. This specific verb-resource combination distinguishes it from siblings 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 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. While the description mentions suitability for audit trails, it does not exclude other uses or compare with other order-related tools. Missing context like prerequisites (e.g., order must exist) or when not to use.
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 provided, so description must disclose behavioral traits. It states 'complete information' but does not detail read-only nature, rate limits, or effects. Adequate for a simple read tool but lacks extra 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?
Single, front-loaded sentence with no fluff. Every word adds value.
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 get tool with one param and no output schema, the description adequately conveys purpose and content. Minor improvement possible: explicitly mention that order_id comes from query_orders.
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 description adds no additional parameter info beyond the schema's own description. 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 complete information for a single order, listing key areas (product details, payment, logistics, discounts). It distinguishes well from siblings like query_orders (list) and other get_* tools for specific aspects.
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 when full order details are needed, but does not explicitly mention when to use vs siblings (e.g., get_order_delivery) or provide prerequisites or 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 bears full responsibility. It mentions the API endpoint and that it retrieves data, but does not disclose safety, side effects, error handling, or other behavioral traits. The description is adequate but lacks explicit read-only or mutation clarity.
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 sentences that cover the tool's purpose and the underlying API endpoint. Every word contributes value, and there is no redundant or extraneous 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?
Despite the absence of an output schema, the description is fairly complete by specifying that variants include a size×color inventory matrix. For a simple read tool with one parameter, this provides sufficient context for an AI agent to understand what data to expect.
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 only one parameter (product_id) described as '商品 ID'. The description does not add additional meaning beyond the schema, so the baseline score of 3 is appropriate per 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 retrieves all SKU variant details for a specific product, including a size×color inventory matrix. This distinguishes it from sibling tools like get_product_list or get_inventory_overview, which serve different purposes.
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 when needing variant-level details for a product, but it does not explicitly state when to use this tool over alternatives, nor does it provide exclusions or prerequisites. Guidance is purely 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 carries full burden. It indicates a read operation (analysis) and lists the metrics (usage counts, discount types, status distribution), but does not disclose whether the tool returns aggregated data, if pagination is involved, or any authentication/permission requirements. This is adequate but leaves gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two short sentences in Chinese, front-loaded with the main purpose. Every word earns its place with no 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 analysis tool with 2 parameters and no output schema, the description covers the core purpose and output metrics. It could describe the return format (e.g., list of aggregated records) but is largely complete 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?
Input schema coverage is 100% (both parameters described). The description does not add new meaning to the parameters beyond what the schema already provides. Baseline score of 3 is appropriate as the schema already handles 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 clearly states the tool's purpose: analyzing promotion campaign effects including usage counts, discount types, and status distribution. It distinguishes itself from sibling tools like get_promotion_roi (specific ROI analysis) and get_promotion_detail (single promotion detail) by focusing on aggregated analysis.
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 analyzing promotion effects and mentions combining with sales data for ROI, but does not explicitly state when to use this tool over alternatives like search_promotions or get_promotion_roi. No usage exclusions or prerequisites 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?
With no annotations, the description carries the burden of disclosing behavior. It implies a read-only report by stating it returns statistics, but does not explicitly confirm non-destructive nature or mention any side effects. The information is adequate but could be more explicit.
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 (two sentences) and front-loaded with the primary purpose. Every sentence adds value, with no extraneous text.
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 absence of an output schema, the description lists the returned metrics (refund amount, number of returns, return rate, product details, net revenue). It could be more specific about the structure (aggregated vs. per-day), but overall sufficiently complete for a summary 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 covers 100% of parameters with descriptions for start_date and end_date. The tool description adds context that these define the time range for the statistics, enhancing 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 it retrieves refund/return statistics for a specified date range, listing specific metrics (refund amount, number of returns, return rate, product details, net revenue). This distinguishes it from siblings like get_refund_by_store which likely filter by store.
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. While the context signals and sibling list suggest other refund/report tools, the description does not specify when this is appropriate or when other tools should be used.
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 carry the full burden. It discloses the return structure (dict with total_found, returned, items containing specific fields) and implies a read-only operation via the GET API. It does not discuss rate limits, authentication needs, or potential side effects, but the return detail 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 sections (用途, 呼叫的 API, 回傳結構), each sentence adds value, and it is concise without extraneous 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?
Given the tool has only 2 parameters, no output schema, and no nested objects, the description adequately covers the return structure and API endpoint, providing enough context for an AI 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?
Schema coverage is 100%, so baseline is 3. The description mentions 'supports filtering by status' which adds minimal value beyond the schema's parameter description. No additional insights are provided for 'max_results'.
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 lists promotions with status filtering, and includes the return structure. However, it does not explicitly differentiate from the sibling 'search_promotions' tool, which could have overlapping functionality.
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: browse promotions to understand their statuses, analyze strategies, and obtain promotion IDs for further detail queries. It does not, however, mention when not to use it or point to alternatives like 'search_promotions'.
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 labels the tool as WRITE, states changes take effect immediately, irreversibility but ability to overwrite, and provides return structure. This adequately discloses behavioral traits beyond simple read/write.
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 (WRITE, 用途, API, return, side effects) and is front-loaded with the main action. Each sentence serves a purpose with no redundancy, though it could be slightly more concise.
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 with full schema coverage, a return structure specification, and side effect disclosure, the description is complete for an update tool. It lacks mention of authorization or permissible field constraints, but these are minor gaps in this 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 schema has 100% coverage for both parameters. The description adds value by explaining it is a partial update (only pass fields to change) and listing example fields (name, price, image). This provides meaningful context beyond the schema definitions.
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 'update addon product data' and lists specific fields like name, price, and image. It distinguishes from sibling tools like create_addon_product and update_addon_product_quantity, but could more explicitly differentiate when to use each.
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 includes a '用途' section advising to only pass fields to modify, providing basic usage guidance. However, it does not clarify when to use this tool versus alternatives such as update_addon_product_quantity or create_addon_product, missing explicit when-not or alternative recommendations.
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?
Despite no annotations, description discloses write nature, permanence, irreversibility, partial retention of order records, and immediate frontend removal.
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?
Well-structured with labeled sections (purpose, API, return, side effects). Some redundancy but overall efficient for the information provided.
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?
No output schema but return structure described. Side effects and API endpoint provided. Sufficient for a simple delete operation with one 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 covers the single parameter fully (100% coverage). Description adds no additional semantics beyond the schema's '商品內部 ID'.
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?
Clearly states it deletes products permanently from Shopline store. Distinguishes from sibling tools with different resources (categories, 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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides context for typical use (clearing delisted items, test data) but lacks explicit when-not-to-use or alternatives among siblings.
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 provided, so description carries full burden. It describes the tool as a read operation ('取得完整資訊') and references the API endpoint. It does not mention side effects, auth, rate limits, or error conditions, which could be more explicit.
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 sections (purpose, API, response). Each sentence adds value, though it is longer than necessary. Front-loaded with main 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 tool has one parameter and no output schema; the description compensates by detailing the return fields (id, status, tracking, address, line_items, timestamps). It covers usage context adequately. Could mention error scenarios.
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 a clear description of delivery_id. The description adds context that ID comes from get_order_detail, but no further parameter details beyond what 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?
Description clearly states the tool retrieves complete delivery info including status, tracking number, and address. It specifies it's for a single delivery, distinguishing it from list tools and update tools like update_order_delivery.
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: tracking packages, confirming recipient info, customer service. It mentions delivery_id comes from get_order_detail. However, it does not explicitly exclude alternative tools 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description reveals that the tool calls two internal APIs (GET /v1/promotions and GET /v1/orders/search) and returns a dict. However, it does not disclose potential side effects (none expected), rate limits, or performance implications. Without annotations, more explicit safety guarantees would be beneficial.
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 concise at around 100 characters. Every sentence adds value, though minor redundancy exists (e.g., repeating 'promotion_items').
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 complexity (composite operation with two APIs) and no output schema, the description provides a clear return structure and explains the business logic. It lacks details on edge cases (e.g., no promotions or orders) and prerequisites, but overall covers the essential aspects.
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 clear descriptions for both parameters (start_date and end_date with YYYY-MM-DD format). The description adds context that these define the time range for active promotions, but this does not significantly enhance understanding beyond the schema, leading to 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's purpose: cross-referencing promotion and sales data to calculate ROI for each promotion. It specifies inputs (date range), outputs (orders count, revenue, discount, ROI), and the return structure, distinguishing it from siblings like list_promotions or 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 description indicates when to use the tool (to get ROI for promotions in a date range) and implies its aggregation nature. It does not explicitly state when not to use it or name alternatives, but the context is clear enough for an agent to infer correct usage.
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?
Although no annotations are provided, the description details the underlying API calls (GET /v1/return_orders and GET /v1/orders/{order_id}) and the return structure, offering good insight into behavior. It does not mention permissions or rate limits, but 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with sections for purpose, usage, API calls, and return structure. It is slightly verbose but clear and front-loaded with key 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?
Given no output schema, the description provides a clear return structure (period, total_return_orders, stores with statistics). It covers the essential information, though details on pagination or limits are 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 descriptions for both parameters. The description adds no extra meaning beyond the schema; it only repeats that dates are in YYYY-MM-DD format. 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 purpose: analyzing return/refund distribution by store/channel. It specifies the action (get refunds by store), the resource (returns per store), and distinguishes from siblings like 'get_refund_summary' by focusing on store-level analysis.
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 context on when to use (for store-level return analysis within a date range) but lacks explicit guidance on when not to use or alternatives. Given the large sibling list, more differentiation would be helpful.
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 full burden. It discloses the internal computation (cross-referencing inventory and sales, calculating days_of_supply) and the APIs called (GET /v1/products, GET /v1/orders/search). It also describes the return structure, though it does not explicitly state it's read-only or mention rate limits. Overall, it offers good insight into 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 with labeled sections (purpose, usage, API calls, return structure) and is reasonably concise. It contains all necessary information without verbose repetition, though it could be slightly shorter.
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 an output schema, the description usefully specifies the return dict structure (period, period_days, total_products, slow_movers). It explains the analytical process and parameters. It does not cover error handling or pagination, but for a read-only analysis 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%, so baseline is 3. The description does not add significant new meaning beyond what the schema already provides (start/end dates, threshold default). It reinforces context but does not compensate for low coverage, which is not an issue 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 identifies the tool's purpose: finding slow-moving inventory items by comparing stock and sales. It explains the logic (days_of_supply, threshold) and distinguishes itself from siblings like get_inventory_turnover or get_low_stock_alerts, which focus on different metrics.
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 states it assists clearance decisions but does not explicitly mention when to use this tool versus alternatives (e.g., get_inventory_turnover). It lacks exclusions or 'when not to use' guidance, making it less helpful for selection among similar 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?
No annotations provided, so description carries full burden. It discloses immediacy of effect, synchronization, and irreversibility (no version history) – valuable beyond a simple 'update' claim.
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, usage, API, return, side effects). Every sentence adds value. Front-loaded with purpose and partial update hint.
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?
Covers purpose, usage, API, return structure, and side effects. Minor gap: no error handling or what happens if variation doesn't exist. Otherwise complete for a mutation 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 coverage is 100% with descriptions, and the description adds key semantic: only changed fields need to be passed in variation_data, clarifying partial update pattern beyond the schema.
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?
Description clearly states it updates product variation data (SKU, spec options, status) and includes a [WRITE] tag. However, it does not explicitly differentiate from sibling tools like update_variation_price or update_variation_quantity, which update specific subfields.
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?
Describes partial update behavior ('only pass fields to modify') and lists API, return structure, and side effects. But it lacks explicit guidance on when not to use or alternatives among sibling update 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?
No annotations are provided, so the description carries the full burden. It mentions the GET API endpoint, implying it's a read-only operation with no side effects. However, it does not explicitly state idempotency or permissions, which would enhance transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (用途, API, 回傳結構). It is concise with no unnecessary information, every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description provides the return structure (dict with fields), which is helpful since there is no output schema. It covers the essential information for using the tool. Could mention error scenarios or required permissions, but overall complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'category_id' has a description in the input schema that already explains it comes from get_category_tree. The tool description does not add further semantic value beyond what is already in the schema. With 100% schema coverage, baseline is 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves full details of a single product category, specifying fields like name, description, parent category. It distinguishes itself from sibling tools like get_category_tree (which lists categories) and update_category.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
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: when needing detailed info for a known category ID. It implies that if the ID is unknown, one should first use get_category_tree. It doesn't explicitly state alternatives or when not to use, but the guidance is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries the burden. It describes the HTTP GET call and return structure, implying a read-only operation. However, it does not explicitly state side effects, permissions, or rate limits, which are common for such calls.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured with clear sections for purpose, API endpoint, and return format. No unnecessary words; every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
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 provides sufficient information: API path, return structure, and a usage hint. It could mention pagination if the list may be large, but it is not a critical gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (only one parameter with a clear description). The tool description adds no new parameter details beyond what the schema already provides, so it meets the baseline but does not exceed it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
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 customer IDs in a given group (verb 'get', resource 'customer group members'), and it explicitly differentiates from sibling tools like list_customer_groups and get_customer_profile by suggesting chaining.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The '用途' section explains the use case: querying which customers belong to a specific group. It also recommends combining with get_customer_profile. However, it does not provide explicit when-not-to-use scenarios or compare with other customer-listing tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It indicates a read operation via the API method (GET) and describes the return structure (a dict with fields like id, name, etc.). It does not mention side effects or contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (用途, API, 回傳結構) and provides all necessary information in a concise, front-loaded manner without superfluous content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the description includes the API endpoint and return fields, it lacks parameter details and does not fully compensate for the missing output schema. Given the tool's simplicity, it is marginally adequate but has gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter delivery_option_id has no description in the input schema (schema_description_coverage = 0%). The tool description does not explain its purpose, format, or how to obtain it, leaving the agent without guidance beyond the name.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
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 (指定配送方式的詳細資訊), distinguishing it from sibling list_delivery_options. It specifies that it retrieves detailed settings for a single delivery method.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
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 this tool: to query a single delivery method's complete settings and confirm specific conditions. It mentions the API endpoint but does not explicitly state when not to use it or list alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description provides basic behavioral context by specifying the API endpoint and return structure. However, it does not explicitly confirm that the operation is read-only, mention authentication needs, or describe any side effects. It covers the essential but not comprehensive behavioral 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 uses clear sections (【用途】, 【呼叫的 Shopline API】, 【回傳結構】) that front-load the purpose and structure. Every sentence is informative and necessary, with 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?
Given no output schema, the description adequately describes the return structure (total and items with fields). It covers the API endpoint and purpose. However, it omits potential details like pagination or limits, but given the tool's simplicity (zero parameters), it is largely 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 has no parameters (100% coverage), and the description adds no parameter information because there is none to add. According to guidelines, zero parameters baseline is 4. The description compensates by clarifying what the tool returns, adding 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 explicitly states the tool retrieves a list of locked/reserved inventory items, using specific verbs and resource ('取得...庫存商品清單'). It clearly distinguishes 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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for analyzing SKUs with reserved quantities but does not explicitly state when to use or not use this tool versus alternatives like get_stock_by_warehouse or get_inventory_overview. No exclusions or comparisons 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 full burden. It discloses that the tool uses a GET endpoint and returns a dictionary with specific fields, but does not mention auth requirements, rate limits, or idempotency. It provides basic behavioral traits but lacks completeness.
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, 回傳結構). It is concise, containing only necessary 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?
Given the tool's simplicity (1 parameter, no annotations, no output schema), the description covers purpose, API endpoint, and return fields. It could mention read-only semantics, but overall it is sufficiently complete for an agent to use 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?
With 0% schema description coverage, the description adds minimal value for the parameter. It refers to 'specified merchant' but does not elaborate on the format, source, or constraints of merchant_id, relying on the parameter's obvious nature.
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 detailed information for a specified merchant, listing specific fields. It distinguishes itself from sibling tools like list_merchants by focusing on a single merchant's full settings.
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 the tool: to query a single merchant's complete settings for confirmation or data verification. It implies the use case but does not explicitly state when not to use or provide alternative tool names.
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 details the API endpoint and response structure, including transaction types (sale, refund, void) and fields. This helps the agent understand the tool's behavior as a read operation. However, it does not discuss authentication requirements, rate limits, or potential failure modes (e.g., invalid order_id). Given the lack of annotations, the description is fairly 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 (用途, API, 回傳結構) and is concise. It front-loads the purpose, provides the endpoint, and gives a detailed response example. Every sentence adds value, and there is no redundant information. It is efficiently organized for quick comprehension.
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?
Without an output schema, the description compensates by providing a detailed response structure with key fields (id, kind, status, amount, gateway, created_at). It also mentions the API endpoint. However, it omits error handling, validation prerequisites (e.g., order must exist), and pagination details (if any). For a read operation with a single parameter, this is mostly complete but has 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 input schema has 100% description coverage for the single parameter order_id, which already clarifies that it is the internal ID (not order number). The description text does not add additional parameter semantics beyond this. Therefore, the description does not significantly enhance parameter understanding beyond what the schema provides, resulting in 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?
The description explicitly states the tool's purpose: '取得指定訂單的所有付款交易紀錄' (retrieve all payment transactions for a specified order). It also mentions use cases ('對帳與財務核查' for reconciliation and financial audit). This clearly distinguishes it from sibling tools like get_order_detail (order details) or get_order_delivery (delivery info), making the purpose highly specific and clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear use case (reconciliation, financial audit) and lists the API endpoint, but it does not explicitly state when to use this tool over alternatives or any exclusions. There is no comparison with other order-related tools or guidance on prerequisites (e.g., ensuring the order exists). This is adequate but lacks proactive usage direction.
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 specifies the API endpoint and return structure but does not disclose pagination, rate limits, or whether the list is filtered by 'enabled' or includes all options with a flag. Ambiguity exists between the phrase 'enabled delivery options' and the inclusion of an 'enabled' field.
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 headings and bullet-style formatting. It is concise but includes useful details. Minor redundancy in listing examples could be trimmed, but overall it is efficient.
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?
Given no output schema, the description provides the return structure with fields. However, it lacks information on pagination, sorting, and whether the list is truncated. For a list operation, this is a notable gap.
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 no parameters, so the input schema is fully covered. The description does not need to add parameter information, and it appropriately omits any.
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 enabled delivery options for a store, with examples like home delivery, convenience store pickup, and in-store pickup. This distinguishes it from sibling tools like get_delivery_option_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 explains when to use this tool: to view all shipping methods and analyze delivery preferences. It does not explicitly state when not to use it or provide alternatives, but the context is clear given 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?
With no annotations provided, the description carries the full burden. It discloses the API endpoint (GET /v1/flash_price_campaigns) and the return structure (dict with total_found, returned, items containing specific fields). However, it lacks details on pagination behavior, sorting, or any filtering capabilities beyond the max_results parameter. This is adequate but leaves some 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 with clear sections (purpose, usage, API call, return structure). It is concise yet informative, using bullet points and no unnecessary words. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given a simple input schema (one optional parameter) and no output schema, the description provides a detailed return structure and a forward reference to another tool. It is mostly complete but could mention pagination or sorting behavior to fully compensate for the lack of 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?
Schema coverage is 100% with one parameter (max_results) already described in the schema as '最多回傳筆數'. The description does not add additional semantic value beyond this. The baseline is 3 due to high coverage, and no extra 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 lists flash price campaigns, with specific purpose of browsing all flash sales and obtaining campaign IDs for further detail. It distinguishes itself from sibling tools like create_flash_price_campaign and get_flash_price_campaign_detail by explicitly mentioning the latter for full details.
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 '用途' section explaining when to use the tool: to browse all flash sales and understand campaign details. It also gives an explicit alternative: after obtaining campaign_id, call get_flash_price_campaign_detail. However, it does not explicitly state when not to use this tool, such as for retrieving a single campaign directly.
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 cover behavioral traits. It implies a read-only GET operation and describes the return structure, but does not explicitly state read-only status, authentication needs, 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with headers and bullet points, front-loading the purpose. It is concise but includes some redundant details (e.g., API endpoint).
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 (1 parameter, no output schema), the description covers purpose, usage, return structure, and related tool, making it fully sufficient 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?
Schema coverage is 100% with a single parameter max_results. The description does not add extra meaning beyond the schema's default and description, so baseline score 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 that the tool lists product subscriptions, explains its purpose, and distinguishes it from related tools like get_product_subscription_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?
Provides explicit guidance on when to use the tool (browsing subscriptions, analysis) and mentions chaining with get_product_subscription_detail, but lacks explicit when-not-to-use or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description discloses API call, side effects (batch update, partial failure, customer notifications), and return structure, compensating well.
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 sections for purpose, API, return, side effects. Front-loaded and concise, no superfluous text.
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 key aspects: batch operation, potential partial failures, return format. Sufficient for correct agent invocation given tool 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?
Single parameter order_ids with 100% schema coverage; description adds context of batch usage but no extra semantics 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?
Clearly states it's a write operation for batch executing multiple order shipments, distinguishes from single-order execution. The title and description specify the action and resource.
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?
Describes use case for daily batch shipment but lacks explicit when-not-to-use or comparison with sibling execute_order_shipment for single orders.
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. The 【副作用】 section discloses immediate effect, potential average rating updates, and partial failure behavior, which is valuable behavioral context 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with labeled sections ([WRITE], 【用途】, etc.), front-loading the purpose. It is slightly verbose but each section earns its place. A bit more conciseness could improve readability.
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 includes a return structure summary and side effects. It also mentions the API endpoint. It is fairly complete for a bulk update tool, though it does not cover authentication or permissions.
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 parameter 'updates' is already documented in the schema. The tool description does not add additional semantics beyond what the schema provides, so it meets 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 '批次更新多筆商品評論' (batch update multiple product reviews) with a [WRITE] prefix, distinguishing it from sibling tools like 'bulk_create_product_reviews' and 'bulk_delete_product_reviews'. The verb+resource+scope is 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 Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 【用途】 section provides a clear example ('適用於管理員批次公開或隱藏評論'), indicating appropriate use cases. However, it does not explicitly mention when to use the single update tool ('update_product_review') instead, lacking when-not and 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?
With no annotations provided, the description discloses the side effect of adding a record to the gift list and the ability to set conditions via promotion rules. It also describes the return structure, providing good behavioral context beyond bare creation.
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, well-structured with clear sections (WRITE, purpose, API, return, side effects), front-loading the key information. Every section 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?
Despite no output schema, the description describes the return structure and side effects. It covers the API endpoint, purpose, and how it integrates with promotions, making it sufficiently complete for a create 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 coverage is 100% as the single parameter 'gift_data' has a description with examples. The main description does not add additional parameter semantics beyond the schema, so it meets 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 it creates a new gift record in the Shopline store, explicitly marked as [WRITE] and provides the purpose. It differentiates from similar tools like update_gift and list_gifts 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 mentions it can be used with promotions but does not explicitly state when to use it versus alternatives like update_gift or when not to use it. Implied by context but lacks explicit 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 discloses critical behavioral traits: permanent deletion (不可復原) and automatic main image replacement. Missing details on authorization or rate limits, but overall good 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-structured with sections (WRITE, purpose, API, return, side effects) and is concise without unnecessary words. Slightly verbose with whitespace, but effective.
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 (no output schema, two parameters), the description covers purpose, usage, API, return structure, and side effects. Contextually sufficient for agent 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 coverage is 100%, and descriptions for product_id and image_ids are already in the schema. The 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 clearly states this tool deletes product images with the verb 'delete' and resource 'product images'. It also distinguishes from sibling tools like add_product_images and other update/delete 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 provides context for when to use (removing outdated or incorrectly uploaded images) but does not explicitly state when not to use or mention alternatives like add_product_images.
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 provided, so description carries full responsibility. It mentions the API method (GET) indicating a read operation, but does not explicitly state idempotency, rate limits, or authentication requirements. The description is adequate but could be more explicit about the read-only nature.
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 concise and well-structured with clear sections (用途, API call, return structure). Every sentence adds value, and no redundant information exists.
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 details the return structure (dict with specific fields) which compensates. Given the simplicity of the tool (single parameter, no nested objects), the description fully covers what the agent needs to know 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 single parameter campaign_id is already described in the schema as being obtained from list_affiliate_campaigns. The tool description adds no new parameter semantics beyond that; since schema coverage is 100%, 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?
Description clearly states the tool retrieves complete details of a single affiliate campaign, specifying it queries commission rules, scope, and promotion links. It distinguishes itself from sibling tools like list_affiliate_campaigns and update_affiliate_campaign by focusing on detail retrieval for a known 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?
Description indicates proper use is when campaign_id is known, implying prior use of list_affiliate_campaigns. It provides clear context for use but does not explicitly exclude alternatives or state 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries the full burden. It discloses the HTTP method (GET) and return structure, but does not explicitly state it is a read-only operation or mention any authorization or rate limit requirements. The API endpoint and return fields are given, but behavioral traits beyond the obvious are absent.
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, usage, API endpoint, and return structure. Every sentence adds value, and the information is front-loaded for quick understanding. 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 tool has no output schema, so the description compensates by listing all expected return fields (id, product info, rating, content, images, reviewer, status, reply, timestamps). Parameter is well-documented. For a simple read tool, this is fully contextual and sufficient.
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?
Only one parameter 'comment_id' with full schema description. The description mentions 'comment_id' in the API path but adds no extra semantic beyond what the schema already provides. Schema coverage is 100%, 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's purpose: retrieving detailed content of a single product review, including images and merchant replies. It uses specific verbs and resources ('取得單一商品評價的完整內容') and distinguishes itself from sibling tools like 'list_product_reviews' (which lists reviews) and 'get_product_subscription_detail' (different domain).
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: customer service, tracking reply progress, manual review. It does not explicitly state when NOT to use it or list alternatives, but the context makes it clear this is for detailed individual review rather than listing. Lacking explicit exclusions for sibling tools, but still clear.
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 disclose behavioral traits. It does not explicitly state that the operation is read-only or require authentication, but for a simple list retrieval with no parameters, the lack of such details 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 a single sentence that conveys the tool's purpose without any wasted words. It is front-loaded and efficient.
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 provides complete information needed for an agent to understand its function. There are no missing contextual details.
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?
With zero parameters, the description correctly implies no inputs are needed. The schema coverage is 100% (no params), so the baseline is 4. The description adds meaning by specifying the returned resource type.
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 all warehouses/store locations. It uses a specific verb ('get') and resource ('warehouses'), and distinguishes from siblings like 'get_stock_by_warehouse' which focus on stock rather than the list itself.
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 provide explicit guidance on when to use this tool versus alternatives. Usage is implied by the tool's purpose, but there is no mention of when not to use it or alternatives for related queries like stock levels.
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 full burden for behavioral traits. It discloses the return structure (dict with total_found, returned, conversations) and fields (id, platform, status, created_at). However, it does not explicitly state that this is a read-only operation or mention any side effects. For a list tool, this is adequate but not exemplary.
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, and return structure. It is concise with no redundant information. Every sentence adds value, and the front-loaded purpose immediately informs the 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?
Given the tool's simplicity (one optional parameter, no output schema), the description fully covers what an agent needs: purpose, usage flow (browse then drill down), API details, and return structure. It is complete for the complexity level.
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 one optional parameter (max_results) described in the schema. The description does not add additional meaning beyond what the schema provides, such as format or default behavior. Baseline score of 3 is appropriate as schema already documents 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 the tool's purpose: '取得客服對話列表' (get customer service conversation list). It explains that it provides a summary list of all conversations for browsing current/historical status. It distinguishes itself from sibling tool get_conversation_messages by noting that this tool is for browsing summaries, while the sibling retrieves full message details.
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 this tool: to browse the summary list of conversations and screen which conversations to retrieve details from. It names the alternative tool (get_conversation_messages) for full messages. It does not explicitly state when not to use, but the 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?
With no annotations provided, the description fully discloses side effects: the original order status may change, the operation is irreversible, and already shipped orders cannot be split. It also specifies the API endpoint (POST /v1/orders/{order_id}/split). This provides comprehensive behavioral 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-structured with clear sections: purpose, usage, API call, return structure, and side effects. It is concise overall, though slightly lengthy due to the side effects list. The information is 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?
The description covers the return structure (dict with success, resource_id, message) despite no output schema, and lists important side effects. However, it lacks prerequisites like order existence or status constraints beyond 'order already shipped', making it slightly incomplete for a mutation 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 coverage is 100% with basic parameter descriptions. The description adds that 'split_config' is a dictionary following Shopline API specs, but does not elaborate on its structure. While this adds some context, it does not significantly surpass the schema's explanations, meriting 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?
The description clearly states the tool's purpose: splitting an order into multiple child shipping documents. It uses a specific verb-resource combination ('split order') and distinguishes itself from sibling tools like 'cancel_order' or 'update_order' by focusing on the splitting functionality.
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 scenarios ('分批到貨' and '不同倉庫分開出貨') but does not explicitly mention when not to use this tool or suggest alternatives. Sibling tools include other order modifications, but no direct comparison is made.
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?
Description explicitly lists side effects: creates a new record and enables subsequent inventory confirmation. It also mentions the API endpoint. No annotations provided, so description carries full burden and does well.
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-organized with [WRITE] prefix, separate sections for purpose, API, return structure, and side effects. Every sentence is informative and concise, no 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?
Despite no output schema, description specifies return dict structure. It also covers side effects. Given the one complex parameter and no annotations, the description is fairly complete and actionable for an agent.
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 'purchase_order_data' is described with an example structure including supplier_id and items array, adding meaning beyond the schema's generic object type. Schema coverage is 100% but description adds 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?
Description clearly states it creates a new purchase order in the POS system with the [WRITE] tag and explains it records supplier purchases. Distinct from sibling tools like list_purchase_orders or delete_purchase_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?
Description describes its purpose but does not provide explicit guidance on when to use vs alternatives or exclusions. It is implied for creating new orders, but lacks exclusion criteria.
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 details side effects: creating a return record with pending review status, triggering return flow that may affect inventory and financial accounting, and potential API errors. This covers the main behavioral traits, though it lacks specifics on authorization needs 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, usage, API endpoint, return structure, and side effects. It is front-loaded with [WRITE] and a concise purpose statement. Every sentence adds value, and there is no wasted wording.
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 absence of an output schema, the description includes a '回傳結構' section that details the return format. Side effects and potential errors are also covered. Parameter information is provided. However, since the tool is a write operation with no annotations, some details like required permissions or idempotency are missing, 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?
The tool has only one parameter (return_order_data) with 100% schema description coverage, including an example in the schema's description field. The tool description itself does not add additional parameter semantics beyond what the schema provides, so the baseline score is 3. The example is helpful but not extra-semantic guidance.
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: [WRITE] 建立退貨／退款申請單 (create return/refund request), specifying it is for customer service handling returns/exchanges. The verb '建立' plus resource '退貨／退款申請單' is specific, and the mention of the Shopline API endpoint further distinguishes it from sibling tools like cancel_order or update_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 description provides a '用途' section that explains the context: for customer service processing return/exchange flows. It implies when to use it but does not explicitly state when not to use or provide alternatives. The note about API errors if conditions are not met gives some guidance. However, there is no direct comparison to sibling tools like update_return_order or list_return_orders.
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. It discloses the API endpoint, return structure, and fields, indicating a read-only query operation. It does not mention rate limits or permissions, but the return structure and purpose are well-covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with sections for purpose, API call, and return structure. It is somewhat long due to the included output schema, but that adds value. Every part is useful, though it could be slightly more concise without losing clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (3 parameters, no output schema), the description fully compensates by detailing the return structure, fields, and types. It also includes the API endpoint, making it complete for agent understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with descriptions already provided for start_date, end_date, and max_results. The description adds no additional meaning beyond what the schema offers, so it meets the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states it queries archived/historical order lists, distinguishing it from siblings like 'query_orders' which likely handles active orders. The verb '查詢' and resource '已封存（archived）的歷史訂單列表' are specific and clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly indicates the tool is for accessing long-term archived orders, implying it is not for current orders. It does not explicitly state when not to use or name alternatives, but the context of siblings and the term 'archived' provide clear guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 tool calls a GET API and provides the expected response structure with fields like tracking_number and label_url, indicating it is read-only. It does not mention prerequisites or error conditions, but the API call and response are well-documented.
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, 回傳結構) and is concise. Every sentence adds value, 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.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the purpose, API call, and output format with a sample response. For a simple read tool with one parameter and no output schema, it is fairly complete. It could mention prerequisites like order existence, but the provided information is sufficient for basic usage.
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 description does not add any information about the order_id parameter beyond what the input schema already provides. However, schema coverage is 100% and the schema description clearly explains that the ID is from query_orders and not the order_number, 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 verb (取得/Get), the resource (配送標籤資訊/shipping label info for a specific order), and the purpose (列印物流面單或查詢寄件單號). It distinguishes this tool from other order-related tools like get_order_detail or get_order_delivery, as it specifically deals with labels.
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 printing labels or tracking shipments, which gives context. However, it does not explicitly state when not to use this tool or mention alternatives compared to sibling tools. The specific purpose is clear but lacks explicit usage guidance for an 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?
Without annotations, the description bears the full burden. It discloses the HTTP GET method and the return structure, implying a read-only operation. While it lacks explicit statements about side effects or safety, the listing nature is evident, and the information provided 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 sections for purpose, API endpoint, and return structure. It is concise yet comprehensive, using bullet-point-like formatting for readability.
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 low complexity (one parameter, no nested objects), the description is complete. It explains the return structure (dict with total_found, returned, items) and each item's fields, which compensates for the lack of an 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?
Only one parameter (max_results) with full schema description coverage. The description does not add meaning beyond the schema, 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 lists affiliate campaigns with specific use cases, such as obtaining campaign IDs for further detail queries. It distinguishes from sibling tools by mentioning get_affiliate_campaign_detail and get_affiliate_campaign_usage as follow-up steps, which differentiates its listing 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 good context on when to use the tool (browsing campaigns) and what to do next (call detail/usage tools). It does not explicitly list when not to use or alternatives, but the guidance is clear and helpful.
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 API call (GET /v1/agents) and return structure (dict with total and agents[]), implying a read-only operation. However, without annotations, it does not explicitly state safety, rate limits, or authorization requirements, leaving some gaps.
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 moderately sized and well-organized into sections (用途, API, 回傳結構). It front-loads the purpose and avoids unnecessary words, though it could be slightly more concise.
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 parameters, no output schema, and no annotations, the description provides a complete picture: purpose, API endpoint, and return format with field details. It covers all needed information for a simple list 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?
There are zero parameters, and schema coverage is 100%. The description adds value by detailing the return structure, which compensates for the lack of parameters to explain.
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 the store's agent account list, specifying its purpose for viewing agent configurations and understanding external account permissions. It distinguishes from sibling list_ tools by focusing on agents.
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: to view currently configured agents, suitable for confirming agent config or understanding external account permissions. It does not explicitly exclude scenarios or compare to alternatives but provides clear 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 API endpoint (GET /v1/membership_tiers) and the return structure, indicating a read-only operation. It adds value beyond the schema by providing the API path and response fields.
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 concise and well-structured with separate sections for purpose, API, and return structure. Every sentence adds value, and there is 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?
Although there is no output schema, the description provides detailed information about the return structure (dict with total and tiers array with fields). It fully covers what the tool does, how it is called, and what the response looks like, making it complete for a list 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 input schema has zero parameters, and schema coverage is 100%. The description does not need to add parameter info. With no parameters, the baseline is 4, and the description meets that.
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 retrieves all membership tier definitions for the store, with a specific verb and resource. The purpose section explains its use for analysis and confirmation, but it does not explicitly differentiate from sibling tools like list_member_point_rules, though the name itself is distinct.
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 for usage: analyzing member structure or confirming tier settings. It does not specify when not to use or provide alternatives, but the context is sufficient for the simple read operation.
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 disclose behavioral traits. It states the API method (GET) implying a read-only operation, and describes the return structure. However, it does not mention authentication requirements, rate limits, or potential side effects. The description 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with sections for purpose, API call, and return structure. It is fairly concise but includes some redundancy (the opening line is repeated in the usage section). Overall, it is organized 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?
Given zero parameters and no output schema, the description provides a complete picture: it explains the return structure (dict with total and payments array, including fields like id, name, payment_type, enabled, etc.). This is sufficient for an agent to understand what the tool returns. No gaps identified.
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 schema coverage is 100% (trivially). The description does not need to explain parameters. According to guidelines, baseline for 0 parameters is 4.
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 list of enabled payment methods for the store. It specifies the exact resource (payment methods) and the purpose (check available channels, analyze order payments), distinguishing it from other list tools like list_addon_products or list_channels.
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 '【用途】' section that explains when to use the tool: to view currently set payment methods, check available channels, or for order payment analysis. It does not explicitly exclude other tools, but the context is clear. No mention of when not to use or alternatives, but sufficient for most scenarios.
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 details side effects (inventory overwritten, immediate effect) and the API endpoint. However, it could mention error handling or idempotency. Still, it provides substantial 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-structured with clear sections (purpose, usage, API call, return, side effects) and front-loaded. It is not overly verbose, though it could be slightly more concise.
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 update tool with no output schema, the description covers all necessary context: return structure, side effects, full parameter semantics (via schema), and use case. It is 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% and both parameters are described in the schema (e.g., quantity is absolute value). The description does not add new parameter info beyond the schema, so score is 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?
The description explicitly states it updates gift inventory by SKU, specifies it's a WRITE operation, and mentions batch inventory sync context. This clearly differentiates it from sibling tools like update_gift or update_gift_xxx.
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 this tool is suitable for batch inventory sync scenarios, providing clear usage context. However, it does not explicitly mention when not to use or suggest alternatives, which would improve 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?
Despite no annotations, the description discloses key behavioral traits: immediate balance change, transaction history recording, and potential error on insufficient points. This exceeds expectations and provides sufficient transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
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 concise but includes some extraneous details (e.g., the exact API endpoint) that may not be necessary for an AI agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple parameter set (3 parameters, no nested objects, no output schema), the description covers purpose, behavior, side effects, and return structure adequately. It is complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with clear descriptions for each parameter. The description adds no additional parameter semantics beyond what the schema provides, so baseline score applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
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 action ('adjust customer member points') and explicitly mentions it can add or deduct points, with specific use cases like manual compensation or activity rewards. It is distinct from sibling tools, as no other tool focuses on adjusting member points.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
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 (manual points addition, activity rewards, complaint compensation) via a dedicated section. It implies when to use the tool, though it does not explicitly state when not to use it. However, given the distinct function, this is adequate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It lists side effects: adds multiple comments, potential immediate/reviewed publication, affects average rating, and partial failure behavior. Missing authentication or rate limit details, but still strong.
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 write operation, purpose, API call, return structure, and side effects. Every sentence is valuable and front-loaded with the main action.
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 1-parameter bulk create tool with no output schema, the description provides comprehensive details: use case, API endpoint, return format, and side effects. It adequately covers all necessary 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% with a clear description of the 'reviews' parameter. The description repeats the schema's explanation but does not add additional semantics beyond the example format.
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 '批次建立' (batch create) and resource '商品評論' (product reviews), with explicit use cases for bulk importing historical reviews or post-promotion entries. It distinguishes itself from single create and other bulk 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 provides explicit context for when to use (bulk imports, post-promotion) but does not include when-not-to-use or direct comparisons to alternative tools like 'create_product_review' or 'bulk_update_product_reviews'.
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 full burden. It explicitly states it is a WRITE operation, calls the POST /v1/addon_products API, and describes the return structure. It also discloses side effects: adds a record and requires enabling. This is adequate 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is organized into clear sections (purpose, API, return structure, side effects). It is front-loaded with the essential WRITE tag. While somewhat lengthy, every sentence adds value, and it is efficiently 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?
Given there is no output schema and only one parameter, the description covers the return structure, API endpoint, and side effects. It is fairly complete for a creation tool, though it lacks error handling or validation details.
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 with a description for the single parameter. The description adds meaningful example fields (name, sku, price, quantity), enhancing understanding beyond the schema's generic '加購商品資料' (addon product data).
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 with specific verb and resource: '建立新加購商品' (create new addon product). It distinguishes from sibling tools like update_addon_product and list_addon_products by explaining its role in creating products for checkout selection.
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: to create an addon product for customer selection at checkout. It also notes the side effect that the product needs to be enabled separately, implying when-not-to-use. However, it does not explicitly name alternatives or exclusions, but the context is sufficient given the sibling list.
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 side effects (adds order, may trigger inventory deduction and notifications) and warns that the order becomes active immediately. Missing details on authorization, but sufficient for safe usage.
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 structure, side effects). Each sentence adds value, no fluff. 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?
Given a single parameter, no output schema, and no annotations, the description covers purpose, usage, return structure, side effects, and warnings. It is complete enough for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only one parameter 'order_data' with 100% schema coverage. The description adds that it must include all required fields per Shopline API, which is helpful but not substantially beyond what the schema provides. 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 it creates new orders ('建立新訂單') and specifies the context (manual order creation for phone orders, customer service, etc.). It includes a [WRITE] tag and distinguishes itself from read or 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 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 (phone orders, customer service supplement, offline transfers) and provides context for its use. It could be improved by explicitly stating when not to use (e.g., for updates, use update_order), but overall 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, the description fully discloses behavioral traits: permanent deletion, irreversibility, product disassociation without deletion, and potential subcategory association impact. It also describes the return structure, making the tool's behavior 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 sections for purpose, API, return, and side effects. It is concise but includes some redundant details like the exact API endpoint. Still, it front-loads the key information 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?
For a simple delete tool, the description covers purpose, usage, side effects, and return structure comprehensively. It omits error cases or permission requirements but is otherwise complete given the tool's simplicity and lack of 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?
Schema coverage is 100% with a single parameter described. The description adds no further meaning beyond the schema's 'category ID' context. Baseline 3 is appropriate as the schema already carries the burden.
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 deletes a product category permanently. It specifies the resource (category) and action (delete), and distinguishes from siblings like update_category and create_category by focusing on removal. The [WRITE] prefix and side effects reinforce the destructive 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 states it is suitable for removing disabled or incorrectly created categories, providing clear context. However, it does not explicitly mention when not to use it or compare with alternatives like update_category for deactivation. The side effects help guide appropriate usage.
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?
States API call (GET) implying read-only behavior, but does not explicitly declare non-destructive nature or other traits like rate limits. Without annotations, description partially compensates.
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?
Well-structured with sections (purpose, usage, API, return), but slightly verbose. Each sentence adds value; no wasted text.
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, description provides return structure (dict with fields and units TWD). Covers all needed info for agent to invoke and parse results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Adds crucial info beyond schema: campaign_id is from list_affiliate_campaigns' id field, guiding the agent to chain calls 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?
Clearly states '取得...訂單使用統計' (get order usage statistics) with detailed description of returned data (orders, revenue, commission), distinguishing it from sibling get_affiliate_campaign_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?
Explicitly describes when to use: '分析特定聯盟行銷活動的訂單數與銷售額，評估推廣效果' (analyze orders and revenue for campaign performance). No explicit when-not-to-use but context is clear.
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 API endpoint (GET /v1/conversations/{conversation_id}/messages) and the return structure (dict with conversation_id, total_found, returned, messages[] including fields like id, sender_type, content, message_type, created_at). However, it does not mention potential side effects, authentication requirements, rate limits, or error behavior, leaving some gaps for a tool with no 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?
The description is efficiently structured with clear sections: 【用途】, 【呼叫的 Shopline API】, 【回傳結構】. It is concise, using bullet points for the return fields, and every sentence adds meaning. 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?
Given only 2 parameters (one required), no output schema, and no annotations, the description provides a complete picture: it explains the purpose, the source of the required parameter, the API call, and the full return structure with field details. The agent has all necessary information to invoke and interpret 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 coverage is 100%, so the baseline is 3. The description adds value by explaining that conversation_id comes from list_conversations and that max_results has a default of 50. This extra context helps the agent understand parameter origins and defaults, going beyond the schema's bare 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 '取得指定對話的完整訊息記錄' (get complete message records of a specified conversation), uses a specific verb (取得) and resource (對話訊息), and lists concrete use cases (了解客戶問題脈絡、審核客服回應品質、追蹤訂單諮詢處理進度). It distinguishes itself from sibling tools like list_conversations or get_order_detail by focusing on messages within a conversation.
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 that the conversation ID comes from list_conversations ('對話 ID 從 list_conversations 取得') and states when to use the tool (查閱特定客服對話的所有聊天訊息). While it does not list when not to use it or mention alternatives, the guidance is clear and contextually 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 the underlying API call (GET /v1/customers/{customer_id}/membership-tier-history) and the return structure (dict with customer_id, total_changes, history[]), which adds significant behavioral context beyond just the 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 concise and well-structured with sections: purpose, companion tool, API call, and return structure. Every sentence serves a purpose and is front-loaded with the core action.
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 covers the return structure, API endpoint, and usage hint. It is complete and sufficient for an agent to understand what the tool does and how to 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 (customer_id) has a schema description ('客戶內部 ID'), and the description merely says '指定客戶' (specified customer), adding little semantic value. With 100% schema coverage, the 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 retrieves membership tier change history for a specific customer, including tracking upgrades and downgrades with reasons. This is a specific verb+resource combination and distinguishes from siblings like get_customer_profile and list_membership_tiers.
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 suggests pairing with list_membership_tiers to map tier names and implies use for tracking tier changes. It provides clear context but does not explicitly state when not to use or mention alternatives, though 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It correctly states that the tool makes GET API calls, implying read-only behavior, but does not explicitly confirm zero side effects or state safety. The return structure is described, which adds transparency, but the absence of an explicit read-only declaration leaves a 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 well-structured with clear sections (用途, API calls, return structure). Every sentence adds meaningful context without redundancy, making it concise and easily digestible for an AI 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?
Given the absence of an output schema, the description provides a detailed return structure including fields like total_found, returned, items, and item attributes. This covers both parameters and expected output, making the tool fully understandable for 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% and both parameters have descriptions. The description adds value by explaining how search_keyword triggers a different API endpoint and that max_results limits response count, which goes beyond the schema's minimal 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 fetches a list of addon products with keyword search support. It differentiates from sibling tools like create_addon_product and update_addon_product by focusing on listing/reading. The specific verb-resource combination is 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?
The description explains when to use the tool (browsing/searching addon products) and the two modes based on keyword presence. However, it does not explicitly mention when not to use it or contrast with similar listing tools like list_gifts or list_promotions, leaving some room for ambiguity.
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 explains the two API endpoints and the conditional behavior (search vs list). It also details the return structure. However, it does not explicitly state that the tool is read-only or free of side effects, which would be beneficial.
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: main purpose, usage, API calls, and return structure. It is concise yet comprehensive, with no wasted sentences.
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 absence of an output schema, the description adequately documents the return structure (dict with total_found, returned, items) and key fields. It covers all necessary aspects: purpose, parameters, behavior, and output. The tool is simple and the description 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?
The schema already has descriptions for both parameters. The description adds value by explaining how the presence of search_keyword triggers a different endpoint and that max_results limits the returned items. This extra context goes 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 lists gifts and supports keyword search. It specifies the resource (gifts) and the verb (list/search). It also distinguishes from sibling tools like create_gift or update_gift by focusing on read-only listing.
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 explaining when to use the tool: to browse or search gift settings. It also clarifies the behavior based on whether a keyword is provided. However, it does not explicitly mention when not to use it or compare with other 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?
No annotations provided, so the description carries full burden. It discloses the return structure, API endpoint, and that it returns a list. The read-only nature is clear, but it does not mention pagination behavior beyond the max_results parameter.
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. Every sentence 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?
Given the tool's simplicity (one optional parameter, no output schema), the description adequately covers the return structure, API endpoint, and use cases. No 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?
Schema description coverage is 100% for the single optional parameter max_results. The description adds no additional meaning beyond the schema's existing 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 retrieves all customers' store credit balances and details its usage for browsing, liability calculation, and identifying high-balance customers. It distinguishes from siblings like update_customer_store_credits.
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 specific use cases (e.g., calculating liabilities, finding high-balance customers) and implies it is for read-only purposes. However, it does not explicitly compare with other list tools or state when not to use.
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 details side effects such as coupon appearing in customer account, quantity limits, and irreversibility for some coupon types, and mentions the API endpoint 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with labeled sections (purpose, API, return, side effects) and is informative without being overly verbose. It is front-loaded with the core function.
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 complexity (one parameter, no output schema), the description covers purpose, usage context, API details, return structure, and side effects. It lacks explicit error handling details but is otherwise 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 coverage is 100%, so baseline is 3. The description does not add additional meaning to the 'coupon_data' parameter beyond the schema's description, which is already somewhat vague.
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 '發送優惠券給指定客戶' (sends coupons to specified customers) and specifies use cases like marketing campaigns and CRM triggers, distinguishing it from customer-initiated actions like claim_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 a ['用途'] section explaining when to use the tool (marketing, rewards, CRM), but does not explicitly state when not to use it or list alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description reveals important behavioral traits: message is final and cannot be retracted or modified, and rate limits apply for bulk sending. It lacks details on authentication or specific error conditions, but covers the main risks.
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), front-loaded with the write indication, and uses concise language without unnecessary repetition.
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 covers what the agent needs: purpose, usage scenarios, API endpoint, return structure, and important side effects. It is complete for a simple write tool with one parameter and no 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 description coverage for the single parameter 'message_data' is 100% (includes description and example). The tool description does not add additional explanation beyond what the schema provides, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies the verb '發送' (send) and the resource '一般商店對話訊息' (general store conversation message). It distinguishes from the sibling 'send_order_message' by stating it is for non-order-specific messages, providing clear 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 lists explicit use cases: marketing notifications, event announcements, proactive customer contact. It implies it should not be used for order-specific messages, with sibling 'send_order_message' serving that purpose. However, it does not include an explicit 'do not use when' 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?
The description explicitly lists side effects: quantity will be overwritten and changes take effect immediately. It also marks the operation as [WRITE]. Since no annotations are provided, this disclosure is valuable for the agent's understanding 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 well-structured with headings for purpose, API, return structure, and side effects. It is concise, containing only necessary information without extraneous details.
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 tool with no output schema, the description covers purpose, API endpoint, return structure (dict with fields), and side effects. This is sufficient for the agent to understand 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 coverage is 100% with clear parameter descriptions. The tool description adds no additional meaning to the parameters beyond what the schema already provides. 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 clearly states the tool's purpose: update addon product stock quantity by SKU. It specifies the verb (update), resource (addon product quantity), and indexing method (by SKU). The title and sibling tools confirm differentiation from other update quantity 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 provides a clear use case: '適合批次庫存同步場景' (suitable for batch inventory sync scenarios). However, it does not explicitly state when not to use this tool or compare it to similar siblings like 'update_addon_product_quantity'.
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 covers behavioral traits: it declares the operation as a write, lists side effects (immediate effect, new orders apply new rules, existing commissions unaffected), and explicitly states irreversibility with no version history. This goes beyond basic requirements.
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, side effects) and is front-loaded with the '[WRITE]' tag. While slightly verbose, every section provides necessary 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?
The description covers purpose, parameters, return structure (dict with success, resource_id, message), and side effects. No output schema exists, so the return structure description compensates. It lacks error handling or permission details, but overall is adequate for the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, and the description adds value by clarifying that 'campaign_data' should only include fields to modify ('僅傳入需修改的欄位'). This guidance helps the AI agent understand partial updates, enhancing the schema's 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 it updates an existing affiliate campaign, specifying the verb '修改' (modify) and resource '聯盟行銷活動' (affiliate campaign). It lists adjustable fields (commission ratio, period, conditions), which differentiates it from sibling tools like create_affiliate_campaign or delete_affiliate_campaign.
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 includes a '用途' section stating when to use the tool (to modify existing campaigns) and provides the underlying API call. However, it does not explicitly state when not to use it or mention alternative tools, leaving room for ambiguity in tool selection.
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 provided, so description carries full burden. Lists key side effects: immediate balance change, history logged, error if insufficient balance. Missing auth or rate limits, but sufficient for typical use.
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?
Well-structured with sections, front-loaded purpose. Includes API endpoint and return structure, which is informative but slightly verbose. Could be trimmed without losing 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?
No output schema, but description explains return dict. Covers side effects and parameter meaning. With 3 params and no nested objects, it is fairly complete. Could mention error responses in more detail.
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 well documented. Description adds value by explaining that positive amount adds and negative deducts, which is important for correct usage.
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 adjusts store credits with specific use cases (top-up, refund, gifts). Distinguishes from sibling tools like adjust_customer_member_points (different resource) and list_store_credits (read vs write).
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 context with example scenarios, but does not explicitly state when not to use or compare to alternatives. Good for a specific operation.
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 from the system, the description fully covers the write operation, confirms overwriting existing tags, lists API endpoints, and describes the response structure. However, it does not mention required permissions or rate limits, which would improve 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-structured with sections and front-loaded core information. It is not overly verbose, but the inclusion of specific API endpoints may be slightly extraneous for a tool description. Still, it remains 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?
Given no annotations or output schema, the description provides sufficient context: side effects, response structure, and usage guidance. It lacks details on error handling or constraints on tags (e.g., max length), but overall it's adequate for a simple write 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?
Input schema has 100% coverage with descriptions for both parameters. The description repeats the overwrite behavior for 'tags' and adds context like API endpoints and response format, but does not significantly enhance parameter meaning 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 sets customer tags by overwriting existing ones, with usage examples like marketing segmentation. It distinguishes itself from siblings like 'update_customer' by focusing specifically on tags and the overwrite behavior.
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 warns that tags overwrite all existing tags and advises using get_customer_profile to first retrieve existing tags if the goal is to add rather than replace. This provides clear guidance on when to use and an alternative approach.
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 fully carries the burden. It declares the tool as a write operation with [WRITE], lists side effects (immediate effect, may affect in-checkout consumers, irreversible without version history but can be overwritten), which 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-structured with sections (purpose, API call, return structure, side effects). It is concise, with no redundant information, and each section 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?
Given the tool's moderate complexity (2 parameters, no output schema, no annotations), the description covers all necessary aspects: purpose, usage, return format (dict with success, resource_id, message), API endpoint, and side effects. It is fully adequate for agent understanding.
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 both parameters. The description adds examples of updatable fields (e.g., discount, validity) and states that only modified fields should be sent, but this adds minimal value beyond the schema. The schema already provides the parameter meanings.
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 an existing promotion ('更新既有促銷活動') and provides examples of modifiable fields (discount, validity, conditions). It is distinct from sibling tools like create_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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for updating existing promotions via the [WRITE] tag and the phrase '修改已建立的促銷活動', but it lacks explicit guidance on when to use this tool versus alternatives (e.g., create_promotion for creation, delete_promotion for deletion). No exclusion or prerequisite information is provided.
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 provided, so description fully covers behavioral traits: permanent deletion, updates to product review counts and ratings, and partial failure scenarios. This is comprehensive for a destructive 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 clear sections (用途, API, 回傳結構, 副作用). It is informative but could be slightly more concise; every sentence serves a 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?
Given the simple input schema (one parameter) and no output schema, the description covers return structure (dict with success, resource_id, message, deleted_count) and side effects, making it complete for effective tool selection and 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 coverage is 100% with clear description and example for comment_ids. The description adds no additional parameter-specific 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 clearly states it batch deletes product reviews, with a verb (批次刪除) and specific resource (商品評論). It distinguishes from siblings like delete_product_review (single) and bulk_update_product_reviews (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 explicit use cases (batch cleanup of test data or violating reviews) and mentions partial failure behavior. However, it doesn't explicitly state when not to use or name alternatives, which would improve clarity.
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 that the product is immediately visible, potential errors on duplicates, and default status behavior. It also marks it as a write operation with '[WRITE]'. This provides adequate behavioral context for an agent to understand 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-structured into clear sections (用途, API call, return structure, side effects) with a front-loaded purpose. Every sentence serves a purpose, and 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.
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 provides the return structure and side effects. The single parameter with additionalProperties is explained with field suggestions. It could be more explicit about required fields within product_data, but the reference to the API spec is acceptable.
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 a single parameter 'product_data'. The description adds value by instructing that the object should be assembled according to the Shopline API spec and listing example fields (name, description, price, SKU). It also describes the return structure, which is absent from 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 verb '建立' (create) and resource '新商品' (new product), and the title 'create_product' distinguishes it from siblings like 'create_addon_product' 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?
The description explains that the tool is for creating a new product in the Shopline store, with details on the Shopline API endpoint and error conditions for duplicate SKU/barcode. However, it does not explicitly contrast with alternative tools or provide when-not-to-use guidance, but the purpose is clear enough for basic usage.
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, so description fully handles transparency. Declares it's a write operation, lists side effects (public/pending, affects average rating), and provides 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?
Well-structured with sections, front-loaded verb, no wasted words. Each section adds distinct value.
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?
Covers purpose, use cases, API, return structure, and side effects. Minor omission of error handling or rate limits, but sufficient for the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with an example description, but the tool description adds no further parameter explanation. Baseline score 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?
Clearly states it creates a single product review, with use cases provided. Distinguishes from bulk_create_product_reviews sibling.
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 for customer service and historical data import. Does not explicitly exclude alternatives, but 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 provided, so description carries full burden. It includes a '副作用' section detailing permanent deletion, irreversibility, and effects on affiliate links. This adequately discloses behavioral traits beyond the input schema.
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?
Well-structured with sections for operation type, usage, API, response, and side effects. Information is front-loaded. Could be slightly more concise, but adds useful context like return structure and API endpoint.
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 is a simple delete with one parameter, the description covers purpose, usage guidelines, side effects, API endpoint, and return structure. No output schema, but description compensates by listing return fields. Sibling tools provide 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?
Only one parameter (campaign_id) with 100% schema coverage. Description does not add meaning beyond the schema; it only includes the endpoint. Baseline score of 3 is appropriate as schema already documents 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?
Description clearly states '永久刪除指定的聯盟行銷活動' (permanently delete specified affiliate campaign), which is a specific verb+resource. It starts with '[WRITE]' and is distinct from sibling tools like create_affiliate_campaign, update_affiliate_campaign, get_affiliate_campaign_detail, 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 explains when to use the tool: '用於清除已結束、取消或錯誤建立的活動' (for clearing finished, cancelled, or incorrectly created campaigns). This provides clear context, though it does not explicitly state when not to use or mention 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?
Without annotations, the description fully covers behavioral traits: it's a write operation, permanent deletion, irreversible, with possible retention of order records. It also specifies the API endpoint 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with sections, front-loaded with [WRITE], and each part adds value. Slightly verbose for a simple tool, but no wasted 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?
No output schema is provided, but the description includes return structure and side effects. It covers purpose, usage, API, and consequences, making it fully sufficient for this simple 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 coverage is 100%, and the schema already describes customer_id as '客戶內部 ID'. The description does not add new semantics beyond that, 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 deletes a customer record from Shopline, with specific use cases (clearing test data, GDPR compliance). It uses a specific verb ('delete') and resource ('customer'), and distinguishes from siblings like create_customer and 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?
The description provides context on when to use (test data cleanup, GDPR) but does not explicitly state when not to use or compare directly with other delete tools. However, it is clear enough for the intended purpose.
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?
Without annotations, the description fully discloses permanent deletion, irreversibility, and automatic update of product review count and average rating. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with sections for purpose, usage, API call, return structure, and side effects. It is front-loaded and concise, though slightly repetitive in some parts.
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 covers all necessary aspects: action, use cases, API endpoint, return structure, and side effects. No output schema exists, but the return format is described. It is complete for a single-parameter delete 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 already provides 100% coverage with a clear description of the 'comment_id' parameter. The description adds no new semantic 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 states the tool deletes a single product review, specifies its use for removing violative, malicious, or test reviews, and distinguishes from bulk delete tools. The verb 'delete' and resource 'product review' are explicit.
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 (removing violative, malicious, or test reviews) and implicitly contrasts with bulk delete by specifying single review. However, it does not explicitly exclude other scenarios or mention prerequisites.
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?
Despite no annotations, the description is highly transparent: discloses permanent deletion, irreversibility, impact on discount codes, and that historical orders are unaffected. Also provides API endpoint 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with sections (purpose, API, return, side effects) and is concise. Minor fluff like the exact API endpoint could be omitted, but overall efficient.
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 param, no output schema), the description is complete: explains when to use, side effects, and return structure. No gaps for an AI agent to understand 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?
Only one parameter 'promotion_id' with schema description 'promotion ID'. Schema coverage is 100%, so baseline is 3. Description does not add additional semantic detail beyond what the schema 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 clearly states the tool permanently deletes a promotion, specifying the purpose (clear expired/test/incorrect activities). It distinguishes from sibling tools like create/update/list 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 'usually used to clear expired, test, or incorrectly created activities' provides clear context for when to use. No explicit alternatives are mentioned, but the purpose is well-defined.
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 provided, but description fully covers behavioral traits: it's a write operation, triggers customer notifications (depending on settings), requires shippable order state, and describes return structure (dict with success, resource_id, message). Discloses error condition for unshipable orders.
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, usage, API call, return structure, side effects. Every sentence provides value. No redundancy, and the information is front-loaded with the essential write indication 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?
For a simple write tool with one parameter and no output schema, the description covers return structure, side effects, and error conditions. Could mention potential partial shipment behavior or further constraints, but overall 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 clear description '訂單 ID'. Description does not add extra meaning beyond the schema, but given the single simple parameter, no additional context is needed. 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?
Description starts with [WRITE] and clearly states it marks an order as shipped and triggers the Shopline shipment process. It distinguishes itself from siblings like cancel_order, update_order_status, and bulk_execute_shipment by specifying single-order write 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?
Explicitly states applicability: '適用於倉庫確認出貨後的狀態更新' (after warehouse confirms shipment). It notes the order must be in a shippable state, which is a key guideline. However, it does not explicitly mention when not to use or compare to alternative tools like bulk_execute_shipment.
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 lists returned fields and mentions the API endpoint, indicating a read operation. However, it does not explicitly state read-only safety or potential errors, though the context suggests no 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-structured with sections for summary, usage, API, and return fields. It is concise, front-loaded, and every sentence is relevant.
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 lists return fields and the API endpoint. It lacks details on error handling or prerequisites beyond campaign_id, but for a single-item retrieval with one parameter, it is fairly 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 only parameter, campaign_id, has a description in the schema that explains it comes from list_flash_price_campaigns. This adds value beyond the schema, which already has high coverage, by providing a clear 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 retrieves complete details of a single flash price campaign, specifying fields like discount rules and time settings. It distinguishes itself from sibling tools such as list_flash_price_campaigns (listing) and update_flash_price_campaign (modification).
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 '用途' section explaining that the tool is suitable when the campaign_id is known and all fields are needed. While it doesn't explicitly mention when not to use it, the context and sibling list make the distinction 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?
No annotations are provided, so the description carries full burden. It states the HTTP method (GET), the specific endpoint, and the return structure with fields like merchant_id, scopes, expires_at. It implies a read-only operation without side effects, which is appropriate. Could be improved by explicitly stating there are no modifications 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with sections for purpose, usage, API call, and return. Each sentence adds value, though it could be slightly more concise. The use of line breaks and Chinese formatting is clear but not minimal.
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 absence of output schema and annotations, the description provides a complete picture: what the tool does, when to use it, the exact API endpoint, and the structure of the return value. The agent has sufficient information 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?
The input schema has zero parameters (100% coverage), so the description does not need to add parameter semantics. It correctly indicates no parameters are needed and instead focuses on the return value, which adds 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 explicitly states the tool retrieves current API token info and authorization scope, including merchant, scopes, and expiry. This is a specific verb-resource pair that clearly distinguishes it from sibling tools which focus on products, orders, 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 description includes a dedicated '用途' section explaining it is suitable for troubleshooting API access issues and confirming token permissions. While it does not explicitly mention when not to use or name alternatives, the context is clear given the absence of other token-related tools among siblings.
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 full responsibility for behavioral transparency. It discloses that the tool makes a GET request to '/v1/taxes' and returns a dict with 'total' and 'taxes' array. It lists key fields (id, name, rate, etc.). No destructive or side effects are implied, which is accurate. It does not contradict any annotations (none exist).
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 call, and return structure. It is concise and front-loaded with the core purpose. However, there is slight redundancy (e.g., '稅率清單' appears twice), and it could be slightly more compact.
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 that the tool has no parameters and no output schema, the description provides complete context. It explains the return structure in detail, listing the fields within each tax object. It also specifies the API endpoint. This is sufficient for an agent to understand the tool's behavior and 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 input schema has no parameters, so the description does not need to add parameter information. The description mentions the API endpoint and return structure, which is sufficient. According to the rubric, 0 parameters receives a baseline score of 4.
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 '取得' (get) and resource '稅率清單' (tax rate list). It distinguishes this tool from siblings by specifying it deals with tax rules, and no other sibling tool has a tax-related purpose. The inclusion of examples like '營業稅、消費稅' adds context.
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 guidance in the '【用途】' section, indicating when to use the tool (for viewing tax rules, confirming settings, financial analysis). However, it does not mention when not to use it or list alternatives, which would improve the score. Since there are no other tax-related siblings, the guidance is adequate.
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?
Discloses mutation behavior (WRITE), immediate effect, irreversibility (no version history), and ability to overwrite. With no annotations, this carries the full burden and does so well.
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 (type, purpose, API call, return structure, side effects). Each sentence is informative and concise, with 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?
Covers purpose, usage, API endpoint, return structure, and side effects. Lacks error scenarios but is sufficient for a mutation tool without output 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?
Schema description coverage is 100%, so baseline is 3. The description adds valuable guidance on partial update semantics (only modify passed fields), which goes beyond schema 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?
Clearly states it updates customer basic information (name, contact, birthday) and specifies the HTTP method and endpoint. Distinguishes from sibling tools like create_customer, delete_customer, and update_customer_tags.
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 states that only passed fields are updated and omitted fields are not overwritten. Provides context for usage but does not explicitly compare to other customer-update 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?
With no annotations present, the description fully carries the transparency burden. It marks the tool as [WRITE], lists side effects (immediate effect, irreversible but overwritable), and describes the return structure, providing comprehensive 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 concise, structured into labeled sections (purpose, usage, API, return, side effects), and every sentence serves a purpose. It is front-loaded with the [WRITE] tag and core action.
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 explanation covers purpose, effects, and return format, which is sufficient for a tool with 2 parameters and no prerequisites. It omits error handling and assumptions but remains largely complete for agent 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% already, but the description adds value by explaining that pickup_store_data includes fields like store_name, address, phone, and business_hours, giving context beyond the schema's generic 'object' type.
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 updates pickup store information for a delivery option, using the verb 'update' and specifying the resource '自取門市資訊' (pickup store info). No sibling tool has a similar purpose, making it uniquely identifiable.
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 indicates it is suitable when store information changes and syncs with Shopline settings. However, it does not specify when not to use this tool or suggest alternatives, leaving the agent without 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. It explicitly labels the tool as a write operation `[WRITE]`, details immediate effects, additive nature (not overwriting), and error handling for invalid IDs. It also describes the return structure, providing comprehensive behavioral insight.
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, use case, API, return structure, side effects). It is concise, front-loaded with the operation type, and 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?
Given the tool has 2 parameters, no output schema, and no annotations, the description provides a complete picture: purpose, usage, API endpoint, return structure, side effects, and error behavior. It enables an agent to use the tool correctly without additional 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?
Input schema has 100% coverage with descriptions for both parameters. The description reaffirms the parameter meanings (product ID list, category ID list) and adds context about additive behavior, but does not significantly extend 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 that the tool batch assigns multiple products to specified categories, using a specific verb and resource. It distinguishes itself from sibling tools like update_product or create_category by focusing on batch assignment.
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 typical use cases (new season listing, restructuring) and notes efficiency over per-product updates. It implicitly suggests when to use (batch) vs. single updates, but does not explicitly list alternatives or when not to use.
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 important behavioral traits: order status changes to cancelled, operation is irreversible, may fail if already shipped, and refund may be needed. This is comprehensive 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.
Conciseness4/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, side effects. It is moderately concise, though it could be slightly shorter. Every section adds value.
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 explains the return structure (dict with success, resource_id, message). It covers purpose, API endpoint, and side effects. It is mostly complete for a cancellation tool, though it could mention prerequisites like order status or permissions.
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 schema already documents both parameters. The description adds context by implying the required order_id and noting reason is optional. It also connects the parameters to the usage scenarios, providing added 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 '取消訂單' (cancel order) and lists specific use cases (customer request, insufficient stock, payment issues). It distinguishes itself from sibling tools by explicitly being a cancellation operation, which is unique among order-related 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 provides explicit scenarios for when to use the tool: customer request, insufficient stock, or payment issues. It also mentions side effects like irreversibility and potential failure if shipped. However, it does not explicitly state when not to use it or provide 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 fully covers behavioral traits: it's a write operation, adds a customer record, may fail on duplicate email/phone, and returns a structured response including success flag and resource ID.
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 with clear sections for purpose, usage, API details, return structure, and side effects. 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's complexity (6 parameters, no output schema, no annotations), the description provides purpose, side effects, return format, and constraints, making it sufficiently complete for an 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 coverage is 100%, so baseline is 3. The description does not add new information about parameters beyond the schema, although it hints at duplication constraints related to email and phone.
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 customer in Shopline, using a specific verb '建立' and resource '客戶記錄'. It distinguishes from sibling tools like update_customer or delete_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 mentions suitable scenarios (manual creation, batch import) and warns about potential duplicate failure. However, it does not explicitly advise when not to use it or suggest alternatives like update_customer for existing records.
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; description discloses side effects: adds promotion, immediate activation possible, mentions update alternative. Lacks permission or reversibility info but 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?
Well-organized with sections: WRITE mark, purpose, API, return structure, side effects. Every sentence adds value, 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?
Provides return structure and side effects. Single-parameter tool, so low complexity. Description is 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?
Only one parameter (promotion_data) with schema description in Chinese. Description adds context that it follows Shopline's object structure, aiding understanding beyond 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?
Explicitly states 'create new promotion activity' with examples (discount codes, BOGO). Distinguishes from update_promotion in side effects.
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?
Mentions API endpoint and side effects. Implicitly says use when needing a new promotion, and to modify use update_promotion. Could be more explicit about when not to use.
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 includes a dedicated '副作用' (side effects) section detailing that deletion is permanent, active campaigns cause instant price reversion, and historical orders are unaffected. This fully discloses behavioral traits.
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. It is concise with no unnecessary 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?
Despite having no output schema, the description includes the return structure. It covers the single required parameter, side effects, and usage context, making it complete for an agent to understand 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 coverage is 100% for the single parameter 'campaign_id', which already has a description. The description adds no additional parameter semantics beyond what is in the schema, so 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 clearly states the tool's purpose: '永久刪除指定的快閃價格活動' (permanently delete a flash price campaign). It differentiates from siblings like create, update, get, and list by specifying it is for 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 includes a usage context: '用於清除已結束、取消或錯誤建立的活動' (for clearing ended, canceled, or wrongly created campaigns). This provides guidance on when to use, though no alternative tools are explicitly mentioned.
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 permanent deletion, irreversibility, impact on product if sole variation, immediate frontend removal, API endpoint, and return structure. This exceeds typical transparency for a delete 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 (purpose, usage, API, return, side effects). It is concise with no unnecessary words, achieving a high signal-to-noise ratio.
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 tool with two parameters and no output schema, the description covers all necessary aspects: purpose, usage, side effects, API details, and return structure. Nothing essential 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 already describes both parameters (product_id, variation_id) with 'internal ID' descriptions. The description adds no additional semantic meaning beyond what the schema 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 clearly states 'delete product variation' and explains it permanently removes a specific variation from a product. It distinguishes itself from sibling tools like create_product_variation and 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?
It provides context on when to use (discontinuing specs, cleaning errors) and includes important side effects like irreversibility and product unpurchasability if sole variation. However, it does not explicitly compare to alternatives like updating variation to disabled.
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 provided, but description fully covers behavioral traits: permanent deletion (irreversible), write operation, and potential restriction if inbound executed. Includes side-effect section.
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 (type, purpose, API, return, side effects). Each sentence is informative and concise. 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 single-parameter tool with no output schema, the description provides return structure, side effects, and usage guidance. Parameter is fully described in schema. Complete for the complexity level.
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?
Only one parameter (purchase_order_ids) with schema description already covering its meaning. Description adds no extra semantics; baseline 3 due to 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?
Clearly states the tool deletes purchase orders in batch, with specific uses like cleaning test data or voiding erroneous orders. Differentiates from sibling tools such as create_purchase_order or list_purchase_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?
Provides context on when to use (cleaning test data, voiding errors) and notes a limitation (potential restriction if inbound executed). Does not explicitly compare to alternatives 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 provided, so description carries full burden. It discloses deprecation status and describes the response structure. Could mention authentication or side effects, but as a read-only operation, it is 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Text is front-loaded with purpose and uses clear sections (用途, 注意, API call, return structure). Concise but could be slightly more structured for readability.
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, description adequately explains return format and provides usage context and deprecation warning. Lacks some details on potential error cases or authorization, but sufficient 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.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has zero parameters, and schema coverage is 100%. Description adds no further parameter details, but none are needed. Baseline of 4 applies per rules.
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 retrieves store application settings, including feature toggles and theme settings. It is distinct from other get_* tools by focusing on app-level settings.
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 it is suitable for confirming feature enablement status and notes the endpoint is deprecated with a suggestion to prefer other settings endpoints. Provides clear 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, but the description discloses that the tool calls five Shopline APIs internally and returns a dict with specific data sections. It mentions amounts are floats in TWD. While it doesn't discuss rate limits or performance, the behavior is well-described for a read-only operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured with sections for purpose, usage, API calls, and return structure. It front-loads the key information and every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given there is no output schema, the description adequately explains the return structure (dict with five sections). It also lists the internal APIs called. The tool is read-only, and the description provides complete context for an AI agent to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There is only one parameter (customer_id) with a description in the schema that explains it's the internal ID from list_customers. The tool description does not add additional semantics beyond the schema. With 100% schema coverage, baseline is 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
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 single customer's complete profile including basic info and multiple data sections. It uses specific verbs ('取得') and lists the five sections. It distinguishes from the sibling get_rfm_analysis for batch analysis.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly provides usage context: answering questions about a customer's profile for customer service or individual analysis. It also directs to get_rfm_analysis for batch analysis, giving a clear when-to-use and when-not-to.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but description describes return structure comprehensively. It implies a read-only query operation, but does not explicitly state lack of side effects or permissions required.
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 sections for purpose, API call, and return fields. Every sentence is informative, and the format is clean and 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?
Given the tool has one parameter and no output schema, the description covers purpose, API endpoint, return structure, and use case. It is complete and self-contained.
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 has 100% coverage with a clear description linking subscription_id to the id field from list_product_subscriptions. Description mentions the parameter but adds marginal extra 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?
Description clearly states it retrieves complete details of a single product subscription, with specific fields listed. It distinguishes from sibling tools like list_product_subscriptions by focusing on a single record and providing full 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?
States use case is for customer service scenarios or individual subscription confirmation. Implicitly differentiates from listing tool but does not explicitly mention alternatives or when not to use.
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，但描述提供了足夠的行為資訊：呼叫 GET API，回傳 dict 包含特定欄位，暗示這是唯讀操作。缺少關於權限或速率限制的說明，但整體透明度良好。
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?
考慮到無輸出 schema，描述明確列出了回傳欄位；參數只有一個且已說明來源； siblings 眾多但描述指出與 list/search 搭配使用，情境完整。
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?
單一參數 promotion_id 在 scheme 中已有完整描述（從 list_promotions 或 search_promotions 取得），描述僅重複此訊息，未增加新意義。根據規則，schema_coverage 100% 時 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?
明確指出這個工具用來取得單一促銷活動的完整詳情，包括折扣規則、適用商品等。與 sibling tools（如 list_promotions, search_promotions）區分，因為它需要已知的 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 Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
描述中明確說明『適合在已知 promotion_id 的情況下取得所有欄位』，並暗示應先使用 list_promotions 或 search_promotions 取得 ID，提供了使用時機與前提。
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），描述承擔了行為透明度的全部責任。描述詳細說明了回傳結構，包含退貨單基本資訊、金額摘要及 line_items 的各欄位。說明了使用的 API（GET /v1/return_orders/{return_order_id}），但未提及權限或錯誤情況，不過對於取得細節工具而言已足夠。
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?
對於一個單一參數、無輸出 schema 的工具，描述已涵蓋所有必要資訊：明確指出功能、使用場合、API 路徑及回傳資料結構。缺乏輸出 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?
只有一個參數 return_order_id，且在 schema 中已有完整描述（來自 list_return_orders 的回傳 id）。描述中的「用途」段落額外提供了 ID 來源的上下文，增加了超過 schema 的價值。由於 schema_description_coverage 為 100%，基線為 3，描述貢獻了額外資訊，因此給 4 分。
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?
明確指出取得單一退貨單的完整明細，並列出包含所有退貨品項。與兄弟工具（如 list_return_orders、update_return_order）區分明確，且不同於其他 get_ 工具（如 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?
提供「用途」段落，說明查閱特定退貨申請的完整資訊，並列舉客服處理個案或審核退貨申請的使用情境。雖然未明確說明替代工具（如 list_return_orders），但給出了足夠的上下文指示何時使用。
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 fully discloses the algorithm, the condition threshold, and the rate limit constraint (analyzing only first 30 products). It also describes the 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 yet comprehensive, with clear sections for purpose, usage, API calls, and return structure. Every sentence provides 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?
Given the tool's complexity (multi-API calls), the description adequately explains the logic, limits, and output format, making it complete for an agent to understand and use 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 only parameter `min_stock_diff` is described in the schema, and the description adds context by explaining how it is used (difference >= threshold). This enhances understanding 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 generates cross-warehouse stock transfer suggestions with a specific condition (stock difference >= min_stock_diff) and a limit of 30 products. It distinguishes itself from related inventory 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 explains when to use the tool (to get transfer suggestions) and mentions its limitation of analyzing only 30 products. However, it lacks explicit guidance on when not to use it 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 bears full responsibility. It discloses the HTTP method (GET), potential 403/422 errors, and describes the response structure. However, it does not mention rate limits or clarify if disabled channels are included beyond noting '開啟的'.
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, 回傳結構). It is front-loaded and every sentence provides value, avoiding 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 covers purpose, usage context, limitations, response structure, and alternative data sources. It is complete 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.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters, so schema coverage is trivially 100%. Baseline for 0 parameters is 4. The description adds context about the response but no param info is 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 sales channels ('取得商店所有銷售渠道清單'), uses a specific verb and resource, and distinguishes from siblings like get_channel_detail and get_channel_comparison by emphasizing the list-all behavior.
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 explaining when to use (e.g., understanding multi-channel layout, pre-analysis). It mentions potential errors and an alternative source of channel info, but does not explicitly exclude scenarios or compare to sibling 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?
No annotations are provided, so the description carries the full burden. It discloses the API endpoint (GET /v1/custom_fields) and the return structure (dict with total and fields array, each field containing id, name, type, options). This is sufficient for a read-only operation with no 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-structured with distinct sections for purpose, usage, API call, and return structure. It is concise, using only necessary information without redundancy. Every 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?
For a tool with no parameters and no output schema, the description covers all essential aspects: purpose, usage context, API endpoint, and return format. It provides enough information for an agent to use the tool correctly 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 input schema has zero parameters, so schema coverage is 100%. According to guidelines, 0 parameters yields a baseline score of 4. The description adds no parameter details, but 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's purpose: retrieving the list of customer custom fields defined by the store. The verb '取得' (retrieve) and resource '客戶自訂欄位清單' (customer custom field list) are specific. While sibling tools include many 'list' tools, this one is uniquely about custom fields, distinguishing it from others.
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 usage section explaining when to use the tool (e.g., to view additional custom fields like birthday, preferences, notes) and its purpose in understanding customer data structure or completeness. It does not explicitly state when not to use it or mention alternatives, but the context is 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?
The description includes the API endpoint and return structure beyond the input schema, disclosing the response includes 'total' and 'merchants[]' with fields. No annotations are provided, so the description compensates with behavioral 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 sections like 【用途】, 【呼叫的 Shopline API】, 【回傳結構】, and is concise with no unnecessary 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 tool with no parameters and no output schema, the description fully compensates by explaining purpose, API endpoint, and response structure, making it 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 and schema coverage is 100%, so baseline is 4. The description adds value by detailing the response structure, which is not present 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 '取得所有商家清單' (list all merchants) and explains it is for viewing accessible merchant accounts, distinguishing it from sibling 'get_merchant_detail' which retrieves a single merchant.
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 multi-merchant environment to confirm operable scope). It does not explicitly mention when not to use or alternatives, but the context is 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?
No annotations are provided, so the description carries full burden. It discloses the API endpoint (GET), the return structure (dict with total_found, returned, reviews[]), and fields included. This sufficiently indicates a read-only operation, though it doesn't explicitly state it is non-destructive.
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 structured with clear sections (用途, 呼叫的 API, 回傳結構), is concise with no redundant sentences, and front-loads the purpose. Every 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?
Given the tool has only one optional parameter, no output schema, and no annotations, the description is complete: it explains purpose, usage guidelines, the API endpoint, and return structure. Nothing essential is missing for an AI agent to select and use 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 single parameter 'max_results' is already fully described in the input schema with default and description. The description does not add additional semantics beyond what the schema 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 clearly states it returns a summary list of product reviews, with verb '取得' and resource '商品評價列表'. It distinguishes itself from the sibling get_product_review_detail by specifying that this tool provides a summary list and the other provides full detail.
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 this tool: for monitoring review quality, finding low-rated products, tracking recent reviews. It also directly says to use get_product_review_detail for full content, providing clear when-not-to-use 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 return format (dict with total_found, returned, return_orders array with fields) and implies read-only behavior. However, it does not explicitly mention side effects, rate limits, or pagination behavior beyond the max_results parameter.
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 endpoint, and return structure. It is concise and front-loaded with essential information, with no unnecessary 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?
Given the tool has 3 parameters, no output schema, and no annotations, the description provides complete context: it explains the tool's purpose, how to use it, what the output structure looks like, and how it relates to sibling tools. No gaps remain.
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 documents all three parameters. The description confirms the date range filtering but does not add new semantic meaning beyond what the schema provides. 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 lists return orders filtered by date range, specifies the purpose (querying return orders over a period), and distinguishes from similar tools like get_return_order_detail (for full item details) and get_refund_summary (for aggregated analysis). It uses a specific verb and resource.
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 guides when to use this tool vs alternatives: it advises using get_return_order_detail for detailed item breakdown and notes that get_refund_summary serves an aggregated purpose. This provides clear usage context.
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 provided, so description carries full burden. It discloses that changes take effect immediately, are irreversible, but can be overwritten. Also marks as [WRITE].
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 headings and bullet points. Every sentence adds value: purpose, usage, API, return structure, side effects. No waste.
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 2 params and no output schema, the description covers all necessary aspects: purpose, usage, behavioral traits, return structure, and side effects. Complete for an update 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 coverage is 100%, so baseline is 3. Description mentions possible fields (name, quantity, image) but does not add significant new meaning beyond 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 updates gift data, listing specific fields like name, quantity, and image. It distinguishes from sibling tools such as update_gift_quantity_by_sku, which only updates 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?
Provides clear usage: only pass fields to modify. Does not explicitly state when not to use or compare with alternatives, but context implies it is the general gift update 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?
No annotations provided, so the description fully covers behavioral traits: declares [WRITE] operation, immediate irreversible changes (overwritable), potential field restrictions based on order status, and provides API call and return structure. This exceeds 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 structured with clear sections ([WRITE], purpose, API, return, side effects), uses bullet points for readability, and is concise without redundancy. Every 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?
Given no output schema, the description explains return structure (success, resource_id, message). It covers side effects, partial update behavior, and field restrictions. For a simple update tool, this is 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?
Schema coverage is 100%, so baseline is 3. The description adds partial usage guidance (only modified fields) but repeats schema descriptions. It does not elaborate on order_id or the nested object format beyond what's 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 explicitly states it updates order editable fields (notes, shipping address) and emphasizes partial update behavior. It distinguishes from sibling tools like update_order_status and update_order_delivery by focusing on general field modification.
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: modify editable order fields. While it does not explicitly list exclusions or alternatives, the sibling tool list implies that status/delivery updates have separate tools. A slightly higher score would require explicit when-not-to-use 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 provided, but description discloses side effects: immediate update, affects frontend availability, setting to 0 with no overselling shows out of stock. Also mentions API endpoint. Could mention permissions or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Structured with sections and bullet points. Concise but covers purpose, usage, API, return, side effects. Slightly verbose but 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?
No output schema, but description explains return structure and side effects. Missing error conditions, but adequate for a simple update 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 coverage 100%, description adds value by clarifying that quantity is absolute (非增減量), which is not in 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?
Clearly states it updates stock quantity for non-variant products, with specific verb '更新庫存數量' and resource '無變體商品'. Distinguishes from sibling tool 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?
Explicitly says when to use (庫存調整, 手動補貨) and when not (if product has variants, use update_variation_quantity). Provides clear 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?
Discloses that changes take effect immediately, average rating updates if rating changes, and operation is irreversible but can be overwritten. Provides sufficient behavioral insight for a mutation tool without 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?
Description is well-structured with sections (purpose, API, return, side effects). Every sentence is informative and concise. 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?
Covers return structure (dict with success, resource_id, message), side effects, and usage context. For a simple single-update tool with 2 parameters and no output schema, the description is complete and 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?
Schema coverage is 100% and description adds value beyond schema by listing example updatable fields (status, content, rating) and providing a sample for review_data. Parameter descriptions are clear.
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?
Starts with '[WRITE]' and clearly states '更新單筆商品評論' (update a single product review). Lists specific purposes: modifying content, status, rating. Distinct from sibling tools like create_product_review, delete_product_review, and 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?
Explicitly states usage context: '適用於客服審核或編輯不當評論' (suitable for customer service review or editing inappropriate comments). Implicitly distinguishes from bulk vs single updates but does not explicitly mention when not to use or list 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 fully discloses behavior: it is a WRITE operation, immediate price update, frontend sync, and no impact on existing orders. Also provides HTTP method and endpoint.
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?
Concise with clear sections (WRITE, usage, API endpoint, return structure, side effects). Every sentence adds value, and the structure 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?
Despite no output schema, the description includes return structure and side effects. For a simple price update tool with 3 parameters (all described), it is completely 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 coverage is 100%, so parameters are well-described in the schema. The description adds no additional parameter meaning beyond what schema provides, meeting 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?
Description clearly states it updates the selling price of a specific product variation, using the verb 'update' and specifying the resource. It distinguishes from sibling tools like update_product_price (which updates main product price) and 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 Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides usage context, stating it is suitable for individual price adjustments and limited-time offers. However, it does not explicitly mention when not to use it or list alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully bears the burden of disclosure. It clearly states side effects: images are appended, become immediately visible, require publicly accessible URLs, and are subject to store plan limits. This provides 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.
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 efficient but could be slightly more concise; however, the structure aids 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?
The description is thorough: it explains the return structure (dict with success, resource_id, message, images) despite no output schema, covers side effects, and constraints. For a tool with two parameters and straightforward behavior, it provides complete 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 input schema has 100% coverage with descriptions for both parameters. The description adds value by clarifying that image_urls must be publicly accessible and that images are appended to existing ones, enhancing understanding 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 purpose with a [WRITE] tag and explicit Chinese explanation '為商品新增圖片' (add images to product), and specifies that it uploads image URLs to the product album, appending them. This distinguishes it from sibling tools like delete_product_images.
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 '用途' (usage) section stating it is suitable for adding product display images and context images. It provides the specific API endpoint but does not explicitly mention when not to use or compare to alternatives like delete_product_images.
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 behavior: it is a write operation (marked [WRITE]), lists side effects (adding a record, potential idempotency issues), and provides the API endpoint. It also details the return structure. This is thorough behavioral 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-structured with sections for purpose, API, return, and side effects. It is concise yet comprehensive, though slightly verbose compared to an ideal minimal description. Each section 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?
Given no output schema, the description adequately explains the return structure. It covers all essential aspects: purpose, API endpoint, input example, side effects, and behavior on duplicates. For a single-parameter tool, it is complete and leaves no significant 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% coverage with a description that includes an example. The description further adds context by explaining the purpose of the metafield data and the importance of the namespace+key combination, which goes beyond the schema's basic 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 explicitly states the tool creates app metafields for merchants, specifying the resource and action. It distinguishes itself from other create tools by focusing on metafields and mentioning namespace and key, which is unique to this tool.
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 usage section explaining when to create metafields for storing app settings. It also warns about potential failure or overwrite if the same namespace+key exists, providing guidance on constraints. However, it does not explicitly compare to other tools 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.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description fully bears the burden. It discloses that the tool calls different API endpoints depending on the search condition and describes the return structure in detail. This goes 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections and uses bullet points. It is slightly longer than necessary but every sentence adds value. It is front-loaded with 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?
Given the tool's simplicity (2 optional parameters, no output schema), the description is complete. It covers API endpoints, return structure, and usage context without any 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%, providing a baseline of 3. The description adds value by explaining the conditional API endpoint behavior based on 'search_keyword', which is not captured in the schema. This enhances 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 purpose: to list or search customer groups. It distinguishes from sibling tools like list_customers by focusing on groups. The verb '取得' (get) and resource '客戶群組列表' (customer group list) are specific.
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: confirming group strategies and obtaining group IDs for further queries. However, it lacks guidance on when not to use this tool or 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?
No annotations provided, but the description clearly lists side effects: coupon marked as used (irreversible), records written affecting reports. This provides essential behavioral transparency for an irreversible 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 like [WRITE], 【用途】, 【呼叫的 Shopline API】, 【回傳結構】, 【副作用】. It is informative but slightly verbose, though all content is relevant.
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 includes return structure (dict with success, resource_id, etc.) and covers purpose, API endpoint, side effects, and usage scenario. It is comprehensive for a simple coupon redemption 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 'coupon_data' has a description that adds meaning: '通常包含 coupon_code 與訂單或客戶識別資訊' (typically includes coupon code and order/customer ID). While the schema coverage is 100%, the description provides useful context beyond the type 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 starts with '[WRITE] 核銷（使用）優惠券', clearly indicating it's a write operation to redeem a coupon. It specifies the verb and resource, and distinguishes from sibling 'claim_coupon' which is a different 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 states when to use: '在結帳或特定場景下核銷優惠券' (during checkout or specific scenarios). It does not explicitly mention when not to use or alternatives, but the context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses key behaviors: immediate effect on active campaigns, irreversibility (無版本歷史), and the API endpoint. This meets the transparency burden comprehensively.
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, 回傳結構, 副作用), each sentence adding unique value. No 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 2-parameter tool with no output schema or annotations, the description covers API endpoint, return structure, and side effects. Missing error handling or permission details, but sufficient for the complexity.
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 descriptions for both parameters. The description adds the nuance that campaign_data should only include fields to modify (partial update), 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 it updates a flash price campaign (修改已建立的快閃價格活動). The [WRITE] prefix and sibling tools (create_flash_price_campaign, delete_flash_price_campaign, etc.) distinguish it effectively.
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 concrete examples (adjusting price, time period, product scope) and implies usage context. It does not explicitly exclude scenarios or mention alternatives, but the purpose 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?
With no annotations, the description fully discloses the write operation, overwrite side effect, return structure, and API endpoint. It is thorough and transparent about all behavioral aspects.
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 and uses efficient language. However, it contains some redundancy (e.g., repeating the overwrite mention) and could be slightly more concise. Still highly readable.
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 two parameters, the description covers purpose, usage, side effects, return structure, and alternative approach. It is fully self-contained 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?
Input schema has 100% coverage with descriptions for both parameters. The description adds minimal additional meaning beyond restating the overwrite behavior already implied by tag field description. 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 sets order tags by overwriting existing ones, and provides usage scenarios. It effectively distinguishes from siblings like get_order_tags by emphasizing the overwrite behavior.
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 mentions that it overwrites all existing tags, and gives specific guidance on how to add tags instead of overwriting by using get_order_detail first. This provides clear when-to-use and when-to-avoid instructions.
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?
Even without annotations, the description fully discloses the tool's behavior: it calls POST /v1/media, lists side effects (adds record, consumes storage), and describes the return structure. The note about the JSON body limitation adds transparency about potential failure modes.
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, front-loads the action and purpose, and includes necessary details without excessive verbosity. Slight redundancy exists between the schema description and the note, but overall efficient.
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 provides the return structure and side effects, making it complete for an upload tool with one parameter. It covers the essential aspects needed for correct invocation and understanding of consequences.
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% description coverage with a good explanation of the param (media_data). The description adds value by explaining the return structure and the possible formats (file_url or base64) beyond what the schema says, as well as the multipart workaround.
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 action ([WRITE]) and resource (upload media files to Shopline media library), explains the purpose of obtaining a media ID for product images, and distinguishes it from sibling tools like add_product_images by specifying it uploads to the media library.
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 note about the multipart requirement and a workaround if the API returns a format error, offering guidance on when the tool might fail and how to handle it. It does not explicitly compare to other tools, but the sibling list shows no direct alternative for uploading media.
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 fully covers behavioral aspects. It states it is a write operation, describes the API endpoint, return structure (dict with success, resource_id, message, category), and side effects (adds a new category record). It also notes a potential error condition.
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 call, return structure, and side effects. It is concise yet informative, with 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?
Given the tool's complexity (one parameter, simple create action), the description is complete. It covers the operation, API details, return format, side effects, and an edge case. No output schema exists, but the return structure is described well enough.
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 one parameter with a description and example. The description adds value by explaining the structure and providing an example JSON. Schema coverage is 100%, so baseline is 3, but the extra example and explanation justify a 4.
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 that the tool creates a new product category in Shopline, with an option to specify a parent category for hierarchy. This clearly defines the action and resource, distinguishing it from other tools like update_category or 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?
The description provides clear usage context: it is for creating a new category. It also warns about potential error if parent_id does not exist. However, it doesn't explicitly contrast with siblings like 'bulk_assign_categories', but the purpose is well-defined.
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, description carries full burden. It discloses side effects: variation is immediately added and available on frontend, and potential error on duplicate SKU. It also specifies the exact API endpoint (POST /v1/products/{product_id}/variations) and return structure (success, resource_id, message, variation).
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 labeled sections (用途, API, 回傳結構, 副作用). The [WRITE] tag front-loads the operation type. Every sentence provides necessary information without repetition.
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, description provides complete return structure. It covers purpose, usage, API details, side effects, and parameter assembly guidance. For a creation tool with nested parameters, this is comprehensive.
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 clear descriptions. Description adds value by stating variation_data should follow Shopline Open API spec, providing context beyond schema. However, it does not detail the nested structure of variation_data.
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 tool creates a new product variation under an existing product, using specific verbs ('新增變體'). It specifies the resource (product) and the action (create variation), and distinguishes from sibling tools like update_product_variation and delete_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?
Description explains when to use: to add new specification variations (color, size) to an existing product. It provides context on how to assemble variation_data according to API specs. However, it does not explicitly state when not to use or compare with 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?
Describes return structure in detail (total, tree[], flat[], node fields) and the API call. While no annotations exist, the description effectively communicates the read-only nature and output format, though it could mention any rate limits or authentication needs.
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 (main purpose, usage, API, return structure). Every sentence adds value, 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's simplicity (no parameters, no output schema), the description covers all necessary aspects: purpose, usage guidance, API reference, and return format. No 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?
No parameters exist, so schema coverage is 100%. The description adds value by explaining the return structure beyond what the schema provides, including the distinction between tree and flat arrays.
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 all product categories and composes a tree structure, with explicit usage purpose of browsing the complete category hierarchy. It differentiates from sibling tools like get_category_detail.
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: confirms category IDs and names, then can be used with get_category_detail for details or with product tools for filtering. Also mentions the underlying API endpoint.
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 provided, so description carries full burden. It explicitly lists side effects: quantity overwritten, changes immediate. Also describes return structure, providing full 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?
Description is well-structured with sections (WRITE tag, purpose, usage, API, return, side effects). Every sentence adds 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?
Given no output schema, description provides return structure. Side effects and API call are documented. Complete for a simple update tool with two params.
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 both parameters, but description adds key info: 'new quantity (absolute, not difference)'. This adds important semantic context 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 updates addon product inventory quantity by ID. It includes '[WRITE]' and specifies the API endpoint, distinguishing it from siblings like update_addon_product_quantity_by_sku which updates 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 explains the use case (direct ID-based update with absolute quantity) and implies when to use. It does not explicitly state when not to use or mention alternatives, but the context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully covers behavior: it notes the underlying API endpoint, return structure (dict with success, resource_id, message), and side effects (immediate effect, affects front-end, not reversible but can be overwritten).
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, uses brackets for key information, and every sentence is necessary and informative without being 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?
Given the tool's complexity and lack of output schema, the description is complete: it covers input, API, return, side effects, and distinguishes from create/delete tools, meeting all informational needs.
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 description adds value by explaining the partial update semantics and providing an example input for category_data, which is more informative than 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 it is a WRITE operation to update product category data, and it distinguishes itself from siblings like create_category and delete_category by focusing on 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?
It explains that the tool is for modifying category attributes (name, sorting, parent) and emphasizes partial updates. However, it does not explicitly state when not to use it or mention alternatives, though the sibling list provides context.
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, description carries full burden: lists side effects (immediate effect, customer visibility, irreversibility), API method, and return structure. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear sections: purpose, usage, API, return, side effects. Front-loaded and every sentence adds value. 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?
Complete for a simple update tool: covers purpose, behavior, return structure, side effects, and partial update. No missing critical 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. Description adds value by reinforcing partial update and listing typical fields (name, email, phone, address), aiding understanding beyond 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?
Clearly states it updates basic merchant data (name, contact info, address) with '[WRITE] 更新商家基本資料.' Distinguishes from sibling tools by focusing on merchant settings. Includes partial update behavior.
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 context: '適合商家資料異動（如搬遷、更名）時同步更新 Shopline 商家設定.' and explains partial update. Lacks explicit when-not-to-use or alternatives, but sufficient for common use.
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 covers behavioral traits: it's a WRITE operation, changes take immediate effect, may trigger automatic customer notifications, and is irreversible but can be overwritten. It also details the API endpoint 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 well-structured with headers for purpose, usage, API, return structure, and side effects. It is concise (approx. 100 words) and front-loaded with [WRITE] tag for quick identification. Every section adds meaningful 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?
Given the complexity (nested object, no output schema, no annotations), the description is remarkably complete. It explains the return structure (dict with success, resource_id, message) and side effects, leaving no obvious gaps for an agent to use this 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%, so baseline is 3. The description adds value by providing concrete examples of fields (tracking_number, carrier, status) and explaining the purpose of delivery_data as logistics info, which helps agents understand what to populate.
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 updates order delivery logistics info (tracking number, carrier, status). It uses a clear verb '更新' and resource '訂單配送資訊'. The context of integrating third-party logistics systems distinguishes it from sibling tools like update_order or update_order_status.
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 use case: '適合整合第三方物流系統後回寫配送狀態' (suitable for writing back delivery status after integrating third-party logistics). While it doesn't explicitly exclude other scenarios or compare with alternatives like execute_order_shipment, the usage 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?
With no annotations provided, the description fully discloses behavioral traits: immediate status changes affecting frontend and reports, potential customer notifications, and error conditions for invalid values or transitions. It also explains the separate API calls per parameter.
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, 回傳結構, 副作用). Each sentence adds value, and the text is concise yet comprehensive, front-loading the 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?
Given no output schema, the description provides the return structure (dict with success, resource_id, message, updated_fields). It also explains side effects and error conditions, making it complete for a tool with 4 parameters (1 required).
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 covers all parameters (100% coverage). The description adds operational context: 'only pass non-None parameters' and that each non-None parameter triggers a separate API call, which enhances understanding beyond the schema 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 specifies the tool's function: updating order statuses (main, delivery, payment) simultaneously. It uses a '[WRITE]' prefix and explains that only non-None parameters are processed, distinguishing it from sibling tools like cancel_order or update_order which handle other 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 provides clear context: use when updating one or more status fields, and only pass non-None parameters. It does not explicitly mention when not to use or contrast with alternatives, but the detailed side effects and API calls offer sufficient 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?
Describes side effects: changes immediate, irreversible, no version history. Specifies API endpoint (PUT /v1/products/{product_id}) and return structure. Despite no annotations, description fully discloses behavioral traits.
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-organized with sections: purpose, usage, API info, return structure, side effects. No redundant sentences. Front-loaded key 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?
Despite no output schema, description includes return structure (dict with success, resource_id, message). Covers side effects and irreversibility. Complete for a mutation 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 coverage is 100% with descriptions for both parameters. Description adds value by explaining that product_data requires only fields to update, and explicitly lists return structure fields not in 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?
Description clearly states it updates basic product info (name, description, category, status) using [WRITE] prefix. Distinguishes from siblings like update_product_price and update_product_quantity by specifying scope of 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?
Provides clear use case: modify existing product fields. Includes partial update hint ('only pass fields to modify, others unchanged'). However, does not explicitly exclude alternative tools like update_product_price.
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 specifies that the update is immediate and affects front-end display, and states that in-progress orders are unaffected. It also mentions the API endpoint and return structure, offering comprehensive behavioral insights.
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 (purpose, usage, API, return, side effects). It is concise yet informative, with no wasted words. The [WRITE] tag front-loads the action 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?
For a simple tool with 2 parameters and no output schema, the description covers all necessary context: purpose, usage scenarios, alternative tool, API details, return structure, and side effects. It is complete 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 has 100% coverage with descriptions for both parameters. The description adds minimal extra meaning beyond the schema; it mainly reinforces the schema's information. 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 verb (update) and resource (selling price of non-variant products). It distinguishes itself from sibling update_variation_price by explicitly specifying it's for non-variant products, providing a specific 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?
Provides explicit when-to-use (direct price setting, price adjustment, promotion end) and when-not-to-use (if product has variants, use update_variation_price). This gives clear context for agent selection.
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 provided, so description carries the full burden. It discloses the overwrite behavior (destructive), return structure (dict with success, resource_id, message), and side effects. Could mention permissions or product existence requirement, but 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?
Well-structured with sections, front-loaded with key behavior (overwrite), concise with no unnecessary text. Every 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?
Given the simple tool (2 params, no output schema, no enums), the description is fully sufficient: explains purpose, behavior, side effects, and provides a usage scenario. No 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% with descriptions. The description adds value by reiterating that tags will replace existing ones, which is critical for correct usage. Baseline is 3 due to high coverage; extra point for the overwrite 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 explicitly states it sets product tags and overwrites existing ones, using specific verb and resource. It distinguishes from siblings like 'update_product' and 'get_product_list' by focusing on tags.
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 when-to-use (setting tags for grouping, promotion, SEO) and when-not-to-use (to add tags without overwriting), with explicit alternative: first use get_product_list to retrieve existing tags and merge.
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情況下揭露充分行為特徵。
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?
無輸出schema，但描述中說明了回傳結構（dict含success、resource_id、message）。包含API端點、副作用等，對一個變更工具而言足夠完整。
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%，描述中提供return_order_data範例('{"status": "approved", "note": "已確認退款"}')，增加了實例說明，超越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?
描述以[WRITE]開頭明確指出為寫入操作，說明更新退貨單狀態或資料，並舉例審核狀態、退款金額、備註等，適用於客服審核流程。與sibling tools如create_return_order、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?
提供用途說明，指出適用於修改審核狀態、退款金額等，隱含用於更新而非其他操作。未明確列出不適用情境，但上下文清晰。
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?
Discloses the underlying API endpoints used depending on search conditions (GET /v1/customers vs GET /v1/customers/search). Describes the return structure including fields like total_found, returned, customers[] with id, name, etc. No contradictions since no annotations are provided.
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?
Well-structured with distinct sections for purpose, usage, API calls, and return structure. Content is front-loaded and efficient, though including API endpoints and return structure may be slightly verbose but adds utility.
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 compensates by detailing the return structure and API behavior. It also mentions the alternative tool for complete profiles, making it complete for a list 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 coverage is 100% so baseline is 3. The description adds value by explaining the search_keyword triggers a different API endpoint and clarifies the return structure, providing context beyond the schema's parameter 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 retrieves a customer list with keyword search support. It distinguishes itself from get_customer_profile by noting that tool provides full details including store credit, points, and tier.
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 this tool (querying specific customers or browsing the list) and when to use the alternative get_customer_profile for complete individual data. Provides clear search capabilities by name, email, or phone.
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?
Despite no annotations, the description discloses immediate update effects on front-end purchasable quantities, possible skipping of non-existent SKUs, and a recommendation to verify SKUs before execution. This covers key behavioral traits beyond the write nature.
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, but includes some extraneous details like the exact API endpoint (PUT /v1/products/bulk-update-quantities) which may not be necessary for an agent. Still, it remains clear and 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 no output schema, the description includes the return structure (dict with success, resource_id, message, updated_count). It also covers side effects and preparation advice. For a write tool with one parameter, this is thorough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description adds meaningful semantics: it explains the 'updates' parameter as a list of objects with 'sku' and 'quantity' fields, and that SKU identifies the product/variant. This goes beyond the schema's minimal 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: batch updating inventory quantities for multiple SKUs. It uses the specific verb '批次更新' (batch update) and resource '庫存數量' (inventory quantities), and distinguishes itself from sibling tools like update_product_quantity and update_variation_quantity by highlighting batch efficiency.
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 provides usage scenarios ('適用於盤點後大批調整、進貨入庫等場景') and compares with individual update tools, stating when to use this batch tool for efficiency. No exclusions given, but sufficient context.
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, but the description fully compensates by detailing side effects (immediate update, frontend impact, out-of-stock behavior) and the API endpoint. This covers all behavioral aspects an agent needs.
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 (title, usage, API, return structure, side effects). It is concise yet comprehensive, with no unnecessary 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?
Given no output schema, the description includes the return structure (dict with success, resource_id, message) and side effects. Combined with full schema parameter coverage, the description is complete for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
While schema coverage is 100%, the description adds value by clarifying that quantity is an absolute value ('新庫存數量（絕對值，非增減量）') and by explaining the return structure. This provides extra meaning 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 starts with a clear verb and resource ('[WRITE] 更新商品變體庫存數量'), explicitly stating it updates a variation's quantity. It distinguishes from sibling tool bulk_update_quantities, making the purpose specific.
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 states when to use (after stocktaking or manual restock) and explicitly mentions the alternative for batch updates (bulk_update_quantities), providing clear usage guidance.
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:

[![mcp-shopline MCP server](https://glama.ai/mcp/servers/asgard-ai-platform/mcp-shopline/badges/card.svg)](https://glama.ai/mcp/servers/asgard-ai-platform/mcp-shopline)

Score Badge

Copy to your README.md:

[![mcp-shopline MCP server](https://glama.ai/mcp/servers/asgard-ai-platform/mcp-shopline/badges/score.svg)](https://glama.ai/mcp/servers/asgard-ai-platform/mcp-shopline)

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/asgard-ai-platform/mcp-shopline'

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