sapo-mcp

Server Quality Checklist

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

Latest release: v0.7.1
Disambiguation5/5
Each tool targets a distinct resource and action, with clear separation between list, search, count, and get variants. Even similar tools like search_products vs list_products are differentiated by their query parameters.
Naming Consistency5/5
All tool names follow a consistent verb_noun pattern in snake_case, including compound nouns like customer_address and order_transaction. There is no mixing of camelCase or other styles.
Tool Count2/5
With 46 tools, this exceeds the 25-tool threshold for 'too many,' even though the tools are organized by domain. The count is inflated by multiple list/search/count variants and separate address/province helpers, but the sheer volume makes it heavy.
Completeness3/5
The set covers many workflows (customers, orders, fulfillments, draft orders, discounts), but product management lacks create/update/delete, and there are no delete operations for customers or addresses, or create for refunds. These are notable gaps for a commerce platform.
Average 4.1/5 across 46 of 46 tools scored. Lowest: 3.4/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 0 commits in the last 12 weeks
- Last stable release on April 30, 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

Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full burden. It discloses that the response includes variants, options, and images, which is useful. However, it does not mention error behavior, permissions, or that it is read-only (though the verb 'Get' implies no side effects). Sufficient for a simple read tool but could be richer.
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 wasted words. The essential verb and resource are front-loaded, and the included related data is listed efficiently. Perfectly 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?
For a simple one-parameter read tool with no output schema, the description covers the main function and return contents. It does not explain return format or error cases, but with such a low complexity, it is mostly complete. Sibling tools like list_products are not referenced, but this is not critical for a basic get-by-ID operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully describes the only parameter, product_id, with 'Product ID (numeric). Required.' (100% coverage). The description 'by ID' adds no new meaning beyond the schema. Baseline of 3 is appropriate since schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get a single product by ID' with a specific verb and resource, and adds that it includes variants, options, and images. It distinguishes from list/search products, though it doesn't explicitly name alternatives like get_order. This is clear but not maximally differentiated.
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 list_products or search_products. The description implies use when you have a specific product ID, but does not state exclusions or preferences. This is a clear 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 provided, so the description carries the full burden of disclosing behavior. It states 'Count total customers' and 'optionally filtered by creation date,' but it does not explicitly say what it returns (e.g., an integer count), nor does it mention any edge cases such as whether deleted customers are included or how date boundaries are handled. For a read-only count, this is a notable gap in return-value 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 a single, concise sentence that front-loads the core purpose and includes the key optional filter. Every word contributes value; no fluff or redundant phrasing.
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?
This is a simple tool with two optional parameters, full schema coverage, and no output schema or annotations. The description covers the purpose and filter, but lacks an explicit statement about the return value (e.g., 'Returns the total number of customers'). Given the low complexity, it is adequate but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for both parameters (created_on_max and created_on_min), so the schema already documents their meaning. The description does add the context that these filter by 'creation date,' which maps directly to the parameters, but it does not add details beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Count total customers in the store.' It uses a specific verb ('count') and resource ('customers'), making it distinct from other customer tools like list_customers, get_customer, and search_customers. The optional filter by creation date is also mentioned, adding precision.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage: use when you need a total count of customers, optionally within a date range. However, it does not explicitly compare with alternatives like count_products or count_orders, nor does it provide when-not-to-use guidance. The intended use is fairly obvious from the wording, but no explicit guidance is given.
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 of behavioral disclosure. It only states that it returns available + committed quantities; it does not mention pagination behavior, performance implications of unfiltered calls, authentication requirements, or any side effects. For a read operation, the lack of caveats about large result sets or required filters is a notable 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 two concise sentences that front-load the core purpose and immediately follow with the key filtering guidance. Every word earns its place; there is no fluff or repetition of schema details. This is an ideal length and structure for a tool description.
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 there is no output schema and no annotations, the description should provide more context about expected return behavior and limitations. It does state the main return content (available + committed quantities) but does not mention that it returns a list, that unfiltered queries may return large volumes, or that pagination is available (only in schema). While not severely incomplete, it leaves the agent with some uncertainty about edge cases.
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 clarifying that location_id and inventory_item_id can be used together ('or both'), which is not explicitly stated in the schema's individual parameter descriptions. This gives the agent a better understanding of how to combine filters, going 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 specific action ('Get inventory levels'), the resource ('available + committed quantities'), and the scope ('for specific variants at specific locations'). It also mentions the key filters, making it distinct from sibling tools like get_variant or get_product. This is a strong, specific purpose statement.
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 by stating it gets inventory for specific variants/locations and says 'Filter by location_id, inventory_item_id, or both.' However, it does not explicitly state when to prefer this tool over alternatives (though no sibling seems focused on inventory) or provide any exclusions or prerequisites. The guidance is minimal and mostly about filtering, not overall usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It mentions 'Returns paginated results' and the endpoint, which adds some transparency. However, it does not disclose whether the operation is read-only, authorization requirements, or how multiple filters interact, leaving gaps for an agent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, with the main purpose front-loaded and no redundant information. Each sentence serves a purpose: clarifying search criteria and explaining endpoint behavior and output pagination.
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 is moderately complex with four optional parameters and no output schema. The description covers the searchable fields and pagination, but omits important context such as how multiple filters are combined (AND/OR), whether partial matches are supported, and the absence of an explicit read-only guarantee. This 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?
The input schema provides detailed descriptions for all four parameters, giving 100% coverage. The description only restates the search fields (name, email, phone) without adding new meaning beyond the schema, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches orders by name, email, or phone, which is a specific verb-resource combination. It distinguishes itself from list_orders (listing all) and get_order (fetching a single order) by explicitly naming the searchable fields.
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 by framing it as a search tool with filter parameters, but it does not explicitly state when to use it versus alternatives or provide exclusions. The phrase 'Uses filter params on the orders list endpoint' gives context but no direct 'use when' 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?
With no annotations provided, the description carries the full burden. It implies a read-only operation via the verb 'count', which is inherently non-destructive, but it does not disclose any additional behavioral traits such as the return value format (e.g., whether it returns just an integer) or whether the count reflects real-time data. This is a minimal but acceptable level of transparency for a simple count tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence (12 words) that directly states the action and parameters. Every word contributes value, and there is no redundant or irrelevant content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple count tool with 3 optional parameters and no output schema, the description adequately covers the core function and filter options. It would benefit from explicitly stating the return value (e.g., 'returns the number of products'), but the tool's name makes this obvious. It is sufficiently complete for an agent to select and 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?
Schema description coverage is 100%, so the baseline is 3. The description reiterates that filters are optional and lists the parameter names, but it does not enrich the semantics beyond the schema. For example, it does not clarify whether filters are combined with AND/OR or how matching works for vendor and product_type. The added 'total products' hints at default behavior, but this is marginal.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Count' and a resource 'products in the store', clearly distinguishing this from sibling count tools like count_orders and count_customers. It also lists optional filters (status, vendor, product_type), which aligns with the schema. This is unambiguous and specific.
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 should be used when a count is needed, but it does not explicitly contrast with list_products or search_products, which are sibling tools. There is no stated 'when not to use' or alternative recommendations. The context is clear but not fully explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the behavioral burden. It transparently discloses that this tool creates a Transaction record and may change order financial_status, which are key side effects. However, it does not mention error scenarios, prerequisites (e.g., parent_id for certain kinds), or return behavior, 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 three short sentences, front-loaded with the core purpose, followed by side effect and allowed kinds. The kind enumeration is somewhat redundant with the schema, but the overall structure is efficient and free of fluff. It could omit the repeated enum to be even more concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has six parameters, no annotations, and no output schema. The description explains the primary side effect and allowed kinds, but lacks details on what the response contains, prerequisites for certain kinds (beyond schema), or failure modes. For a mutation tool with non-trivial side effects, this is adequate but not complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters. The description only repeats the kind enum values already present in the schema and adds minimal new meaning; the side effect note is behavioral rather than parameter-specific. This matches the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the action: 'Create a transaction for an order' with specific kinds (capture, sale, refund). It also distinguishes itself from sibling list tools like list_order_transactions by focusing on creation, and from update_order by targeting transaction records and financial status.
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 through the kinds (authorization, capture, sale, void, refund) and the side effect on financial_status, but it does not explicitly state when to use this tool versus alternatives or provide exclusion conditions. No direct comparison with sibling tools like update_order or create_fulfillment 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 are provided, so the description carries the full burden. It discloses the response contents ('Returns full draft order including line_items, customer, address, and applied discounts') but does not explicitly confirm read-only behavior, error handling, or permissions. 'Get' implies non-mutating, but more transparency 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 a single sentence that states the purpose and key return information. It is concise, front-loaded, and every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple getter with 1 parameter and no output schema, the description covers the essential return contents ('line_items, customer, address, and applied discounts'). It does not mention error behavior or explicitly state read-only, but overall it is sufficient for a tool of this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%: the only parameter, draft_order_id, is already described as 'Draft order ID (numeric). Required.' The description adds no extra semantic meaning beyond what the schema provides, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get a single draft order by ID' uses a specific verb and resource, clearly distinguishing it from siblings like list_draft_orders (plural) and get_order (regular orders). It states exactly what it does.
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 you have a specific draft order ID), but it does not explicitly mention alternatives or when-not-to-use. There is no comparison to list_draft_orders or get_order, so guidance is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It states the return behavior ('Returns full refund record') but does not disclose potential errors, authentication needs, or explicitly confirm read-only nature. For a simple get operation, 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with no wasted words. Each sentence adds value: what the tool does and what it returns.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is sufficient for a simple get-by-ID tool, especially with a complete schema and sibling context. It notes the return type ('full refund record') despite no output schema. However, it could mention that both order_id and refund_id are required, but the schema covers that.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds no extra parameter detail, but the schema fully documents order_id and refund_id. The description's vague 'by ID' is clarified by the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool gets a single refund by ID and returns the full record, distinguishing it from list_refunds. 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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when a specific refund ID is known, but does not explicitly mention alternatives like list_refunds or provide when-not-to-use guidance. The 'by ID' phrasing gives an implied context.
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 transparency burden. It clearly implies a read-only listing operation and highlights key returned fields, but it does not describe pagination behavior, response shape, or edge cases, which would be valuable for an agent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is concise and front-loaded. It communicates the action, resource, and key output fields without unnecessary words or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter list tool, the description sufficiently covers purpose and key returned fields. However, since there is no output schema or annotations, mentioning pagination or the exact result shape would make it more complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides descriptions for both customer_id and limit, covering 100% of parameters. The description adds no parameter-specific details beyond what the schema already documents, so it stays at the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'List' and clearly identifies the resource as 'saved addresses for a customer'. Mentioning the default address flag and Vietnamese province/district/ward fields adds useful specificity and distinguishes this tool from sibling address-mutation tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description conveys the basic use case—listing a customer's saved addresses—but it does not explicitly compare against alternatives like update_customer_address or set_default_customer_address, nor does it state when not to use this tool. Usage is implied rather than clearly guided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses the return content (tracking info, line_items, delivery status), which is valuable behavioral info. However, it omits potential caveats like pagination, ordering, or filtering behavior, so it provides only moderate transparency for a list 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 extremely concise: two sentences, front-loaded with the core purpose, and no extraneous information. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter list tool without an output schema, the description covers the essential return details and required input. It lacks any mention of pagination or potential edge cases, preventing a perfect score, but it is sufficiently complete for basic agent use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with order_id fully described in the schema. The description adds no additional parameter semantics beyond what the schema already states. Baseline of 3 is appropriate because the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action and resource: 'List all fulfillments for a specific order' uses a specific verb and object. It distinguishes from siblings like get_fulfillment (single fulfillment) and create_fulfillment (write) by emphasizing 'all fulfillments' scoped to a specific order.
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 through the phrase 'for a specific order' but does not explicitly contrast with get_fulfillment or other sibling tools. No clear exclusions or when-not-to-use guidance is provided, making the usage guidance merely implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the behavioral disclosure burden. It does disclose that the tool returns full refund records with transactions, line items, and adjustments, which is useful. However, it does not explicitly state read-only semantics, pagination, or permission requirements, though the verb 'list' implies a safe read 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—two sentences, front-loaded with the main action, and free of redundant details. 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?
Given this is a simple 1-parameter list tool with no output schema, the description adequately explains the scope and return content. It could mention pagination or limits, but for a straightforward list-refunds operation, it is sufficiently complete for an agent to select and invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the parameter is already documented. The description adds minimal value beyond the schema, only reiterating that the order_id is required and the purpose. It does not introduce new syntax or additional meaning 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 lists refunds for a specific order, using a specific verb and resource. It distinguishes from sibling tools like get_refund (single refund) and list_order_transactions (transactions only) by specifying full refund records and associated data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by requiring an order_id, but it does not explicitly compare with alternatives or state when not to use it. Context is clear that it is an order-scoped list operation, but no explicit exclusions or alternative tool recommendations are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It does disclose that it returns a paginated list and that matching applies to email, phone, or name, which is useful. However, it omits details like ordering, case sensitivity, or whether matching is partial or exact, leaving some ambiguity.
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 of 11 words, front-loaded with the action and target, and includes essential details (matching fields, pagination). There is no filler or repetition, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 parameters, no output schema), the description provides sufficient context: what it searches and that results are paginated. It does not explain return fields, but for a customer search this is likely inferable. It is complete for basic usage, though slightly more detail could enhance 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?
Schema coverage is 100%, so the baseline is 3. The description adds no new parameter meaning beyond the schema; the statement about matching email/phone/name is redundant with the query parameter's schema description. No additional insight is provided for the limit 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 uses the specific verb 'search' with the target 'customers', and clarifies the matching scope ('email, phone, name'), distinguishing it from list_customers and search_orders. This clearly articulates what the tool does and differentiates it from related sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you need to find customers by a query string, but it does not explicitly state when to prefer this over alternatives like list_customers or get_customer. There is no mention of exclusions or alternative tools, so guidance is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavior on its own. It states the effect (marks address as default) and the return value (the address now marked default), which is useful. However, it does not mention side effects (e.g., previous default being unset), permission requirements, or error behavior, leaving some gaps 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 two short sentences with no filler. It front-loads the core action and then gives the endpoint and return value. Every word earns its place, making it highly efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter mutation tool, the description is complete: it explains what happens (sets default), shows the endpoint, and tells the caller what to expect in the response. With no output schema, the explicit return statement fully covers the success response. The tool's simplicity means no additional context is necessary.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides full coverage (100%) with descriptions for both customer_id and address_id. The description adds a minor bit of context by showing how they appear in the endpoint URL, but it does not enrich the semantic meaning beyond what the schema already offers. 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 specific action: 'Set a customer's default address' via a dedicated endpoint. It identifies the resource (customer address) and the precise operation (mark as default), distinguishing it from sibling tools like update_customer_address or add_customer_address.
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 this is the right tool for setting a default address (calling it 'Sapo's dedicated endpoint'), but it does not explicitly compare to alternatives or state when not to use it. No explicit 'use this instead of X' guidance is given, leaving the agent to infer from 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It clearly states this is a read-only counting operation, describes optional filters, and specifies the return shape. For a simple tool, this is adequate, though it could mention edge cases like deleted orders or permission requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence that front-loads the core purpose ('Count total orders') and efficiently specifies the optional filters and return format. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (no required params, no output schema), and the description explains the return shape. It is mostly complete, but could benefit from a brief note on when to prefer this over list/search siblings, and it doesn't address potential filtering nuances. Still, it's sufficient for basic 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?
The input schema fully documents all 4 parameters with descriptions and enums (100% coverage). The description adds no additional parameter meaning beyond what the schema already provides, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action (counting) and resource (orders), and the return format '{ count: N }' distinguishes it from sibling tools like list_orders or search_orders that return order objects. It 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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use it (when you need a count rather than a list of orders) but does not explicitly mention alternatives or provide exclusions. It lacks the guidance seen in higher-scoring tools that say 'use X instead of Y'.
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 burden. It discloses the side effect (creates a customer-applicable code) and the uniqueness constraint, which is useful. However, it omits other behavioral details such as auth requirements, idempotency, or error handling, making it adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the primary action, and every sentence earns its place. No redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (2 params, no nested objects) and the description covers purpose, side effect, and a constraint. Without an output schema, it could mention return value, but the missing detail is minor given the simplicity and clear sibling context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers both parameters with descriptions and 100% coverage, so the description adds little beyond restating the uniqueness constraint already in the schema. Baseline 3 is appropriate given high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Create' with the resource 'discount code for a price rule', and distinguishes it from sibling tools like create_price_rule. The side effect explanation ('customers can apply at checkout') further clarifies the tool's unique role.
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 the prerequisite of an existing price rule ('for a price rule') and the uniqueness requirement, giving clear context. It does not explicitly exclude alternatives or mention when not to use it, but the context is sufficient for a simple create 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?
No annotations are provided, so the description carries the full burden. It explicitly discloses the key side effect: 'creates a Fulfillment record and marks specified line_items as fulfilled.' This is valuable behavioral context beyond the schema, though it could also mention return value or prerequisites.
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: the first states the purpose, the second states side effects. No filler, front-loaded with the primary 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 description covers purpose and side effects, and the schema handles parameter details. However, since there is no output schema, the description does not explain the return value (e.g., the created fulfillment object), which is a minor gap for a creation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all six parameters clearly. The description adds only a high-level summary ('optionally specifying line items and tracking info') without deeper semantic details, meeting the baseline for schema-covered params.
Input schemas describe structure but not intent. Descriptions should explain non-obvious 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 ('Create a fulfillment for an order') and scopes it with optional line items and tracking info. It distinguishes from sibling tools like update_fulfillment_tracking and get_fulfillment 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 usage is implied by the action verb 'create' and the resource 'fulfillment'. It does not explicitly mention alternatives or exclusions (e.g., 'use update_fulfillment_tracking for updates'), but the context makes it clear this tool is for the creation scenario.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description discloses the side effect and highlights a critical value format requirement. Could enrich with permission needs or activation behavior, but it addresses the core mutation 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?
Two concise sentences front-load purpose and side effect, then highlight key constraints. No wasteful prose; every sentence carries 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?
Given full schema coverage and no output schema, the description covers purpose, side effect, and required fields. It lacks return-value details but that's not required here; overall adequate 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 description coverage is 100%, so the description adds little beyond schema details. It reiterates the value format and required fields, but these are already documented 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?
Clearly states the action ('Create') and resource ('price rule'), with a helpful side-effect note ('creates a PriceRule record'). Distinguishes from sibling tools like update_price_rule and list_price_rules.
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?
No explicit when-to-use or alternative guidance. The purpose is obvious from the name and description, but lacks contextual cues about when to choose this over other price rule operations.
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 implies a read-only operation via 'Get' and discloses the included address list and order count. However, it does not describe error behavior, permissions, or any constraints. For a simple read tool, this is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loaded with the verb and resource, and includes relevant detail about returned data. Every word earns its place, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With one parameter, no annotations, and no output schema, the description explains the key return aspects (address list and order count), which is enough for a simple get tool. It doesn't cover error handling or edge cases, but the low complexity makes this acceptable. Overall, it is complete enough for the tool's scope.
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 'Customer ID (numeric). Required.' The description simply says 'by ID' without adding format, examples, or extra meaning beyond the schema. Since schema coverage is high, the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' with the resource 'single customer by ID' and specifies the included data (address list and order count). This distinguishes it from sibling tools like list_customers (multiple customers) and list_customer_addresses (addresses only).
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: it is for retrieving a single customer with related data. However, it does not explicitly name alternatives or when-not-to-use scenarios, even though siblings like list_customer_addresses exist. This is clear context without exclusions, so a 4 is appropriate.
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. The verb 'get' implies read-only behavior, but the description does not explicitly state that there are no side effects, nor does it mention error handling or authentication. It does disclose the return contents, which adds some 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 concise, consisting of two sentences that front-load the core purpose and then enumerate the included fields. Every word earns its place, with no unnecessary filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read operation with one parameter and no output schema, the description provides adequate context by listing the major components of the returned order. It does not cover error cases or authentication, but these are not critical for such a straightforward tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% coverage for the single parameter (order_id), including its type and required status. The description only repeats 'by ID,' adding no additional 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 the tool's purpose: 'Get a single order by ID.' It specifies the resource (order) and the exact identifier (ID), and lists the returned details, which distinguishes it from sibling tools like list_orders and search_orders.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the usage context: use when you have a specific order ID and need full details. However, it does not explicitly mention alternatives or exclusions, so it falls short of a full 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden of behavioral disclosure. It does add value by specifying the response contents (value_type, value, IDs, usage stats), which is helpful. However, it does not mention error behavior (e.g., 404 if not found), permissions, or side effects, leaving some transparency 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 two sentences, front-loaded with the core action ('Get a single price rule by ID'), followed by concise return details. There is no redundant information or filler, making it highly efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple tool (one parameter, no output schema), the description provides enough context about the operation and the returned data. It is mostly complete, though it could mention what happens if the ID does not exist. Still, it is sufficiently complete for an AI 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?
The input schema already provides 100% coverage for the single parameter (price_rule_id) with a clear description. The tool description adds no additional parameter-level meaning beyond the schema, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb and resource: 'Get a single price rule by ID.' This distinguishes it from siblings like list_price_rules (which lists multiple) and create/update_price_rule, making the tool's purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies when to use this tool: when you have a specific price_rule_id and need full details. However, it does not explicitly mention alternatives (e.g., 'use list_price_rules to get all rules'), so it falls short of a 5. Still, the context is clear with no exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of behavioral disclosure. It adds pagination behavior via the since_id cursor, which is non-obvious and valuable. It does not explicitly state read-only/no side-effects, but 'List' strongly implies it, and the pagination detail is the main behavioral nuance.
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 short, focused sentences convey purpose and pagination with no redundancy. Every word adds value, and the structure is clean.
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, the description covers the core purpose and pagination. It lacks an explicit note about choosing this over list_orders and does not describe the return shape, but that is partially mitigated by the schema and the straightforward nature of a list operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already describes all three parameters accurately, including the cursor behavior of since_id. The description adds no new parameter-level detail beyond what the schema provides, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Uses a specific verb ('List') and resource ('orders placed by a specific customer'), immediately distinguishing it from general tools like list_orders. The customer-specific scope is explicit and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies this is for retrieving orders for a specific customer, giving context for when to use it. However, it provides no explicit alternatives or when-not-to-use guidance, especially with sibling tools like list_orders and search_orders present.
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 discloses that this is a read operation (list), paginated via since_id cursor, and requires price_rule_id. It doesn't describe return format or edge cases, but for a simple list operation this is adequate but minimal.
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, front-loaded with the core purpose, no redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple list nature, no annotations, and no output schema, the description covers purpose, prerequisite, and pagination. It's complete enough for the tool's complexity, though it doesn't describe the shape of returned items.
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 all parameters with descriptions (100% coverage), so baseline is 3. The description adds the context that since_id drives cursor pagination and price_rule_id is mandatory, but these are already in the schema, so minimal added semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'list' with the resource 'discount codes' scoped to 'a specific price rule', clearly distinguishing it from sibling tools like create_discount_code or list_price_rules.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
States a clear prerequisite ('Must provide price_rule_id') and indicates the pagination context, but doesn't explicitly name alternatives or when-not-to-use, so it's clear context without exclusionary guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and does well: it discloses paginated results, the since_id cursor mechanism, the has_more flag, and the instruction to call again with next_since_id. 'List' also implies read-only. It does not go into rate limits, ordering, or auth, but the key behavioral trait (multi-page iteration) is explicitly covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose ('List draft orders with optional filters') and consists of four short, dense sentences. There is no fluff or redundancy; every sentence provides actionable information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a listing tool with no output schema, the description adequately covers the essential use cases: what it lists, optional filters, and the complete pagination protocol (has_more, next_since_id). The main gaps are the response structure of individual draft orders and explicit differentiation from sibling `list_orders`, but the description is substantially complete for driving 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?
Schema description coverage is 100%, so the schema already documents all three parameters (limit, status, since_id) with meaningful descriptions. The tool description adds only marginal value by referencing the pagination loop ('call again with next_since_id'), which is primarily a behavioral note rather than new parameter semantics. 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 uses a specific verb+resource ('List draft orders') with optional filters, clearly distinguishing this from siblings like `list_orders` (regular orders), `get_draft_order` (single fetch), and `create_draft_order` (mutation). The scope 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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear operational context (optional filters, status filtering, pagination loop with has_more/next_since_id), which implies when to use the tool. However, it does not explicitly contrast with alternatives such as `list_orders` for regular orders or `get_draft_order` for a single record, so exclusions are absent.
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. It discloses pagination behavior via since_id and the status filter values, which is useful. However, it does not mention ordering, default limit (though schema does), response shape, or potential side effects (none expected). It is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two clear, front-loaded sentences with no filler. The first sentence states the purpose, the second adds pagination and filter details. Every word contributes.
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 operation with three optional parameters and no output schema, the description covers the essential semantics: what it lists, how to filter, and pagination. It stops short of explicitly stating that it is a read-only operation, which is implied by 'List,' but otherwise it is complete for an AI agent to use it 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 description coverage is 100%, so baseline is 3. The description adds minimal context by explaining that since_id is used for cursor pagination, which reinforces the schema's own parameter description. It does not add significant extra meaning beyond what is already 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 clearly identifies the verb ('List') and resource ('price rules'), and even clarifies that 'price rules' are 'discount rules.' It distinguishes from sibling tools like get_price_rule (single) and create/update_price_rule by focusing on listing with optional filters.
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 this is the tool for listing all price rules with optional filters, and the sibling list includes alternate tools for single-rule retrieval or mutation. It does not explicitly state when not to use it, 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It mentions the side effect of modifying draft order fields and the status restriction, but omits other behavioral nuances such as error handling, permission requirements, or the fact that line_items replaces all existing items (though that is in the schema).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise and front-loaded: two sentences that state the primary action, the side effect, and a key restriction. Every sentence adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the lack of annotations and output schema, the description covers the essential operational context: status restriction and mutation side effect. The full parameter details are in the schema, so the description does not need to repeat them. It is sufficiently complete for an update operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema provides full parameter semantics. The description adds no additional parameter-level context, which is acceptable but also the reason for 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: updating a draft order, with a specific status constraint ('open' status). It also distinguishes itself from related draft order tools by explicitly stating that completed or cancelled drafts cannot be updated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear usage condition (only 'open' drafts) and an exclusion ('cannot update completed or cancelled drafts'). It does not name alternative tools explicitly, but the context is sufficient for an agent to know when this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 mutating effect ('modifies the price rule'), specifies partial-update semantics ('Only provided fields are updated'), and adds a constraint that 'value must remain a string if updating.' These go beyond what the input schema alone conveys and help the agent understand non-obvious behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short but contains redundancy: 'Update an existing price rule' and 'Side effect: modifies the price rule' essentially repeat the same idea. The note about 'value' is placed awkwardly at the end. While it is front-loaded with the purpose, the redundant sentence reduces overall clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 8 parameters fully documented in the schema and no output schema, the description covers the key behavioral aspects: targeting an existing rule, partial updates, and the value type constraint. It doesn't mention return values, but that would be standard for an update operation and is not required here.
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 clarifying that only provided fields are updated (partial update), which affects how parameters should be interpreted, and explicitly notes that the 'value' parameter must remain a string—a detail not fully emphasized in 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 states 'Update an existing price rule,' identifying the action (update) and resource (price rule). This distinguishes it from sibling tools like create_price_rule, get_price_rule, and list_price_rules, as the verb and 'existing' scope are explicitly different.
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 updating already-created price rules via the word 'existing,' and notes that only provided fields are updated. However, it does not explicitly mention when to use this versus alternatives (e.g., create_price_rule for new rules) or provide any exclusions, so guidance is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 key behaviors: the requirement for email/phone, optional inline address creation, and that the response includes the auto-generated id. It does not discuss error cases or idempotency, but the most important side effects and return behavior are covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loaded with the purpose, and contains no redundant information. Every sentence earns its place by adding a constraint, an optional feature, or return behavior.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a create operation with no output schema and no annotations, the description covers the essential aspects: purpose, required input condition, optional nested feature, and return value. The rich schema for addresses compensates for lack of detail there, though some parameter nuances remain undocumented.
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 only 45%, so the description must add meaning. It does add a critical constraint (email OR phone) that is not reflected in the schema's required fields, and clarifies the addresses array. However, it does not elaborate on most other parameters, leaving significant gaps that the schema only partially fills.
Input schemas describe structure but not intent. Descriptions should explain non-obvious 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 begins with 'Create a new customer,' a specific verb and resource that clearly distinguishes it from update_customer and read-only customer tools. It unambiguously states the action and object.
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?
Clear context is provided: this tool is for creating new customers, with a mandatory condition of email or phone. It does not explicitly name alternatives like update_customer, but the context is unambiguous and no exclusions are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It explicitly discloses the side effect (DraftOrder in 'open' status) and clarifies the requirement for item types, which goes beyond the obvious 'create' action. It does not cover permissions, error behavior, or reversibility, but the core transactional side effect is transparently stated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the primary action, and each sentence carries essential information (side effect and prerequisite). No fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a create tool with nested objects and no output schema, the description covers the core behavior and a critical requirement. The schema handles parameter details adequately. A minor gap is not mentioning what the tool returns (e.g., the created draft order), but this is not essential and the description is otherwise 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?
Schema coverage is 100% with each parameter described, so baseline is 3. The description adds value by imposing a cross-parameter constraint: at least one line_item must contain variant_id or title+price for custom items. This clarifies the relationship between parameters that the schema alone does not convey.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear verb+resource ('Create a new draft order'), which precisely states the tool's action. It also distinguishes itself from sibling draft-order tools (list, get, update, complete, send invoice) by being the creation function, and adds a useful side-effect detail (status 'open').
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 a key prerequisite: 'Requires at least one line_item with variant_id or title+price for custom items.' This gives a concrete condition for use. However, it does not explicitly mention when to prefer this tool over alternatives (e.g., for updating vs. creating) or any exclusion cases, so guidance is only partial.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses that the tool returns 'full fulfillment' with specific fields, which goes beyond the name. While it does not mention error handling or authentication, the read-only nature is implied by 'Get', and for a simple fetch this is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single efficient sentence that front-loads the core action and follows with useful return details. Every word contributes value, with no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get-by-ID tool with one parameter and no output schema, the description adequately conveys purpose and return contents. It could be slightly more complete by explicitly noting it only returns one fulfillment and not a list, but overall it provides sufficient context for an agent to select and invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% since the only parameter, fulfillment_id, is described as 'Fulfillment ID (numeric). Required.' The description adds no additional meaning beyond the schema's clarification of the parameter, so it meets the baseline without enhancing parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get a single fulfillment by ID' with a specific verb and resource, distinguishing it from sibling tools like list_fulfillments_for_order. It also specifies the return contents (tracking info, line_items, origin address), making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies the tool is for retrieving a single fulfillment when its ID is known. However, it does not explicitly mention alternatives such as list_fulfillments_for_order for listing fulfillments, nor does it state exclusions, so it lacks 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?
With no annotations, the description carries the full burden. It transparently discloses the return fields (price, SKU, barcode, inventory quantity, option values) and the price format (VND, float with 4 decimals). It does not mention error behavior, but for a simple getter this is a solid 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 and front-loaded, using two sentences with no redundant information. It immediately states the action and then lists the returned data efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter getter with no output schema, the description covers the essential behavior and return values. It could mention what happens if the variant is not found, but overall it provides enough context for correct invocation and result interpretation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides full coverage (100%) for the only parameter, variant_id, with a clear description. The tool description adds 'by ID' but doesn't enrich the parameter semantics beyond what the schema already states. 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 'Get a single product variant by ID' with a specific verb and resource. It distinguishes itself from sibling tools like 'list_variants_for_product' by indicating it retrieves exactly one variant by its identifier, not a list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description makes the usage context clear: use this when you need a single variant by its ID. It does not explicitly mention alternatives or when not to use it, but the 'single... by ID' wording provides enough guidance to select it over 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?
With no annotations provided, the description carries the burden of disclosing behavior. It clearly explains the cursor-based pagination pattern and how to continue fetching results, which is a non-obvious behavioral trait. It doesn't explicitly state that it's a read-only operation, but 'list' implies safety.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exactly two sentences: the first states the purpose and filters, the second explains pagination. It is front-loaded, efficient, and contains no unnecessary 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?
Despite having 6 optional parameters and no output schema, the description addresses the most critical non-obvious detail: cursor pagination. It doesn't describe the customer object structure, but that is a minor omission given the tool's self-explanatory nature and the comprehensive schema parameter descriptions.
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 each parameter having a detailed description (e.g., since_id: 'Return customers with ID greater than this value (cursor pagination)'). The description adds no additional meaning beyond reinforcing the cursor loop, 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 'List customers with optional filters', identifying the specific action and resource. It distinguishes itself from siblings like get_customer (single customer), search_customers (search), and list_customer_addresses (addresses). The verb 'list' plus resource 'customers' 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 provides clear pagination guidance: 'If has_more=true, call again with next_since_id.' This tells the agent exactly how to handle multi-page responses. However, it does not explicitly state when to use this tool over alternatives like search_customers, so it 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?
With no annotations provided, the description carries the full burden. It discloses the types of data returned (payment attempts, captures, refunds, voids), which informs the agent about expected output. It does not mention pagination or auth requirements, but for a read-only list operation, the behavioral disclosure is reasonably complete.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the action and resource, and the second sentence adds valuable detail about return contents. No superfluous words, earning a top score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given one required parameter and no output schema, the description adequately explains the purpose and return types. It could mention response format or ordering, but for a simple list tool, the provided information is sufficient for correct 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 schema already covers the only parameter (order_id) with a clear description and required flag. The tool description adds no additional semantic detail 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 identifies the action (List all transactions), the resource (specific order), and enumerates the transaction types included (payment attempts, captures, refunds, voids). This distinguishes it from sibling tools like list_fulfillments_for_order and list_refunds by emphasizing comprehensiveness.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: use this tool when needing all transactions for a specific order. It does not explicitly mention alternatives or exclusions, but the phrase 'for a specific order' and the focus on transaction types imply its appropriate use case.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses pagination via since_id cursor and hints at the response contents (SKUs, prices, inventory quantities), adding 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no fluff. The first sentence states the core purpose, and the second adds a key behavioral detail. The description is front-loaded and every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with 3 parameters and full schema coverage, the description provides enough context: what it returns and pagination behavior. It lacks explicit mention of response structure, but no output schema exists, so description is 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 the baseline is 3. The description does not add additional parameter semantics; all parameters are already described in the schema. It references since_id but only in the context of pagination, not adding new 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 uses a specific verb ('List') and resource ('variants for a product'), clearly stating what it returns (SKUs, prices in VND, inventory quantities). This distinguishes it from sibling tools like get_variant or list_products.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The context is clear: use when you need to list all variants for a given product. It does not explicitly name alternatives or state when not to use it, but the scope is well understood from the description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the transparency burden. It discloses that it uses the title filter on the list endpoint and returns paginated results, giving the agent behavioral expectations. It does not elaborate on sorting defaults or error cases, but for a read-only search tool this is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three short sentences, each adding information: purpose, implementation method, and return behavior. No filler 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 the simple search tool with fully documented parameters and no output schema, the description adequately covers the main function and return behavior. It does not describe the exact structure of returned items, but the agent can infer that it returns product objects and can use get_product for details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description repeats the 'substring' behavior but does not add any new parameter information beyond what the schema already provides for title, limit, and status.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function as searching products by title substring, using the active verb 'Search' and specific resource 'products'. This distinguishes it from sibling tools like list_products and get_product.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear context for when to use: searching by title substring. It also mentions it uses the title filter on the list endpoint, implying that unfiltered listing would use list_products. However, it does not explicitly name alternative 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full transparency burden. It explicitly discloses the side effect of modifying tracking_company, tracking_number, or tracking_url. However, it does not mention other side effects like customer notifications (notify_customer) or partial-update behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two short sentences, front-loading the action and immediately clarifying the side effect. No unnecessary words or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple, the schema covers all parameters, and the description covers purpose and side effects. It could mention that only provided fields are updated or that notify_customer triggers a customer email, but these are already in the schema, making the description largely complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds minimal meaning beyond the schema, only naming the tracking fields but not elaborating on fulfillment_id or notify_customer beyond their existing 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 uses a specific verb ('Update') and resource ('tracking information for an existing fulfillment'), and explicitly lists the fields modified (tracking_company, tracking_number, tracking_url), clearly distinguishing it from sibling tools like get_fulfillment or create_fulfillment.
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?
Clear context is provided: this tool updates an existing fulfillment's tracking info. However, there are no explicit alternatives or when-not-to-use statements, though the purpose is distinct enough to infer appropriate 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?
With no annotations provided, the description carries the full transparency burden. It discloses pagination behavior ('Returns paginated results via since_id cursor') and the continuation mechanism ('If has_more=true, call again with next_since_id'), which adds value beyond the schema. It does not mention rate limits or return field details, but the pagination disclosure is significant for a list 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 two sentences, front-loaded with the core action, and devoid of filler. Every sentence provides actionable information: what the tool does and how pagination works. This is exemplary conciseness.
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 8 parameters and no output schema, the description covers essential usage: it explains filtering options, pagination, and continuation. It does not need to repeat schema details, and the mention of has_more/next_since_id gives the agent the full loop for paginated retrieval. This is complete for a list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers 100% of parameters with descriptions, so the baseline is 3. The description adds minimal extra meaning by naming some filter fields and giving source_name examples, but it does not elaborate on date formats or parameter interactions. It neither significantly enhances nor diminishes the schema's clarity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious 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: 'List orders with optional filters.' It uses a specific verb ('List'), identifies the resource ('orders'), and distinguishes itself from sibling tools like get_order (single order) and count_orders (count) by implying a list operation. The mention of filters and pagination further clarifies its role.
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 use: listing orders with optional filters and pagination. It implicitly distinguishes itself from order-specific tools but does not explicitly exclude alternatives or name when to use search_orders or other siblings. Thus it gives clear context without exclusions, matching a 4.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses substantive behavioral traits: fuzzy matching of province text (e.g., 'HCM' resolves to canonical 'TP Hồ Chí Minh'), filling missing fields from the canonical dataset, and pre-flight rejection of post-2025 codes. The main shortcoming is that it lists required fields as 'address1, city, country' while the schema also requires customer_id, which is inconsistent and could mislead.
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 dense paragraph, front-loaded with purpose and required fields. The province-handling note and the API version warning are essential, and every sentence adds value. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with 17 parameters, no output schema, and no annotations, the description covers the most complex aspects (province/district/ward handling, schema version constraints). It does not explain the return value, and the required-fields list erroneously omits customer_id. Despite these gaps, it is substantially complete for the tool's tricky areas.
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 low (29%), so the description must compensate. It adds significant semantics for province/province_code (mutually exclusive usage with fuzzy matching), and for district/ward (must pass both text and code). It also restates required fields. However, it omits customer_id from the required list and does not explain optional fields like zip/phone, though those are self-explanatory from their names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious 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: 'Add a new address to a customer.' It uses a specific verb and resource, and is distinct from sibling tools like list_customer_addresses, update_customer_address, and set_default_customer_address, which handle other address 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?
It explicitly indicates when to use this tool (to add a new address) and directs to list_districts/list_wards for required sub-administrative data. It also warns about the pre-2025 schema limitation, which helps the agent avoid errors. However, it does not explicitly contrast with update_customer_address 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden and explicitly discloses the key side effect: 'creates an Order from the draft; draft status becomes completed.' It also explains the effect of payment_pending. However, it does not mention permissions, reversibility, or error conditions, which would make it more complete.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no filler. The first sentence states purpose and side effect; the second gives parameter usage guidance. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (2 params, no output schema), and the description covers purpose, side effects, and a usage nuance. It doesn't describe return values or failure cases, but these are not critical given the tool's simplicity and the absence of an 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?
Input schema provides 100% coverage for both parameters. The description adds value by explaining when to set payment_pending=true, which the schema only describes as 'If true, order is created with payment pending.' This goes beyond the schema's default-value note.
Input schemas describe structure but not intent. Descriptions should explain non-obvious 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: 'Complete a draft order and convert it into a real order.' It also distinguishes this from related tools (e.g., update_draft_order, send_draft_order_invoice) by explicitly mentioning the side effect of creating an 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 gives clear context for when to use the tool (completing a draft) and provides specific guidance for the payment_pending parameter: 'Use payment_pending=true if payment not yet collected.' It does not explicitly mention alternatives or when not to use it, but the use case 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?
Since no annotations are provided, the description carries the burden of disclosing behavior. It explicitly explains the pagination flow using since_id, has_more, and next_since_id, which is essential for a list endpoint. This goes beyond the schema by telling the agent to call again when has_more=true. It does not mention rate limits or response structure, but the pagination instruction is substantial behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences: the first states the purpose and filters, the second explains pagination. Every sentence earns its place, with no fluff. It is front-loaded with the verb and resource, making it immediately actionable.
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 list tool with 7 optional parameters and no output schema, the description provides the core roadmap: filters and pagination. It is not exhaustive (no default limit, no mention of sorting or response shape), but the pagination instruction is a critical missing piece that would otherwise be unclear. Overall, it is sufficiently complete for an agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds value by explaining the pagination loop involving since_id and next_since_id, which is not fully captured in the schema. It also names the key filters (status, vendor, product_type) upfront. However, it omits created_on_min/max and limit from the summary, though these are 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 begins with 'List products', which is a specific verb+resource combination. It clearly differentiates from sibling tools like get_product (single product), count_products (count), and search_products (search) by focusing on listing with filters. The optional filters are named, and pagination is implied, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly indicates when to use this tool: to list products with optional filters. It provides context for pagination. However, it does not explicitly mention alternatives or when not to use it (e.g., for keyword search use search_products, or for a single product use get_product). The guidance is clear 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 are provided, so the description carries full responsibility. It explicitly discloses that an email is sent to the customer and that the draft status changes to 'invoice_sent', which are critical behavioral traits. This is strong transparency, though it doesn't cover failure scenarios.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loads the primary action, and includes only essential information about side effects and requirements. 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?
The description covers purpose, side effects, and a prerequisite. Given the tool's moderate complexity (5 parameters, no output schema), this is sufficient for an agent to select and invoke it correctly. It doesn't describe return values, but those are not needed for understanding the tool's function.
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 meaning by noting that the 'to' parameter can substitute for a missing customer email. This connects the parameter to the prerequisite. Other parameters remain self-explanatory via 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 states the specific action ('Send an invoice email') and resource ('draft order'), and the side effect of status change differentiates it from related tools like complete_draft_order. It is clear 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?
Provides a clear precondition: requires customer email on the draft or via the 'to' parameter. This indicates when the tool is applicable, but it does not explicitly name alternative tools or state when not to use it, so it falls short of a full 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It explicitly discloses the partial update behavior ('Only provided fields are modified'), which is critical for correct invocation. It could mention return values or error handling, but the most important behavioral trait is covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no redundancy. The first sentence states the primary purpose, and the second adds a crucial behavioral note and refers to alternatives. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (11 parameters, no output schema), the description covers the key decision points: what the tool does, that it is a partial update, and when to use sibling tools. It could include details about the return value or required customer_id, but the schema covers the latter. Overall, it provides enough context for selection and correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 27%, so the description must compensate. The statement 'Only provided fields are modified' adds meaning to all parameters, indicating they are optional and individually updatable. While it doesn't detail each parameter, this semantic is valuable and improves over the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool updates an existing customer, using a specific verb and resource. It distinguishes itself from create_customer and get_customer, and also from the address management tools by explicitly directing users to add_customer_address / update_customer_address for address changes.
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 names alternative tools (add_customer_address / update_customer_address) and states they should be used for address management, providing a clear when-not-to-use this tool. It also implies usage for updating non-address customer fields.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the burden. It discloses a key behavioral quirk—the sentinel '-1' for district_code in level=2—and explains the relationship between levels. It does not explicitly state return format or pagination, but for a list operation this is acceptable and the disclosed sentinel is valuable.
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?
Three sentences, front-loaded with the primary purpose, then covering the two usage modes and the sentinel. Every sentence adds necessary context with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the tool's complexity (two administrative levels, sentinel, parameter dependencies), the description covers all necessary guidance: how to obtain codes, what to pass for each level, and the post-reform special case. No output schema exists, but the description sufficiently supports correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already covers parameter descriptions 100%, so baseline is 3. The description adds value by explicitly linking district_code and province_code to their source tools (list_districts and list_provinces), and by explaining the conditional requirement based on level. This goes beyond the schema's static 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 starts with a clear verb+resource ('List wards (Phường/Xã)') and immediately differentiates the tool from the sibling tools list_provinces and list_districts by specifying how to obtain codes from each. This makes the purpose unambiguous and distinct.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage instructions for both levels: level=3 with district_code from list_districts, and level=2 with province_code from list_provinces({level:2}). It also clarifies the sentinel '-1' for district_code in post-reform wards, leaving no ambiguity about which parameters to pass.
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 having no annotations, the description surfaces critical implicit behaviors: the default level is 3 when omitted, province code ranges differ by level (1–63 vs. starting at 2001), and level=2 is read-only for write endpoints. These details go far beyond what the schema alone conveys and are essential for correct invocation.
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 dense but every sentence contributes. The primary action is stated succinctly, followed by clearly labeled sections (WORKFLOW, NOTE) that organize the alternative schema usages. No fluff or repetition of schema content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given there is no output schema or annotations, the description carries the full explanatory burden. It covers the default behavior, both possible level values, and the exact workflows for downstream calls, which is comprehensive. However, it does not explicitly describe the response structure (e.g., fields returned), which would have been helpful but is not strictly necessary given the tool's purpose.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents the 'level' parameter fully with a 100% coverage, so baseline is 3. The description adds meaningful semantic context by explaining the default value, the tier counts (3-tier vs. 2-tier), and the code format differences. This exceeds the baseline by providing crucial operational nuance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear verb-object statement: 'List Vietnamese provinces.' It then differentiates the tool from its siblings by explaining the two administrative levels (level=2 and level=3) and their implications for the result set, which is unique to this tool in the context of the sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use each level, provides step-by-step workflows for new schema (level=2) and old schema (level=3), and gives the important exclusion: 'Sapo write endpoints ... accept ONLY level=3 codes; level=2 is read-only as of 2026-05.' This clearly guides tool selection and 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?
With no annotations, the description carries full burden and does so admirably. It discloses that only provided fields are modified (partial update), that codes alone are silently dropped (requiring both text and code), and that the endpoint only accepts the pre-2025 3-tier schema. These are critical behavioral traits beyond basic 'update.'
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences long, each earning its place: the main action, the alternative for default setting, and two critical warnings. It is front-loaded with the purpose and wastes no 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 the 18-parameter complexity and no annotations or output schema, the description covers the essential context: partial update semantics, the default-setting alternative, the schema compatibility constraint, and the code/text pairing requirement. It doesn't explain return values, but the absence of an output schema lowers that burden. The main pitfalls are thoroughly addressed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 28%, so the description must compensate. It adds crucial meaning for the subdivision fields by explaining the need to pass both text name and code together, and warns about the 3-tier schema limitation. However, many parameters (zip, city, district, etc.) remain unexplained, though they are mostly self-explanatory. The most error-prone fields are well covered.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Update an existing customer address,' a specific verb+resource that clearly states the tool's function. It also distinguishes itself from sibling tools by explicitly naming set_default_customer_address for the default-setting use case, and the contrast with add_customer_address is implicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives an explicit alternative: 'To set this address as default, use set_default_customer_address (Sapo dedicated endpoint).' It also states when NOT to use this endpoint (new 2-tier addresses) and describes the failure mode (returns 422). This is clear, actionable guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses a critical behavioral quirk: Sapo silently ignores customer/customer_id fields on update with no error or effect. It also warns about destructive consequences of cancel+recreate, and includes a 'Verified live 2026-05-01' note. This goes well beyond what the schema or annotations (none provided) would convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and front-loaded with the core purpose and supported fields. It gets slightly longer due to the important caveat and workarounds, but every section earns its place. The 'Verified live' line could be seen as optional, but it adds confidence, so the length is justified.
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 (a silent failure and alternative workarounds), the description covers the essential context comprehensively. Without an output schema, it does not explicitly mention the return value, which is a minor gap, but the update operation's response is likely predictable for an agent familiar with Shopify/Sapo APIs. Overall, it is complete enough for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is high (83%), but the description adds essential meaning by explaining that the customer link cannot be changed and providing concrete workaround examples like `tags: "customer:<id>"` and setting email. This clarifies behaviors not represented in the schema, e.g., how to tag or use email to track customers.
Input schemas describe structure but not intent. Descriptions should explain non-obvious 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 'Update an existing order via PUT /admin/orders/{id}.json' with a specific verb and resource, and enumerates supported fields. It distinguishes itself from sibling tools like update_draft_order by explicitly warning against cancel-and-recreate via draft_order, reinforcing its specific role.
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: it is for updating existing orders, and includes a strong when-not-to-use directive ('Do NOT cancel + recreate via draft_order') with reasoning about data loss. It also offers workarounds for tracking customers, guiding the agent on alternative approaches when the primary operation isn't suitable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description takes on the transparency burden. It discloses the critical edge case that level=2 returns empty results and explains why, which is exactly the kind of behavioral context needed beyond the basic list 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?
Two sentences, front-loaded with the primary action, followed by a necessary caveat. No filler or repetition of schema-level 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?
Given the tool's simple nature and full schema coverage, the description covers the essential usage context, including the level-dependent behavior. It is appropriately complete for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already has 100% parameter coverage, describing both level and province_code. The description adds value by tying level=3 to default and explicitly noting the empty response for level=2, which is not stated in the schema itself. This enriches the schema information without redundancy.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'List districts (Quận/Huyện) within a province', which is a specific verb+resource+scope. It clearly distinguishes from sibling tools like list_wards and list_provinces by naming the district level and explaining its dependence on the schema level.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states 'Only meaningful for level=3 (pre-2025 3-tier schema, default)' and 'With level=2 the response is empty because the district level was abolished on 2025-07-01', providing clear when-to-use and when-not-to-use guidance, including the reason.
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:

[![Sapo-MCP MCP server](https://glama.ai/mcp/servers/nguyennguyenit/Sapo-MCP/badges/card.svg)](https://glama.ai/mcp/servers/nguyennguyenit/Sapo-MCP)

Score Badge

Copy to your README.md:

[![Sapo-MCP MCP server](https://glama.ai/mcp/servers/nguyennguyenit/Sapo-MCP/badges/score.svg)](https://glama.ai/mcp/servers/nguyennguyenit/Sapo-MCP)

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/nguyennguyenit/Sapo-MCP'

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