ecwid

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

The description explicitly states it 'MODIFIES live store data', aligning with the destructiveHint annotation. It provides additional behavioral context (delta vs absolute, return shape) beyond the annotation. No contradictions.

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

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

Two sentences convey purpose, usage, and return shape. Efficient but includes some technical REST detail that could be secondary. No wasted 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 simple mutation tool with 2 parameters and no output schema, the description covers purpose, parameters, effect, and return format. Lacks explicit mention of error conditions or idempotency, but adequate for the complexity.

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

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

Schema coverage is 100% with both parameters described via JSON schema. The description reiterates the delta meaning but adds minimal extra value (e.g., example endpoint). Baseline 3 is appropriate.

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

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

The description uses the verb 'ADJUSTS' with a specific resource ('product's in-stock quantity') and clearly distinguishes from sibling tools which are primarily read operations (get, list, search) or update_order. The mention of modifying live store data and the API endpoint further clarifies the purpose.

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

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

The description explains the tool modifies stock via delta and the direction of change, but does not explicitly state when to use this tool over alternatives. Sibling tools are all different (no similar inventory tools), so implicit differentiation exists, but no when-not or prerequisites are given.

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

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

Annotations already declare readOnlyHint=true, so the description's addition of fields returned (name, parent, product ids, images) provides some context. However, it does not disclose any additional behavioral traits like authentication requirements or error handling, which are not expected given the simplicity of the tool.

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

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

The description is two sentences with no extraneous information. The first sentence states the purpose and included fields, the second provides the REST endpoint. Every word earns its place.

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

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

Given the tool's simplicity (1 parameter, no output schema), the description adequately covers what the tool returns. It mentions the key fields. It could be slightly more complete by noting the return format, but for a single-category retrieval, this is sufficient.

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

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

The input schema has 100% description coverage (category_id with type and description), so the schema already explains the parameter. The tool description does not add any extra meaning beyond what is in 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 the verb ('Get'), resource ('single category'), and identifier ('by id'), and lists included fields (name, parent, product ids, images). It also provides the REST endpoint. This distinguishes it from sibling tools like ecwid_list_categories and ecwid_get_product.

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

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

The description provides clear context on when to use the tool: to get a single category by id. It does not explicitly state exclusions or alternatives, but the context from sibling tools (e.g., ecwid_list_categories for listing) implies the appropriate use case.

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

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

Annotations already provide readOnlyHint=true, so the description's disclosure of returned fields adds value. However, it does not mention error handling or what happens if the customer doesn't exist.

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 concise sentences with no wasted words. Front-loaded with the action 'Get' and includes essential details efficiently.

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

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

For a simple single-parameter tool with no output schema, the description adequately covers the return value (contact details, addresses, customer group) and completes the context needed for an agent to use it correctly.

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

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

The schema covers 100% of parameters with a description for customer_id. The description reinforces it's 'by id' but adds no new semantic meaning beyond the schema.

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

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

The description clearly states the action (get), resource (customer by id), and what is included (contact details, addresses, customer group). It also provides the REST endpoint, making the purpose unambiguous.

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

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

The description implies usage when you have a customer id, but no explicit guidance on when to use this versus sibling tools like ecwid_search_customers. It lacks when-not-to-use or alternative suggestions.

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

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

Annotations already declare readOnlyHint=true, so description is not required to restate. It adds value by specifying what data is returned (line items, totals, etc.) and the API endpoint, providing context beyond the safe-read flag.

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?

Single sentence plus REST endpoint. All information is relevant and front-loaded. No extraneous content.

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

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

Given the simple input (one parameter), annotations (readOnlyHint), and no output schema, the description adequately covers the purpose, return data, and usage. No gaps for an agent to misinterpret.

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 'Order number (the store-visible order id).' The tool description does not add new parameter details, staying at baseline. No additional clarity needed but also no extra value.

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

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

Description clearly states the verb ('Get'), resource ('order by its order number'), and the data included ('line items, totals, customer, and payment/fulfillment status'). It distinguishes from siblings like 'ecwid_search_orders' (which lists multiple) and 'ecwid_update_order' (mutation), despite not naming them 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?

The description implies use when a single order is needed by number, but does not explicitly address when not to use or mention alternatives such as 'ecwid_search_orders' for filtering. Slightly lacking in decisional guidance.

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

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

Annotations already declare readOnlyHint=true. The description adds context about the returned data (price, stock, etc.) and the underlying REST endpoint, but does not disclose authentication needs, rate limits, or error cases. No contradiction with annotations.

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, front-loaded with the core purpose. Every sentence adds value: purpose and scope in first, API reference in second. No excess 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?

Given the tool's simplicity (single parameter, no output schema), the description adequately covers what the tool does and what data is returned. Could optionally mention error handling (e.g., product not found) but not essential for this level of completeness.

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

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

Schema coverage is 100%: the only parameter (product_id) is fully described in the schema. The description only repeats 'by its id', adding no new semantic information beyond what the schema provides.

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

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

The description clearly states the verb 'Get' and the resource 'single product by its id', specifying included fields (price, stock, options, images, category assignments). It distinguishes from siblings like ecwid_search_products (list/search) and ecwid_adjust_product_inventory (mutation).

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

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

The description implies usage for fetching a specific product by ID, but does not explicitly state when to use this tool versus alternatives (e.g., ecwid_search_products for filtered lists). No exclusion or context for when not to use.

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

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

Annotations already declare readOnlyHint=true. The description adds minimal behavioral insight beyond mentioning the REST endpoint. No additional traits like rate limits, authentication, or side effects are disclosed.

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?

One short sentence with no unnecessary words. Purpose is front-loaded and every part is informative.

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

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

For a parameterless read-only tool, the description is nearly complete. It lacks details about the return format or structure, but given the simplicity, it is adequate.

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 are no parameters; schema description coverage is vacuously 100%. Baseline is 4 as per guidelines.

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 clear verb 'Get' and specifies the resource 'store's profile', listing included info (id, name, currency, company details, settings). It is distinct from all sibling tools, which operate on different entities.

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 does not explicitly state when to use this tool versus alternatives, but the context makes it clear that it is the only tool for retrieving the store profile. Guidance is adequate given the uniqueness.

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

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

Annotations already declare readOnlyHint=true, and the description adds that it returns a paged collection, which is behavioral context beyond annotations. No contradiction; the description reinforces a safe read operation.

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

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

Three sentences, each serving a purpose: action+options, return type, and API reference. No redundancy, though the REST endpoint might be seen as extra. Front-loaded with key info.

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

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

Given the tool's simplicity (4 parameters, no output schema, no nested objects), the description covers the essential behavior: listing categories with filters and paging. It is complete enough for an agent to select and invoke correctly.

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

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

Schema description coverage is 100% (all 4 parameters have descriptions in the schema). The description repeats 'optionally scoped to a parent category and including hidden ones' but does not add new meaning beyond the schema's parameter descriptions. Baseline 3 is appropriate.

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

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

The description clearly states the action (list categories) and the resource (store's product categories), with optional scoping and hidden categories mentioned. It distinguishes itself from sibling tools like ecwid_get_category by focusing on listing and paging.

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

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

The description provides usage context (optional parent, hidden categories, paged collection) but lacks explicit when-to-use or when-not-to-use guidance compared to alternatives. No exclusion criteria or sibling differentiation is stated.

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

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

Annotations declare readOnlyHint=true, and the description aligns by noting it returns a paged collection. It adds context about pagination and the REST endpoint, but does not contradict annotations.

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 three concise sentences: action and filters, result format, API reference. No unnecessary words, and key information is front-loaded.

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

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

For a simple listing tool with good schema annotations, the description covers the essentials. It could mention default ordering or response shape, but the paged collection hint provides sufficient context given no output 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% with each parameter already described. The description only summarizes the filters without adding new meaning, so it meets the baseline for high coverage.

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

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

The description clearly states the action ('List the store's discount coupons') and specifies the resource (discount coupons). It also lists optional filters, distinguishing it from sibling tools that operate on different entities.

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?

While no explicit when-to-use or alternative guidance is provided, the tool's name and description make its purpose unambiguous. Since no sibling tool serves a similar function for discount coupons, the lack of exclusion criteria is acceptable.

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

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

Annotations declare readOnlyHint=true, indicating a safe read operation. The description adds value by specifying 'Returns a paged collection', which informs the agent about pagination behavior, and mentions the REST endpoint. This goes beyond the annotation alone.

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, no redundancy. Front-loaded with the core purpose and filters, followed by pagination and API reference. Every word earns its place.

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 search/list tool with 6 optional parameters and no output schema, the description adequately states it returns a paged collection. Missing details like sorting or default behavior, but overall sufficient for an agent to understand the tool's function.

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 parameters are documented in the schema. The description lists 'keyword, email, name, customer group' but adds no significant meaning beyond the schema descriptions. Baseline 3 is appropriate.

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

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

The description clearly states 'Search / list the store's customers with optional filters', specifying the verb (search/list) and resource (customers). It distinguishes from sibling tools like ecwid_get_customer (single) and ecwid_search_orders. The mention of 'paged collection' and API endpoint adds clarity.

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

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

The description implies usage for searching or listing customers with filters, but does not explicitly state when to use this tool versus alternatives (e.g., ecwid_get_customer for a specific customer). No exclusion or when-not-to-use guidance is provided, though sibling context exists.

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

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

Annotations already declare readOnlyHint=true. The description adds value by stating 'Returns a paged collection' and the REST method (GET /orders), providing behavioral context beyond the annotation. No contradictions.

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

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

Three sentences, each adding distinct information: purpose with filters, return type, and API reference. No redundant or filler content. Every sentence earns its place.

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, but the description notes 'Returns a paged collection.' It could clarify the structure of items (order objects) but the sibling ecwid_get_order provides detail. All 10 parameters are covered in schema. Mostly complete for a search tool.

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

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

Schema description coverage is 100%, so each parameter is already documented. The description summarizes filter groups (e.g., 'keyword, customer email/id') but adds no new meaning beyond grouping. Baseline 3 is appropriate.

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

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

The description uses specific verbs 'Search / list' combined with the resource 'the store's orders' and lists filter categories, clearly distinguishing it from sibling tools like ecwid_get_order (single order) or ecwid_list_categories (different resource).

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

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

The description implies usage via 'with optional filters' but does not explicitly state when to use this tool over alternatives (e.g., ecwid_get_order). No exclusions or when-not-to-use guidance is provided, so it's adequate but not explicit.

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

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

The description reveals that the tool returns a paged collection with specific fields ({total, count, offset, limit, items}) and uses a GET request, which aligns with the readOnlyHint annotation. This adds useful behavioral context beyond annotations, though it does not mention potential rate limits or performance constraints.

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 two concise sentences that front-load the core purpose and list key features, with no extraneous words. Every sentence adds value.

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

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

Given the tool's complexity (10 optional parameters, no output schema), the description covers the search capability and pagination shape adequately. It could mention how filters combine or default behaviors, but it is still fairly complete for the agent.

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

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

Schema description coverage is 100%, so parameters are already well-documented. The description adds minimal extra context, such as noting that 'keyword' matches title/description/SKU and that category 0 is root, but this does not significantly enhance the schema's clarity. Baseline of 3 is appropriate.

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

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

The description clearly states 'Search / list the store's products' with specific filter options and sorting, establishing a clear verb and resource. However, it does not explicitly distinguish from the sibling tool 'ecwid_get_product' for retrieving a single product, so it gets a 4 rather than 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?

The description lists available filters but provides no guidance on when to use this tool instead of alternatives like ecwid_get_product or ecwid_adjust_product_inventory. There is no mention of when not to use it or specific contexts that warrant its use.

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

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

Discloses that it modifies live store data and may trigger customer notifications, adding context beyond the destructiveHint annotation. Also mentions the REST API 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?

Two concise sentences: first states purpose and scope, second adds behavioral context and API details. No wasted 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?

Covers purpose, updates fields, side effects, and API endpoint. Lacks explicit sibling differentiation but given low complexity and good annotations, it's largely 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 coverage is 100%, so baseline is 3. Description adds value by explaining partial updates ('Provide only the fields you want to change') and mentioning return {updateCount}, though not in 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?

Clearly states it updates an order, specifying the exact fields (payment status, fulfillment status, tracking number). Distinguishes from sibling tools like ecwid_get_order (read-only) and ecwid_search_orders (search).

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?

Instructs to 'Provide only the fields you want to change', indicating partial updates. No explicit when-not-to-use or alternatives, but context implies usage for modifying order fields.

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