Read EasyStore orders, products and customers; manage stock, fulfillments and customer records.
Scored across 29 tools
Most tools target distinct resource/action pairs, and the write tools clearly separate relative inventory adjustment from exact inventory setting. The main overlap is between easystore_list_customers (broad query search) and easystore_search_customers (exact email/phone/code lookup), plus some potential confusion between product listing and product detail/variant listing tools.
All tools share the easystore_ prefix and use readable snake_case verb_noun naming such as list_orders, get_customer, create_fulfillment, and adjust_inventory_level. Minor variations like get_customer_points or list_order_fulfillments still follow the same predictable convention.
Twenty-nine tools is heavy for a single MCP server, even for a broad commerce platform covering orders, customers, products, inventory, locations, and content. The set is organized by resource family and each tool has a plausible role, but the surface is large enough to feel borderline unwieldy.
Read coverage is broad across store, products, orders, customers, inventory, and content, with several useful write operations for customers, inventory, fulfillments, and order cancellation. However, major lifecycle gaps remain: no product creation/update/delete beyond variants, no order creation/update, no collection management writes, and content tools are read-only.
WRITE. Add to or remove from the stock of one variant at one location by a relative amount (positive adds, negative removes; 0 is rejected). Not idempotent: repeating it changes the stock again. Omit location_id for the primary location. Needs write_products. PUT /api/4.0/inventory_levels/adjust.json.
| Name | Required | Description | Default |
|---|---|---|---|
| variant_id | Yes | Variant id (see easystore_list_product_variants). | |
| location_id | No | Location id (see easystore_list_locations). Default: the primary location. | |
| adjustment_quantity | Yes | Relative change: 5 adds 5, -5 removes 5. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark this as non-read-only, destructive, non-idempotent, and open-world; the description reinforces the write/non-idempotent behavior and adds useful details: the required write_products permission, the endpoint, zero rejection, and the consequence of repeating the call.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
It is front-loaded with 'WRITE' and packs only actionable information into a few dense sentences: relative semantics, rejection rule, default location, permission, non-idempotence, and endpoint. There is no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a three-parameter mutation with rich annotations and no output schema, the definition covers the essential context: what changes, how the relative amount works, non-idempotence, permission requirements, default location behavior, and the underlying endpoint.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds meaningful semantics by stating that adjustment_quantity is relative, that zero is rejected, and that omitted location_id targets the primary location. The positive/negative behavior is already in the schema, so it is not a full 5.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: add to or remove from stock for one variant at one location by a relative amount. The phrase 'relative amount' clearly distinguishes this from the sibling easystore_set_inventory_level, which sets an absolute level.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives clear usage context: positive adds, negative removes, zero is rejected, omit location_id for the primary location, and it is not idempotent. It does not explicitly name easystore_set_inventory_level as the alternative for absolute stock values, so it falls short of a full when/when-not routing statement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
WRITE, hard to undo. Cancel an order, with an optional reason. Confirm the order id and number with the user first. Needs write_orders. POST /api/3.0/orders/{id}/cancel.json.
| Name | Required | Description | Default |
|---|---|---|---|
| reason | No | Why the order is cancelled, e.g. Damaged item. | |
| order_id | Yes | EasyStore order id (not the order number). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, idempotentHint=true and openWorldHint=true; the description adds the human-meaningful consequences ('hard to undo'), the required OAuth scope, and the confirmation protocol. It stops short of stating what actually happens to the order (status change, refund, inventory restock), which matters for a destructive write.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four short clauses, front-loaded with the risk flag and ending with the endpoint. No sentence is redundant and an agent can parse the safety posture in the first two words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 2-parameter destructive write with full annotation coverage and no output schema, this covers safety, prerequisites, confirmation, and transport. The one meaningful omission is the post-cancellation state, which an agent may need to report back to a user.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3; the confirmation instruction goes beyond the schema by flagging the id-vs-order-number trap at the point of invocation. It adds no detail on reason formatting beyond what the schema's min/max length and example already convey.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Cancel an order') with a scope qualifier ('optional reason') that maps directly onto the two parameters. The 'WRITE' prefix immediately separates it from the many read-oriented easystore_get_*/list_* siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives a concrete pre-call workflow ('Confirm the order id and number with the user first') and a hard prerequisite ('Needs write_orders'). It does not name an alternative or suggest a read-only verification step such as easystore_get_order, which is the obvious sibling pairing for a destructive action.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
WRITE. Create a customer. Pass at least one of first_name, last_name, email or phone. Not idempotent. Needs write_customers. POST /api/3.0/customers.json.
| Name | Required | Description | Default |
|---|---|---|---|
| code | No | Your own customer code. | |
| No | Email (unique per store). | ||
| phone | No | Phone number, e.g. +60192233445. | |
| gender | No | Gender. | |
| groups | No | Group names to assign, e.g. ["VIP"]. | |
| birthdate | No | yyyy-mm-dd. | |
| last_name | No | Last name. | |
| first_name | No | First name. | |
| country_code | No | Two-letter country code, e.g. MY. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false and idempotentHint=false, so 'WRITE' and 'Not idempotent' mostly restate structured data. However, the description adds genuinely new operational context: the required OAuth scope (write_customers) and the concrete endpoint (POST /api/3.0/customers.json), which an agent needs for auth planning and debugging.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Five short fragments, each carrying distinct information, with the most decision-relevant fact ('WRITE') front-loaded. No filler, no repetition of the title.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation with no output schema and no annotations beyond safety hints, the description covers the action, the precondition, the non-idempotency, the permission, and the endpoint. It stops short of telling the agent what a successful response contains (e.g. the new customer id) or how duplicate email/phone per store is handled, which matters given the schema's 'unique per store' note.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline would be 3, but the description adds meaning the schema lacks: the schema lists zero required parameters, and only the description reveals that at least one identity field (first_name/last_name/email/phone) must be supplied. That is a real constraint not encoded anywhere in the input schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Create a customer') and disambiguates from the many read/list siblings by leading with 'WRITE.' An agent can immediately tell this apart from easystore_list_customers, easystore_search_customers, and easystore_get_customer.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Pass at least one of first_name, last_name, email or phone' is a concrete precondition for a successful call, and 'Needs write_customers' tells the agent the required scope. It does not explicitly say when to prefer easystore_update_customer instead, but the create-vs-update distinction is self-evident from the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
WRITE. Mark an order (or some of its line items) as shipped, with tracking details. Not idempotent: calling it twice creates two fulfillments. With notify_customer true the customer is emailed. Needs write_fulfillments. POST /api/3.0/orders/{id}/fulfillments.json.
| Name | Required | Description | Default |
|---|---|---|---|
| status | No | Shipment status. | |
| message | No | Note about this fulfillment. | |
| order_id | Yes | EasyStore order id. | |
| line_items | No | Only these line items and quantities; omit to fulfill the whole order. | |
| tracking_url | No | Tracking page URL. | |
| notify_customer | No | Email the customer (default false). | |
| tracking_number | No | Tracking number. | |
| tracking_company | No | Courier name, e.g. DHL. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructive, non-idempotent, and open-world behavior, so the description's 'WRITE' and 'Not idempotent' are somewhat redundant. It does earn credit for spelling out the concrete consequence (two fulfillments on a double call), the customer email side effect, the required scope (write_fulfillments), and the endpoint.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four short sentences, front-loaded with 'WRITE', with no wasted words. The idempotency statement partially repeats the annotation, but it is short enough that it does not harm readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive, non-idempotent mutation with eight parameters and no output schema, the description covers safety signal, repeat-call risk, notification side effect, permission, and endpoint. It does not describe the returned fulfillment object or default status behavior, which are minor gaps for this schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents every parameter, including the 'omit to fulfill the whole order' semantics for line_items. The description restates the partial-fulfillment idea and the notify_customer behavior without adding format or default detail beyond the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Mark an order ... as shipped') and scopes it to whole-order or partial line-item fulfillment. It is clearly distinguishable from listing tools like easystore_list_order_fulfillments, but it never names a sibling or an alternative explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies when to use it (marking shipments) and gives an important caveat about repeat calls and the notify_customer side effect, but offers no explicit when-not guidance or comparison with alternatives such as easystore_cancel_order or easystore_list_order_fulfillments.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One collection by id. Needs read_products. GET /api/3.0/collections/{id}.json.
| Name | Required | Description | Default |
|---|---|---|---|
| collection_id | Yes | EasyStore collection id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the basic safety profile is covered. The description adds useful context by stating the required permission ('Needs read_products') and the REST endpoint, but it does not describe error behavior or return characteristics beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short and front-loads the core purpose, with no wasted sentences. Its telegraphic style is efficient, though slightly more prose could improve clarity without adding bulk.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-resource read tool with one fully documented parameter and annotations covering safety, the description includes the key invocation details: required permission and endpoint. It does not describe the return shape, but no output schema exists; this is a minor gap for such a straightforward retrieval.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter is fully documented in the schema as 'EasyStore collection id.' The description only says 'by id,' which adds little beyond the schema. With 100% schema description coverage, the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific retrieval action and resource: 'One collection by id.' This clearly distinguishes it from listing collections, though it does not explicitly name the sibling tool easystore_list_collections as the alternative.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'One collection by id' implies the tool is for fetching a single collection when its id is known, but it does not explicitly describe when to use this versus easystore_list_collections or other retrieval tools. Usage is inferable but not fully guided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One customer by id. Add fields=points,membership for loyalty data. Needs read_customers. GET /api/3.0/customers/{id}.json.
| Name | Required | Description | Default |
|---|---|---|---|
| fields | No | Extra sections, e.g. points,membership. | |
| customer_id | Yes | EasyStore customer id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish that this is a read-only, non-destructive, open-world operation. The description adds valuable behavioral context by naming the required auth scope (read_customers) and the endpoint path, but it omits what happens on missing/invalid IDs or any rate-limit/error behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short and front-loaded with the core purpose, then adds auth and endpoint details. It earns its space, though the compressed telegraphic style could be slightly more readable without losing brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter read-only lookup with annotations covering safety and no output schema, the description provides adequate context: purpose, auth requirement, optional fields behavior, and endpoint. It could do slightly more to explain return content or not-found behavior, but nothing critical is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters. The description adds only a light usage hint about setting fields=points,membership for loyalty data, which mostly restates the schema's example rather than introducing new syntax or constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb+resource ('One customer by id') and distinguishes it from the list/search customer siblings by emphasizing a single customer lookup. It is understandable at a glance, though it could more explicitly contrast with easystore_list_customers and easystore_search_customers.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides a useful hint for when to add 'fields=points,membership' and notes the required read_customers permission. However, it does not explicitly say when to use this tool versus list_customers, search_customers, or get_customer_points, leaving alternatives largely implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The loyalty points balance of one customer. Needs read_customers. GET /api/3.0/customers/{id}/points.json.
| Name | Required | Description | Default |
|---|---|---|---|
| customer_id | Yes | EasyStore customer id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds something the annotations do not: the required read_customers scope, which is real operational context for an agent planning calls. It stops short of describing the payload shape, keeping it at 4.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short fragments, front-loaded with what is returned, then the permission, then the endpoint. Nothing meaningful is wasted, though the raw endpoint path is marginal information for an agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter read with no output schema, the description covers what is returned (points balance), the scope (one customer), and the auth requirement. It would be stronger if it sketched the response shape or noted behavior for a customer with no loyalty record.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There is a single parameter with 100% schema description coverage, so the schema fully documents customer_id. The description only echoes the id position in the path template and adds no semantics beyond that — the baseline 3 for high-coverage schemas applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a precise resource and scope: the loyalty points balance (not the customer record) for exactly one customer. An agent can distinguish it from easystore_get_customer, though the description never names that sibling explicitly, which keeps it from a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Needs read_customers' gives a prerequisite, and 'one customer' implies this is the per-customer lookup rather than a list. There is no explicit statement of when to prefer this over easystore_get_customer or easystore_search_customers, and no exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One order by id. Ask for extra sections with fields: items, addresses, transactions, fulfillments, refunds, taxes, customer, shipping_fees, discounts, points, cancellation, note_attributes. Needs read_orders. GET /api/3.0/orders/{id}.json.
| Name | Required | Description | Default |
|---|---|---|---|
| fields | No | Comma-separated extra sections, e.g. items,addresses,fulfillments. | |
| order_id | Yes | EasyStore order id (not the order number). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=true), so the description only needs to add context — and it does: the required read_orders scope and the underlying endpoint GET /api/3.0/orders/{id}.json. It does not describe error behavior or how sections are returned, but that is a modest gap given annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core purpose, then auth, then the optional-section list; every clause carries information and there is no filler. The telegraphic fragment style is efficient but slightly clipped compared with full prose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description is the only place an agent could learn what a successful call returns, and it says nothing about the response shape beyond implying that extra sections are opt-in. For a simple two-parameter read tool this is adequate but leaves a real gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3, but the description goes further by enumerating the full set of legal fields values (items, addresses, transactions, fulfillments, refunds, taxes, customer, shipping_fees, discounts, points, cancellation, note_attributes), which the schema only illustrates with three examples. This materially reduces trial-and-error on the fields parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific resource and scope (a single order fetched by id), which cleanly separates it from the sibling easystore_list_orders. The verb is implicit rather than stated ('One order by id'), but the meaning is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Adds a real prerequisite ('Needs read_orders') and tells the agent how to request extra sections via fields. However, it never explicitly routes between this and easystore_list_orders, nor states when not to use it or what happens if the id does not exist.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One product by id with its variants, options, images and collections. Needs read_products. GET /api/3.0/products/{id}.json.
| Name | Required | Description | Default |
|---|---|---|---|
| product_id | Yes | EasyStore product id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover safety (readOnly, non-destructive, openWorld), so the description's added value is the required scope 'read_products', the underlying endpoint, and the returned payload contents (variants, options, images, collections). That is meaningful context beyond the annotations, though it omits error behavior for a missing id.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, front-loaded with the payload contents and followed by the auth requirement and endpoint; every clause carries information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, describing the returned sub-resources is valuable and fills that gap, and the scope requirement prepares the agent for auth failures. Only minor elements like not-found behavior are missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a single documented product_id parameter, so the schema does the heavy lifting. The description adds no format or constraint details beyond what the schema already says.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource — fetches one product by id — and the phrase 'one product by id' implicitly distinguishes it from the sibling easystore_list_products. It is clear without explicitly naming the alternative.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The single-item vs list distinction is implied by 'One product by id' alongside the list siblings, but there is no explicit when-to-use or when-not-to-use guidance and no named alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The store behind this access token: name, contact emails, easystore domain, plan, locale, country, time zone, currencies and locations. Needs no API access scope. GET /api/3.0/store.json.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuine beyond-schema context: the tool requires no API access scope, and it spells out what the payload contains and the underlying endpoint (GET /api/3.0/store.json), which tells an agent this is an unauthenticated-scope, single-object read.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero filler: the resource and its contents come first, then the auth note and endpoint. The field list is dense but each item describes the actual return shape, so it earns its place because no output schema exists.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the field enumeration in the description is the only source of return-shape information, and it does that job well. The auth-scope note covers a real gotcha for a token-scoped read. Minor gap: it does not say what happens if the token is invalid or the store is unavailable, that is, no error or failure behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so the baseline is 4, and the empty schema is consistent with a full-store read. The description adds nothing to compensate for because there is nothing to parameterize.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Identifies the exact resource as 'the store behind this access token' and enumerates the fields returned (name, contact emails, domain, plan, locale, country, time zone, currencies, locations), so it is far more specific than a tautology. It does not explicitly contrast with nearby siblings such as easystore_list_locations, though the scoping to a single store object makes the distinction inferable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the resource name and by 'the store behind this access token', which tells an agent this is the account-context lookup. There is no explicit when-to-use or when-not statement, and no routing to alternatives. 'Needs no API access scope' is a useful precondition but is not usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List blog articles. Needs read_content. GET /api/3.0/articles.json.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number, from 1 (default 1). Pass the previous reply's next_page. | |
| limit | No | Results per page, 1-100 (default 25). | |
| visibility | No | Only published or unpublished articles. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds a genuinely useful behavioral fact beyond annotations: the required 'read_content' scope, plus the underlying endpoint path. It says nothing about result volume or pagination expectations, keeping this at a moderate score.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three terse sentences, front-loaded with purpose then prerequisite then endpoint; no filler. The raw endpoint path is of marginal value to an agent but is not wasteful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list tool with a fully described 3-parameter schema and no output schema, the description covers purpose, required scope and endpoint. The one meaningful omission is disambiguation from easystore_list_blogs, which matters given the near-identical sibling.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% — page, limit, visibility and the enum are all documented in the schema, including the next_page chaining hint. The description adds no parameter meaning beyond that, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('List blog articles'), so an agent knows exactly what it retrieves. However, the sibling tool easystore_list_blogs exists and the description never distinguishes articles from blogs, leaving a real ambiguity for selection.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The only guidance is a scope prerequisite ('Needs read_content'); there is no statement of when to use this versus easystore_list_blogs or the get_* variants, and no exclusion conditions. An agent must infer the choice entirely from the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the store's blogs. Needs read_content. GET /api/3.0/blogs.json.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number, from 1 (default 1). Pass the previous reply's next_page. | |
| limit | No | Results per page, 1-100 (default 25). | |
| visibility | No | Only published or unpublished blogs. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds the required auth scope (read_content) and the underlying REST path, both useful beyond the annotations, but says nothing about result ordering, pagination behavior, or empty results.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, purpose front-loaded, with permission and endpoint as supporting detail. Nothing is wasted and nothing is buried.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only, zero-required-parameter list tool with full schema coverage and annotations covering the safety profile, the definition is nearly sufficient. The only minor gap is that, with no output schema, the description gives no hint of the shape of the returned blog list.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%: page, limit and the visibility enum are all documented in the schema, including the "pass the previous reply's next_page" pagination convention. The description adds no parameter meaning beyond that, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ("List the store's blogs"), which is unambiguous and distinct from sibling list endpoints such as list_articles and list_pages. It doesn't explicitly contrast itself with those siblings, leaving that inference to the resource name alone.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
"Needs read_content" gives a genuine prerequisite for calling it, which is more than most siblings offer. However, there is no explicit when-to-use/when-not-to-use guidance or routing to alternatives (e.g., when a single-blog fetch is preferable).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List checkouts (carts in progress or abandoned). Cart tokens are not returned. Needs read_orders. GET /api/3.0/checkouts.json.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number, from 1 (default 1). Pass the previous reply's next_page. | |
| limit | No | Results per page, 1-50 (default 25). | |
| since_id | No | Start at this checkout id (inclusive). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so safety is covered. The description adds genuine value beyond them: it discloses the required auth scope and, importantly, that cart tokens are omitted from results — a behavioral caveat an agent could not infer elsewhere.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three compact sentences, each carrying a distinct fact (definition, output caveat, auth/endpoint). It is front-loaded with the purpose and wastes nothing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description usefully notes what is not returned (cart tokens) and how results are paged (in the schema). It is nearly complete for a simple read-only list tool, though it remains silent on result ordering and total counts.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with page, limit, and since_id all documented in the schema, including pagination chaining via next_page. The description adds no parameter-level detail, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('List checkouts') and clarifies the ambiguous term with a parenthetical ('carts in progress or abandoned'). That disambiguates it from orders, but it doesn't explicitly differentiate from list siblings like list_orders in terms of what a checkout represents in the lifecycle.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives prerequisite context ('Needs read_orders'), which helps an agent know when it can be called. However, there is no explicit when-to-use vs. when-not guidance or comparison to alternatives such as list_orders, leaving the usage decision implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List product collections. Needs read_products. GET /api/3.0/collections.json.
| Name | Required | Description | Default |
|---|---|---|---|
| ids | No | Only these collection ids, comma-separated. | |
| page | No | Page number, from 1 (default 1). Pass the previous reply's next_page. | |
| sort | No | Sort as field.asc or field.desc, e.g. id.asc (a stable order for paging through everything). | |
| limit | No | Results per page, 1-100 (default 25). | |
| since_id | No | Start at this collection id (inclusive). | |
| visibility | No | true = only published collections. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=true). The description adds the required scope and the underlying endpoint, but does not disclose pagination mechanics (the schema hints at next_page) or what the response shape looks like. With annotations carrying the safety burden, this is a moderate-value addition.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short fragments, front-loaded with the purpose and zero filler. The endpoint reference is slightly redundant with the tool name but still cheap; the telegraphed style is efficient if a bit terse for an agent needing context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-required parameter read-only list tool with full schema coverage and no output schema, the description covers purpose, scope, and endpoint, but omits how paging/next_page should be consumed and what a collection record contains. Adequate but with clear gaps for an agent planning a paginated enumeration.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so all six parameters (ids, page, sort, limit, since_id, visibility) are fully documented in the schema. The description adds nothing about parameter semantics, so the baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('List product collections'), which cleanly separates it from the sibling 'easystore_get_collection' (single) and 'easystore_list_products'. It does not explicitly name those siblings, but the list-vs-get distinction is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description supplies a prerequisite ('Needs read_products'), which is real usage context, but it never says when to prefer this over alternatives (e.g., 'easystore_get_collection' for a single id) or when the ids filter vs paging applies. Usage is implied by the name and prerequisite rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The saved addresses of one customer. Needs read_customers. GET /api/3.0/customers/{id}/addresses.json.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number, from 1 (default 1). Pass the previous reply's next_page. | |
| limit | No | Results per page, 1-100 (default 25). | |
| customer_id | Yes | EasyStore customer id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only/non-destructive/open-world, so the description wisely spends words elsewhere: the required read_customers scope and the exact endpoint. It doesn't discuss pagination or return shape, but the schema covers paging.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, front-loaded with what the tool returns before the auth requirement and endpoint. Nothing wasteful, though the phrasing is telegraphic and the raw endpoint path adds little for an agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple paginated read with no output schema and full annotation coverage, this states the resource, the required permission, and where the data comes from. An agent has enough to invoke it correctly; only the response shape is unaddressed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so page/limit/customer_id are fully documented in structured fields. The description adds no syntax or semantics beyond 'one customer', so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Identifies the resource precisely ('saved addresses of one customer'), which clearly separates it from easystore_get_customer or easystore_list_customers. The verb 'list' is only implied from the name/title, not stated in the description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Needs read_customers' gives a real precondition for calling it, and the customer-scoped resource implies when to use it. However, it names no alternatives or exclusions (e.g. when to prefer get_customer to read the full record), so routing is left partly to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List customer groups (for example VIP). Needs read_customers. GET /api/3.0/groups.json.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds the required auth scope and the underlying endpoint (GET /api/3.0/groups.json), which annotations do not convey — genuinely useful extra context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three compact fragments — purpose, example, permission, endpoint — with the core purpose front-loaded and no filler whatsoever.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-param, no-output-schema list tool this is nearly sufficient; the example clarifies the return semantics. The only gap is whether the result is paginated or bounded, which an agent might want to know.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Zero parameters, so the baseline is 4. Nothing in the schema needs explaining, and the description correctly doesn't waste words on parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb + resource ('List customer groups') with a concrete example ('for example VIP') that tells the agent what a group actually is. The resource name alone separates it from the many other list_* siblings, though it never explicitly says so.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied by the resource name — there is no statement of when to reach for this versus easystore_list_customers or easystore_get_customer, and no exclusions. The permission note ('Needs read_customers') is the only precondition given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List customers with contact details, order count, total spent, groups and store credit. Search by name or email with query. Needs read_customers. GET /api/3.0/customers.json.
| Name | Required | Description | Default |
|---|---|---|---|
| ids | No | Only these customer ids, comma-separated. | |
| page | No | Page number, from 1 (default 1). Pass the previous reply's next_page. | |
| sort | No | Sort as field.asc or field.desc, e.g. id.asc (a stable order for paging through everything). | |
| limit | No | Results per page, 1-100 (default 25). | |
| query | No | Match on first name, last name or email. | |
| since_id | No | Start at this customer id (inclusive). | |
| created_at_max | No | ISO 8601 date or date-time, e.g. 2026-10-01 or 2026-10-01T00:00:00+08:00. | |
| created_at_min | No | ISO 8601 date or date-time, e.g. 2026-10-01 or 2026-10-01T00:00:00+08:00. | |
| updated_at_max | No | ISO 8601 date or date-time, e.g. 2026-10-01 or 2026-10-01T00:00:00+08:00. | |
| updated_at_min | No | ISO 8601 date or date-time, e.g. 2026-10-01 or 2026-10-01T00:00:00+08:00. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds genuinely new context: the required read_customers scope and the underlying GET /api/3.0/customers.json endpoint, which matters for auth planning. It stops short of describing pagination or result limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, front-loaded with the returned fields, then filtering, then prerequisites and endpoint. No filler and nothing buried.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With ten all-optional parameters fully covered by the schema and no output schema, the description usefully enumerates returned fields and the auth scope. The main gap is routing guidance versus the overlapping search_customers sibling.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all ten parameters (paging, sorting, date ranges, ids, since_id) are fully documented in the schema. The description only restates the query parameter's behavior, adding nothing beyond the schema, which matches the baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource plus the fields returned (contact details, order count, total spent, groups, store credit), so an agent knows what it gets. It does not distinguish itself from the close sibling easystore_search_customers, and in fact advertises searching by name/email, which overlaps that sibling's apparent purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
"Needs read_customers" and "Search by name or email with query" give implied usage context. There is no explicit when-to-use versus easystore_search_customers or easystore_get_customer, and no statement of when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Stock per variant per location: available (inventory_quantity), committed, incoming and reserved. Pass variant_ids or location_ids (at least one is required). Needs read_products. GET /api/4.0/inventory_levels.json.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number, from 1 (default 1). Pass the previous reply's next_page. | |
| limit | No | Results per page, 1-100 (default 25). | |
| variant_ids | No | Variant ids, comma-separated (see easystore_list_product_variants). | |
| location_ids | No | Location ids, comma-separated (see easystore_list_locations). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is clear. The description adds useful operational context beyond annotations: the required read_products auth scope, the endpoint, the returned stock fields, and the need for at least one filter.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: it states the resource and returned fields first, then the required filters, auth scope, and endpoint. Every sentence adds practical information without repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only listing tool with full schema descriptions and annotations, the description supplies the remaining critical context: what the output represents, the required filter constraint, auth scope, and endpoint. Pagination details are already covered by the schema, so nothing important is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline would be 3, but the description adds meaningful semantics by stating that at least one of variant_ids or location_ids is required. It also maps 'available' to inventory_quantity, which helps interpret the result. Pagination parameters are left to the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that this retrieves stock per variant per location, with returned fields like available, committed, incoming, and reserved. It is specific enough to distinguish a read operation from mutation siblings, though it does not explicitly name the adjust/set inventory tools as alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives an invocation constraint ('Pass variant_ids or location_ids, at least one is required') but does not explain when to use this tool versus related tools such as easystore_adjust_inventory_level or easystore_set_inventory_level. Usage context is implied by 'Stock per variant per location' but not directly provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The store's stock and pickup locations (warehouses, outlets) with address, phone, is_primary and pickup settings. Use the ids for inventory levels. Needs read_locations. GET /api/3.0/locations.json.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number, from 1 (default 1). Pass the previous reply's next_page. | |
| limit | No | Results per page, 1-100 (default 25). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, non-destructive and openWorld, so the safety profile is covered; the description adds genuinely new context: the required read_locations scope, the underlying GET /api/3.0/locations.json endpoint, and the field set returned. It does not mention pagination behavior beyond what the schema says.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, front-loaded with what the resource is and its fields, followed by usage and prerequisite. Every sentence carries distinct information with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, and the description compensates by listing the returned fields; auth scope and endpoint are also given, and pagination is covered by the schema. Complete enough for an agent to call correctly, with only minor gaps like unpaginated vs paginated semantics.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and both parameters (page, limit) are documented in-schema including the next_page chaining hint. The description adds nothing about either parameter, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('List locations') and enumerates returned fields (address, phone, is_primary, pickup settings), so the agent knows exactly what comes back. It also distinguishes itself from easystore_list_inventory_levels by noting 'Use the ids for inventory levels', though the sibling is not named directly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Use the ids for inventory levels' gives a clear downstream-use cue and implicitly routes the agent toward easystore_list_inventory_levels, and 'Needs read_locations' states the prerequisite scope. No explicit when-not-to-use or named alternative, which keeps it at 4.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The fulfillments (shipments with tracking details and status) of one order. Needs read_fulfillments. GET /api/3.0/orders/{id}/fulfillments.json.
| Name | Required | Description | Default |
|---|---|---|---|
| order_id | Yes | EasyStore order id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds real behavioral context beyond that: the required read_fulfillments scope and the concrete endpoint GET /api/3.0/orders/{id}/fulfillments.json. It does not mention pagination or empty-result behavior, keeping it just short of a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short fragments with zero waste: what it returns, what permission it needs, and the endpoint. The most important information (the resource and its scope) is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With one required parameter, no output schema and annotations covering the safety profile, the description does what is needed: it explains what the return payload represents ('shipments with tracking details and status') in lieu of an output schema, and states the auth scope. Only pagination/volume expectations are absent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There is a single parameter and schema description coverage is 100%, with the schema already stating 'EasyStore order id.' The description reinforces that the id scopes to one order but adds no format or edge-case detail. Baseline 3 applies when the schema does the work.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: lists the fulfillments of a single order, and parenthetically defines what a fulfillment contains (shipments with tracking details and status). That distinguishes it from easystore_create_fulfillment and easystore_list_order_transactions without naming them, so it is clear but lacks explicit sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'of one order' plus the required order_id implies the usage context (look up shipments for a known order) and the scope requirement 'Needs read_fulfillments' signals an auth prerequisite. However, it never states when to use this rather than a sibling such as easystore_get_order or easystore_list_order_transactions, 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.
List orders from every sales channel with customer, items, totals, payment and fulfillment status. Filter by payment or fulfillment status, customer, or dates (store time zone). Needs read_orders. GET /api/3.0/orders.json.
| Name | Required | Description | Default |
|---|---|---|---|
| ids | No | Only these order ids, comma-separated. | |
| page | No | Page number, from 1 (default 1). Pass the previous reply's next_page. | |
| sort | No | Sort as field.asc or field.desc, e.g. id.asc (a stable order for paging through everything). | |
| limit | No | Results per page, 1-100 (default 25). | |
| since_id | No | Start at this order id (inclusive: id >= since_id). Use with sort=id.asc. | |
| customer_id | No | Only this customer's orders. | |
| created_at_max | No | yyyy-mm-dd or yyyy-mm-dd hh:mm:ss, read in the store's own time zone. | |
| created_at_min | No | yyyy-mm-dd or yyyy-mm-dd hh:mm:ss, read in the store's own time zone. | |
| updated_at_max | No | yyyy-mm-dd or yyyy-mm-dd hh:mm:ss, read in the store's own time zone. | |
| updated_at_min | No | yyyy-mm-dd or yyyy-mm-dd hh:mm:ss, read in the store's own time zone. | |
| financial_status | No | Payment status. | |
| processed_at_max | No | yyyy-mm-dd or yyyy-mm-dd hh:mm:ss, read in the store's own time zone. | |
| processed_at_min | No | yyyy-mm-dd or yyyy-mm-dd hh:mm:ss, read in the store's own time zone. | |
| fulfillment_status | No | Shipping status. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds value beyond them: the required read_orders scope and the fact that date filters are interpreted in the store's own time zone, plus the concrete endpoint GET /api/3.0/orders.json.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, front-loaded with purpose, then filters, then permission and endpoint. Nothing is redundant or padding; each clause carries information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 14-optional-parameter list tool with no output schema and full schema coverage, the description covers purpose, filters, auth scope and endpoint. It omits pagination guidance (page/limit/next_page behavior) and any hint at result size or ordering defaults, which would help an agent drive multi-page retrieval.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with every one of the 14 parameters documented including enum values and date formats, so the baseline is 3. The description's filter summary and time-zone note largely restate what the schema already says per-parameter and add no format or precedence detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Opens with a specific verb and resource ('List orders') and enumerates the payload fields returned (customer, items, totals, payment, fulfillment status) plus the cross-channel scope. It is clear on its own, but it never names the sibling easystore_get_order as the single-order alternative, so the boundary is inferred rather than stated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly lists the filter dimensions (payment/fulfillment status, customer, dates) and states the prerequisite 'Needs read_orders', which is real routing context an agent needs before calling. It stops short of exclusions such as 'for a single order use get_order' or how this differs from easystore_list_order_transactions / easystore_list_checkouts.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The payment transactions of one order (gateway, amount, status). Needs read_orders. GET /api/3.0/orders/{id}/transactions.json.
| Name | Required | Description | Default |
|---|---|---|---|
| order_id | Yes | EasyStore order id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/openWorld/non-destructive, so the description's added value is the required scope ('Needs read_orders') and the concrete REST endpoint, which tells the agent this is a live remote call. It does not mention pagination or error behavior, keeping it short of 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three compact, front-loaded sentences/fragments with zero padding. The telegraphic style is efficient, though the endpoint path is arguably redundant with the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter read-only list tool with no output schema, the description covers purpose, returned fields, auth scope, and endpoint — enough to call correctly. Missing only minor details like pagination or empty-result behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There is only one parameter (order_id) and schema coverage is 100%, so the schema already fully documents it; 'of one order' merely confirms the singular scope. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ('payment transactions of one order') and names the returned fields (gateway, amount, status). It is clearly distinguishable from siblings like easystore_list_order_fulfillments or easystore_get_order, though it does not explicitly contrast with them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'The payment transactions of one order' implies the use case, and 'Needs read_orders' gives a prerequisite. However, it never states when to prefer this over related tools (e.g. list_order_fulfillments) or what happens if the order has no transactions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the store's content pages. Needs read_content. GET /api/3.0/pages.json.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number, from 1 (default 1). Pass the previous reply's next_page. | |
| limit | No | Results per page, 1-100 (default 25). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so safety is covered. The description adds the auth scope requirement ('Needs read_content') and the underlying endpoint (GET /api/3.0/pages.json), which is exactly the kind of context annotations don't carry. It does not mention result shape, but the schema covers pagination.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences with the core purpose front-loaded and zero filler. The auth scope and endpoint each earn their space as information unavailable elsewhere in the same form.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-required-param read-only list with full schema coverage and annotations, the definition is adequate. But with no output schema, an agent has no idea what a 'page' object contains or what identifiers it can carry forward, which the description could have sketched in a clause.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%; both 'page' and 'limit' have defaults, ranges, and a next_page handoff note in the schema. The description adds nothing about parameters, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: 'List the store's content pages.' An agent can distinguish this from easystore_list_articles, easystore_list_blogs, and easystore_list_collections by the word 'pages', though the description never explicitly contrasts those similar listing siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Needs read_content' provides a real prerequisite for use, but there is no guidance on when to prefer this over easystore_list_articles or easystore_list_blogs, nor any exclusion or alternative routing. Usage is implied by the resource name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List products with variants, prices, SKUs, stock, images and collections. Filter by collection, SKU, published status or dates. Needs read_products. GET /api/3.0/products.json.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number, from 1 (default 1). Pass the previous reply's next_page. | |
| skus | No | Only products with these SKUs, comma-separated. | |
| sort | No | Sort as field.asc or field.desc, e.g. id.asc (a stable order for paging through everything). | |
| limit | No | Results per page, 1-100 (default 25). | |
| since_id | No | Start at this product id (inclusive: id >= since_id). | |
| is_bundle | No | true = only bundle products, false = no bundle products. | |
| visibility | No | Only published or only unpublished products. | |
| collection_ids | No | Only products in these collection ids, comma-separated, e.g. 2311217,2311218. | |
| created_at_max | No | yyyy-mm-dd or yyyy-mm-dd hh:mm:ss, read in the store's own time zone. | |
| created_at_min | No | yyyy-mm-dd or yyyy-mm-dd hh:mm:ss, read in the store's own time zone. | |
| updated_at_max | No | yyyy-mm-dd or yyyy-mm-dd hh:mm:ss, read in the store's own time zone. | |
| updated_at_min | No | yyyy-mm-dd or yyyy-mm-dd hh:mm:ss, read in the store's own time zone. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds useful operational context beyond annotations: it names the required permission (read_products) and the underlying GET endpoint, though it does not discuss rate limits or pagination behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences cover purpose, available filters, required permission, and endpoint with no filler. The key information is front-loaded, and every sentence contributes.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only list tool with full schema coverage and explicit safety annotations, the description is largely complete: it identifies included fields, auth, and endpoint. Minor gaps remain around pagination defaults and result ordering, though those are covered in the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema documents all 12 parameters at 100% coverage, including pagination, sort syntax, SKU format, and date formats. The description adds only a high-level filter summary and no parameter syntax or edge-case details beyond the schema, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource ("List products") and enumerates included data (variants, prices, SKUs, stock, images, collections), which clearly distinguishes it from single-product retrieval tools like easystore_get_product and from easystore_list_product_variants. The added endpoint and filter summary further pin down scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It states what can be filtered (collection, SKU, published status, dates) but does not explicitly say when to choose this over sibling tools such as easystore_get_product or easystore_list_product_variants. Usage is implied rather than guided by conditions or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The variants of one product (price, SKU, barcode, stock, weight, enabled flag). Needs read_products. GET /api/3.0/products/{id}/variants.json.
| Name | Required | Description | Default |
|---|---|---|---|
| product_id | Yes | EasyStore product id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, non-destructive, open-world behavior, but the description adds useful context: the required read_products scope, the endpoint, and the variant fields returned. It does not mention pagination, rate limits, or error behavior, so it stops short of full behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The definition is compact and front-loaded: resource, returned fields, auth requirement, and endpoint each appear in a short fragment. No sentence is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter read tool with rich annotations and full schema coverage, the description supplies enough to call it correctly: product scope, auth scope, endpoint, and return fields. It still omits routing guidance and pagination details, so it is not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and product_id is already documented as an EasyStore product id. The description only reinforces the one-product scope through the endpoint path, adding little beyond the schema baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description identifies the exact resource and scope: variants of one product, with a field list that distinguishes it from easystore_get_product and easystore_list_products. It does not explicitly name a sibling or use the verb 'list' in the prose, so it 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.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit when-to-use or when-not-to-use guidance, and no alternatives such as easystore_get_product or easystore_update_variant are named. 'Needs read_products' is an authorization prerequisite, not usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find customers by exact email, phone number or customer code. Pass at least one. Needs read_customers. GET /api/3.0/customers/search.json.
| Name | Required | Description | Default |
|---|---|---|---|
| code | No | Customer code. | |
| page | No | Page number, from 1 (default 1). Pass the previous reply's next_page. | |
| No | Exact email address. | ||
| limit | No | Results per page, 1-100 (default 25). | |
| phone | No | Phone number as stored, e.g. 601110768827. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover readOnly, openWorld and non-destructive, so the bar is lower; the description still adds two things they do not: the required auth scope ('Needs read_customers') and the exact-match semantics of the lookup keys. It omits return shape and result-count behavior, but the pagination contract is carried by the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, front-loaded with the action and the key constraint, with no filler. The endpoint path is marginally useful but adds little for an agent that already has the tool; minor redundancy against the schema's own field descriptions.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Five optional params, no enums, no output schema, and annotations carrying the safety profile. The description supplies the one thing structured data lacks (at-least-one-key rule) plus auth scope, leaving nothing an agent needs before calling it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline would be 3, but the description adds a constraint the schema does not express at all: no parameter is marked required, yet the description says to pass at least one of email/phone/code. That is genuine semantic value beyond the structured fields.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Find customers') and the three exact-match keys it accepts (email, phone, code), which distinguishes it from easystore_list_customers. It never names the sibling it replaces, so an agent must infer the search-vs-list split from the words 'exact' and 'Find'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Pass at least one' gives a real invocation constraint and 'exact' implies this is not a fuzzy or listing endpoint, so usage is inferable. But there is no explicit statement of when to prefer it over easystore_get_customer (single-record lookup) or easystore_list_customers (browse), which are the two obvious alternatives in the sibling set.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
WRITE. Set the stock of one variant at one location to an exact number (quantity 0 or more). Omit location_id for the primary location. Overwrites the current quantity; use easystore_adjust_inventory_level for a relative change. Needs write_products. PUT /api/4.0/inventory_levels/set.json.
| Name | Required | Description | Default |
|---|---|---|---|
| quantity | Yes | The exact available quantity to set. | |
| variant_id | Yes | Variant id (see easystore_list_product_variants). | |
| location_id | No | Location id (see easystore_list_locations). Default: the primary location. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=true, and the description reinforces this with "Overwrites the current quantity" plus the write_products permission requirement and the concrete endpoint. It stops short of describing the response body or error modes, which keeps it from a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the "WRITE" marker and the core operation, then the alternative, then the auth and endpoint. No sentence is wasted and nothing important is buried.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a three-parameter, two-required write tool with no output schema, the description covers action, scope, defaulting, auth, and the destructive overwrite semantics. The only gap is what the call returns, which is minor since no output schema is promised.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so quantity bounds, variant_id, and the primary-location default are all documented in the schema. The description repeats the location default and the 0-or-more bound but adds no format or semantic detail beyond that, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource with exact scope: "Set the stock of one variant at one location to an exact number." The leading "WRITE" marker plus the contrast with the sibling adjust tool makes it unambiguous without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly names the alternative ("use easystore_adjust_inventory_level for a relative change") and the condition that selects it, plus the location_id omission behavior. An agent can route correctly from this sentence alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
WRITE. Change fields of an existing customer; only the fields you pass change. Needs write_customers. PUT /api/3.0/customers/{id}.json.
| Name | Required | Description | Default |
|---|---|---|---|
| code | No | Your own customer code. | |
| No | Email (unique per store). | ||
| phone | No | Phone number, e.g. +60192233445. | |
| gender | No | Gender. | |
| groups | No | Group names to assign, e.g. ["VIP"]. | |
| birthdate | No | yyyy-mm-dd. | |
| last_name | No | Last name. | |
| first_name | No | First name. | |
| customer_id | Yes | EasyStore customer id. | |
| country_code | No | Two-letter country code, e.g. MY. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=true, so the description's job is lighter. It still adds real value: partial-update semantics (unpassed fields are left alone), the required permission scope, and the exact endpoint. It does not spell out what 'destructive' means here (e.g. that groups replace existing membership), so a 4 rather than 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four compact fragments, front-loaded with the operation class, then the semantic rule, then auth, then endpoint. Nothing is redundant or padded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 10-parameter mutation with no output schema, the definition covers semantics, permission, and endpoint adequately. It leaves the response shape unstated and does not clarify the effect of array fields like groups, a minor gap given rich annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with per-field descriptions, formats, and an enum, so the schema carries parameter meaning. The description only contributes the partial-update rule, which is useful but adds no field-level detail. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Change fields of an existing customer') and adds a scope-defining clause ('only the fields you pass change') that separates it from easystore_create_customer and the get/list siblings. The 'WRITE' prefix telegraphs the operation class immediately.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives concrete preconditions: requires write_customers permission and targets PUT /api/3.0/customers/{id}.json. It does not explicitly name an alternative tool or state when a caller should pick a different sibling, which keeps it below a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
WRITE. Change one variant's price, compare-at price, cost price, SKU, barcode or enabled flag. Only the fields you pass change. To change stock use the inventory tools. Needs write_products. PUT /api/3.0/products/{product_id}/variants.json.
| Name | Required | Description | Default |
|---|---|---|---|
| sku | No | SKU. | |
| price | No | Selling price in the store's primary currency. | |
| barcode | No | Barcode. | |
| cost_price | No | Cost price. | |
| is_enabled | No | Whether the variant can be sold. | |
| product_id | Yes | The product the variant belongs to. | |
| variant_id | Yes | Variant id. | |
| compare_at_price | No | Original price shown struck through. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=true, so the description is not obligated to restate safety. It still adds real value beyond them: 'Only the fields you pass change' documents partial-update semantics, and the write_products scope plus PUT endpoint disclose auth and transport. It does not explain why the operation is flagged destructive or what a successful response contains, keeping it below a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four short sentences, each carrying distinct information (mutation type, mutable fields, partial-update rule, stock alternative, scope, endpoint). The 'WRITE' token is front-loaded so an agent sees the operation class immediately.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers authorization, the partial-update contract, the sibling route for inventory, and the underlying endpoint — enough for an agent to call it correctly given annotations supply the safety profile and there is no output schema. It stops short of describing error conditions or whether unknown variant IDs fail loudly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so every parameter is already documented, including units ('store's primary currency') and bounds. The description's field list mirrors the schema rather than adding syntax, format, or edge-case guidance, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Opens with an explicit 'WRITE' marker and a specific verb+resource ('Change one variant's ...'), then enumerates exactly which fields are mutable. An agent can distinguish this from easystore_list_product_variants and easystore_adjust_inventory_level without opening a schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
States the exclusion explicitly ('To change stock use the inventory tools'), names the required scope ('Needs write_products'), and gives the endpoint. The alternative path for stock mutation is spelled out rather than left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
easystore_adjust_inventory_leveleasystore_cancel_ordereasystore_create_customereasystore_create_fulfillmenteasystore_get_collectioneasystore_get_customereasystore_get_customer_pointseasystore_get_ordereasystore_get_producteasystore_get_storeeasystore_list_articleseasystore_list_blogseasystore_list_checkoutseasystore_list_collectionseasystore_list_customer_addresseseasystore_list_customer_groupseasystore_list_customerseasystore_list_inventory_levelseasystore_list_locationseasystore_list_order_fulfillmentseasystore_list_order_transactionseasystore_list_orderseasystore_list_pageseasystore_list_product_variantseasystore_list_productseasystore_search_customerseasystore_set_inventory_leveleasystore_update_customereasystore_update_variantRead Sapo store products, orders, customers and stock levels; edit order notes and stock.
Read Megaventory products, stock, orders and partners; create clients, sales and purchase orders.
Read KiotViet products, customers, invoices, orders and stock; create customers and orders.
Read Veeqo orders, products, stock, warehouses, customers and POs; add notes, tag, set stock.
Add one secure layer between your agents and this server.