Lightspeed Retail (X-Series) MCP by usefulapi

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

Annotations already declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false, so the safety profile is covered. The description adds a genuinely non-obvious constraint beyond structured data: the schema lists zero required parameters, but the tool actually requires at least one of first_name/last_name/company_name. It does not say what happens on a rejected or duplicate create.

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 operation type and immediately followed by the actionable constraint and the duplicate check. The trailing 'POST /customers' adds little for an agent but costs almost 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?

For a 20-parameter mutation with no output schema, the description covers the essential precondition and the duplicate guard, but omits what the response contains (e.g., the newly created customer id needed for follow-up calls) and how most optional fields behave.

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?

With 20 parameters and only 25% schema description coverage, the description must carry meaning about the fields but mentions only the name trio. Address, loyalty, consent, and customer_code parameters are left entirely to bare schema property names, so the coverage gap is not compensated.

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 new customer') and prefixes it with 'WRITE', making the operation type unambiguous. It is distinguishable from update_customer and get_customer, though it never explicitly names update_customer as the mutation 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?

Explicitly directs the agent to run search_customers first to avoid duplicates, which is a real alternative-tool routing rule. It also gives the precondition that at least a first name, last name, or company name must be supplied, though it does not cover failure behavior or when-not-to-use cases.

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?

readOnlyHint=true already declares the safety profile, so the description needs only to add context. It contributes the HTTP endpoint and the domain scope (which record types are covered), which is modest added value; it says nothing about 404/not-found behavior or what happens for cancelled/void consignments.

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 with zero filler, and the identifying information (what is returned, keyed by what) comes first. The endpoint path is compact and useful for agents reasoning about the underlying API.

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 single-record fetch with full parameter documentation and readOnlyHint, the description covers what is needed to select and invoke it. The one gap is that no output schema exists and the description does not hint at the return shape, so the agent cannot anticipate the response fields.

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 there is a single required parameter whose pattern and provenance ('from list_consignments') are already documented in the schema. The description adds nothing about the id's format or source, so it sits at the 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?

States the specific resource (one consignment) with the qualifier 'by id' and enumerates the underlying record types (stock order, transfer, stocktake, return), so the agent knows exactly what is fetched. It does not name list_consignments as the contrasting sibling, but 'by id' plus the singular framing makes the single-vs-list 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 only implied: the id-based framing signals 'call this when you already have a consignment id'. The schema note '(from list_consignments)' carries the workflow hint, but that lives in structured data, not the description. No explicit when-not or alternative guidance is offered.

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's 'GET /customers/{customer_id}' is consistent with that. It adds the set of fields returned, but does not cover error behavior, permissions, or response shape beyond the field list.

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 compact sentence front-loads the key information (single customer by id), lists the returned fields, and ends with the endpoint. No wasted text.

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 lookup with one fully documented parameter and no output schema, the description is nearly complete because it enumerates the returned fields. Minor gaps remain around error handling and exact response structure.

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 customer_id documented as coming from search_customers or list_customers. The description adds no further meaning about the parameter, 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?

States a specific verb and resource ('One customer by id') and enumerates the returned data (contact details, addresses, customer group, balance, loyalty balance, YTD spend), which distinguishes it from list/search siblings. The endpoint is also included.

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: fetch a single customer when you already have an id. It does not explicitly say to use search_customers or list_customers to obtain an id or when not to use this tool, though the schema description mentions this.

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, but the description adds real value beyond them: it pre-empts the POST-body confusion ('Read-only even though the vendor takes the filter as a POST body') and describes paging behavior (pass next_offset, null = last page). It says nothing about permissions, rate limits, or error behavior, so not 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-loads the returned fields, then filters, then paging — a sensible order with no filler. It is dense and long, but the field enumeration earns its place because there is no output schema. Slightly overpacked into one paragraph where a break before paging would aid scanning.

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 list is necessary and present; with 12 optional params, filtering and paging semantics are the critical parts and are covered. The remaining gaps (sort_type/sort_direction meaning, include_composites, include_inactive) are minor for a read tool flagged readOnly.

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 67%, and the description compensates for the most consequential gaps: it explains the outlet_ids/location_ids naming, the product_ids vs root_product_ids exclusion, and precisely what to_be_procured_only means versus a below-reorder-point list. However, size (max 500), sort_type, sort_direction, include_inactive, and include_composites are left to the schema, and sort_type's enum values carry no description at all.

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 precise verb+resource ('Stock on hand per product per outlet') and enumerates the returned fields, so an agent immediately knows this is a per-outlet inventory read rather than a product or sales listing. It is clearly separable from siblings like list_products or search_products.

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 explicit conditional guidance: use to_be_procured_only for the vendor's re-order suggestion (accounting for open orders), and compare current_inventory_level with reorder_threshold yourself for a plain below-reorder-point list. Also states product_ids and root_product_ids are mutually exclusive. It does not name a sibling alternative, which keeps it a 4 rather than 5.

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 agent knows this is a safe read. The description adds the API endpoint and singular-retrieval scope, but it does not disclose not-found behavior, permission requirements, or return characteristics.

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 no wasted preamble. The endpoint fragment is somewhat redundant but still useful as compact 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 simple one-parameter read with full schema coverage and a readOnly annotation, the description is minimally adequate. It leaves out operational details such as error behavior, which would help an agent invoke it confidently.

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 the schema itself says 'Outlet id (from list_outlets).' The description adds no parameter meaning beyond that, so the baseline score of 3 is appropriate.

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

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

The description states a specific resource and scope: 'One outlet by id.' It is clear enough to distinguish a single-outlet lookup from broad list operations, though it does not explicitly name or contrast with the sibling list_outlets tool.

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 guidance on when to use this tool versus list_outlets or another outlet-related operation. The phrase 'by id' only weakly implies that it should be used when an outlet id is already known.

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 only declare readOnlyHint=true, so the description carries the burden of disclosure and does well: it names the returned sub-resources and clarifies the entity is a variant, not a parent product. It also gives the underlying endpoint GET /products/{product_id}, which helps an agent reason about failure modes. Missing error behavior (e.g. 404 on unknown id) 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?

Two sentences, zero padding, with the payload description and endpoint front-loaded. Every clause (variant distinction, returned fields, endpoint) 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, the description's enumeration of returned fields (prices, codes, suppliers, outlet taxes) is what tells the agent whether it needs a follow-up call. For a 2-parameter read tool with full schema coverage, that is nearly sufficient; only the `includes` expansion behavior and error semantics remain undescribed.

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%, and the `includes` parameter comes with a substantive caveat about 'families' being required alongside brands/categories/etc., so the schema does the heavy lifting. The description adds no meaning beyond 'by id' and never mentions that related records are opt-in via includes.

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 ('One product (variant) by id') and lists the payload contents (prices, codes, suppliers, outlet taxes), which is more precise than the title 'Get product'. It implicitly separates itself from list_products/search_products by being a single-record fetch, but never names those 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?

Usage is only implied: 'by id' signals you must already have an identifier, and the schema note '(from list_products)' hints at the discovery path. There is no explicit guidance on when to prefer this over search_products or list_products, and no exclusion criteria.

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 safety is covered. The description adds useful behavioral scope by specifying 'since it was opened' and 'by payment type', but it does not describe auth requirements, rate limits, or response shape beyond the basic result content.

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 short sentences with the key scope and use case front-loaded. There is no filler, and the endpoint reference is compact.

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 single-parameter tool with no output schema, the description supplies enough scope and result meaning (payment totals by payment type since opening) for an agent to call it correctly. Return format details are not provided, but they are not essential for invocation here.

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 the schema itself explains that register_id comes from list_registers. The description does not add parameter-specific syntax or meaning beyond what the schema already provides, so the baseline of 3 is appropriate.

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

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

The description states a specific outcome (payment totals by payment type) and a clear scope (one register, since it was opened). It is easy to distinguish from list/register tools, though it does not explicitly name sibling alternatives such as sales_summary.

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 'end-of-day / cash-up view' gives a clear usage context for when an agent should select this tool. It does not state when not to use it or name a specific alternative, but the intended scenario is clear.

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 is consistent with that ('GET /retailer'). Beyond annotations it discloses the exact payload contents, which is valuable given there is no output schema, and adds operational guidance about the time zone field.

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 tight sentences plus the endpoint line, front-loaded with what the resource is before the workflow tip. No filler or restatement of the 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 zero-parameter read with no output schema, the description fully compensates by enumerating every returned field and explaining how to use one of them. An agent has everything needed to call it and interpret the result.

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; there is nothing for the description to disambiguate. No parameter-level detail is needed or missing.

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 (the connected store/retailer) and enumerates exactly what the response carries: id, name, domain prefix, store URL, country, currency, time zone, tax and loyalty/gift-card settings. The phrase 'the connected store' plus the closing 'GET /retailer' distinguishes it from siblings like get_outlet or list_users.

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 recommends it as a first call and gives a concrete downstream use — 'use the time zone to turn a local day into UTC for sales searches' — which tells the agent when to reach for it. It stops short of naming an alternative tool to avoid, but no true alternative exists for this data.

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?

readOnlyHint=true already covers the safety profile, so the bar is lower. The description nevertheless adds real value by disclosing the payload contents — line items, payments, taxes and totals — which tells an agent what data is available without needing to inspect the response first. No contradictions with the annotation.

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 with no filler: the payload contents come first, followed by the endpoint. Every clause 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 simple one-parameter read with no output schema, the description covers the essentials by enumerating the returned components. It stops just short of mentioning not-found or error behavior, which is a minor omission.

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% and the sale_id parameter is already fully documented in the schema, including its pattern and provenance ('from list_sales or search_sales'). The description adds nothing beyond that, which is the expected baseline for a fully documented single 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 verb and resource ('One sale by id') plus the scope of what's returned. 'By id' distinguishes it from list_sales and search_sales, which return collections rather than a single sale.

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: fetch a single sale when you have its id. But the description never explicitly says when to prefer this over list_sales or search_sales, nor what happens with an unknown id. The routing hint 'from list_sales or search_sales' lives in the schema, not in the description.

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?

readOnlyHint already covers the safety profile, and the description adds real behavioral context: totals are vendor-computed and unfiltered by date, plus the underlying endpoint. It does not describe what the totals contain, but for a read-only aggregate that is a modest gap rather than a blocker.

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 compact clauses: the purpose leads, the disambiguation follows, and the endpoint trails as reference. 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 single-parameter read tool with full schema coverage and a readOnly annotation, the description covers what is needed to select and call it. Only the shape of the returned totals is left implicit, which is acceptable without an output schema but would be nice to have.

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% and user_id already documents its source (list_users). The description only reinforces the semantic that the user is a staff user, adding little 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?

States a specific verb and resource (sale totals for one staff user) and immediately disambiguates from the sibling sales_summary by noting there is no date filter. An agent can distinguish this tool from nearby siblings 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?

Explicitly names the alternative ('use sales_summary for a period') and the condition that selects it. Both the when-to-use and when-not-to-use are 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?

readOnlyHint=true already declares the safety profile, so the bar is lower. The description does add that results are id/name pairs retrieved via GET /brands and that pagination uses next_after, but it says nothing about ordering, rate limits, or whether deleted brands appear (that is only in the schema).

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

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

Three terse fragments, front-loaded with the resource and return shape before pagination and endpoint details. Nothing extraneous 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 no output schema, the description usefully names the returned fields (id, name) and the pagination cursor, but omits result ordering and total-count behavior that an agent consuming the list might want. Adequate for a simple read-only reference 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%, and each parameter already documents cursoring, deleted-record inclusion, and page size with vendor context. The description's 'Paginate with next_after' merely echoes a note already present in the 'after' parameter description, adding no new semantics.

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 brands') plus the returned fields (id, name) and the underlying endpoint (GET /brands). A 'brands' resource is clearly distinct from siblings like list_products or list_tags, though the description never explicitly contrasts 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 only procedural guidance is 'Paginate with next_after', which covers the mechanics of iteration but not when to choose this tool over list_products or search_products. Usage is largely implied by the tool name for a simple reference-list endpoint.

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 readOnlyHint annotation already establishes that this is a safe read operation. The description adds useful behavioral context beyond annotations by listing the returned product-line fields and explaining pagination termination, though it does not cover auth requirements or rate limits.

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

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

The description is compact and front-loads the key information: the scope, returned fields, pagination rule, and endpoint. Every sentence carries useful signal 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?

With no output schema, the description does well to enumerate the returned fields and explain how to paginate. It is nearly complete for a read-only list tool, though it could clarify field meanings or mention any auth context.

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 well documented in the input schema. The description mentions pagination via next_after but does not add parameter-level meaning beyond what the schema provides, making the baseline 3 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 identifies the resource as the product lines of one consignment and lists the returned fields, so the tool's purpose is readily understandable. It does not explicitly distinguish itself from sibling tools such as list_products or get_consignment, which keeps it below 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 pagination instruction ('Paginate with next_after (stop when data is empty)') gives operational guidance for using the cursor. However, there is no explicit guidance on when to use this tool versus alternatives like get_consignment or list_products, so usage context is only implied by the consignment scope.

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 readOnlyHint annotation already covers safety, so the description adds useful behavioral detail by explaining the pagination cursor (next_after) and the returned dimensions (outlet, supplier, due/received dates, totals). It does not cover rate limits or response envelope details, but it exceeds the annotation baseline.

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 a single dense but front-loaded passage with no filler. The core purpose, type/status enumerations, pagination hint, and endpoint are all packed 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 read-only list tool with no output schema, the description provides enough context: what is listed, what filters exist, what fields are returned, and how to paginate. It lacks explicit sibling differentiation, but otherwise an agent has what it needs to call the tool 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 coverage is high (83%), but the description adds meaningful semantics beyond the raw enum labels: it maps SUPPLIER to supplier stock orders, OUTLET to transfers between outlets, and clarifies the status groups. It does not add much for after/before/page_size beyond what the schema already 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 a specific verb and resource: it lists consignments and enumerates the four subtypes (SUPPLIER, OUTLET, STOCKTAKE, RETURN). It implicitly distinguishes itself from get_consignment by being a list operation, but it does not explicitly name siblings or contrast with list_consignment_products.

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 gives filtering context (type, status, outlet, supplier, dates) but never explicitly states when to use this tool versus get_consignment or list_consignment_products. Usage is implied by the listing/filtering language rather than stated as 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?

readOnlyHint=true already tells the agent this is a safe read, so the description's main added value is the pagination instruction ('Paginate with next_after') and the endpoint. It doesn't disclose defaults like active-only vs deleted records or termination behavior, which the schema happens to cover instead.

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: what it returns, how to use the result, how to paginate. Front-loaded, no filler, and each sentence carries distinct 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 simple read-only list tool with annotations and a fully described schema, this is nearly complete: it names the return fields and the pagination cursor. Only minor gaps remain around default filtering behavior on the response side, which the parameter schema largely implies.

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 four parameters (after, before, deleted, page_size) are already fully documented with cursor semantics and page-size advice. The description only echoes the pagination hint ('next_after'), adding little beyond the schema; 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?

Specific verb+resource ('List customer groups') with the returned fields (id, name) and endpoint stated, so an agent knows exactly what it retrieves. It doesn't explicitly contrast with list_customers or search_customers, leaving differentiation to the tool name.

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 gives downstream usage ('Use the id as customer_group_id when creating or updating a customer') and pagination guidance, which is useful context. However, it never states when to choose this tool over the sibling list_customers/search_customers calls or what prerequisites exist.

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?

readOnlyHint=true already covers the safety profile, and the description adds genuinely useful behavior: version-order sorting, the returned field set, and the pagination stop rule. It stops short of describing page-size defaults or what version numbers mean, but the essentials for correct iterative calls are present.

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, no filler: purpose and field list first, then the alternative route, then the pagination rule. Every clause carries operational 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, the description compensates by enumerating returned fields and explaining the cursor flow, which is what an agent needs to consume results. It could say more about the shape of the response envelope (where next_after lives), 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 coverage is 100%, so after/before/deleted/page_size are already fully documented in the schema. The description's mention of version ordering and next_after adds only marginal framing beyond what the parameters already say.

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 customers), names the exact fields returned, and distinguishes itself from search_customers by scope. An agent can identify it against siblings like get_customer or search_customers 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?

Explicitly routes name/email lookups to search_customers and gives the pagination loop plus termination condition ('stop when data is empty'). The only gap is that it says 'next_after' while the input parameter is named 'after', but the schema description reconciles this.

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 safety profile is covered. Beyond that, the description adds valuable behavioral context by listing the returned fields and mentioning pagination via next_after, though it does not discuss auth, rate limits, or the deleted-record behavior covered 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?

The description is short, front-loaded, and structured as an imperative list of what is returned, how it is used, and how to paginate. No sentence feels wasted or 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 simple read-only list tool with annotations covering safety and a fully documented schema, the description provides enough context: returned fields, pagination cue, downstream use, and endpoint. It is slightly less complete because it does not mention optional deleted-record handling, but that is well covered by 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?

Schema description coverage is 100%, so all four pagination-related parameters are already documented in detail. The description only briefly mentions 'Paginate with next_after', which does not add meaningful semantics beyond the schema's own cursor instructions.

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 gives a specific verb and resource ('List the store's outlets (locations)') and even enumerates returned fields and the endpoint. It is clearly distinguishable from the singular sibling 'get_outlet' because it describes enumeration rather than retrieval of one outlet.

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 useful context by explaining that the returned outlet id should be used to filter sales, stock and stock orders. However, it does not explicitly state when to use this instead of the sibling 'get_outlet', so the alternative-selection guidance is only implied.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered; the description adds genuinely useful behavior — the family-name gap and how to close it, the next_after cursor loop with its stop condition. Notably it does not mention rate limits or whether the cursor is version-based (the schema says the cursor is a version number, the description never reconciles this), so it is good but not rich on operational traits.

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 dense sentences plus an endpoint, each carrying distinct information: field inventory, the family/name caveat, pagination, sku override, and sibling routing. The critical caveat (name lives on the family) is front-loaded rather than 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?

No output schema exists, so the description takes on the job of enumerating returned fields (id, family_id, sku, variant_name, prices, active, codes, suppliers, version) and it does. Combined with pagination and sibling routing, an agent has everything needed to call 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 coverage is 100%, so baseline is 3; the description earns above baseline by explaining the includes=["families"] dependency for retrieving names and by tying pagination to next_after from the previous response. It stops short of the version-based semantics of `after`, which is the one non-obvious mechanic left unaddressed.

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 products/variants in the catalog) and immediately disambiguates the variant-vs-family model, which is the key conceptual trap here. An agent can distinguish it from get_product and list_consignment_products 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?

Explicit routing: text/brand/supplier filters belong to search_products, stock belongs to get_inventory_levels, and setting sku overrides all other filters. The when-not and the alternative are both named, leaving nothing to inference.

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, so the safety profile is covered; the description still adds useful context by naming the response fields and disclosing cursor-based pagination through next_after. It doesn't mention rate limits or whether deleted registers appear, but that is a minor gap given 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 tight fragments: what is returned first, then pagination note, then endpoint. No filler or redundancy; every element is useful.

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 full schema coverage and a readOnly annotation, the definition supplies enough: resource identity, returned fields, pagination cue, and endpoint. Only the absence of any output schema means return shape is described by field enumeration rather than a formal contract, which is acceptable here.

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 of the four parameters fully documented (cursor semantics, deleted flag, page_size guidance). The description's 'Paginate with next_after' adds only a pointer that the schema already explains in detail, so 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 registers (tills)') and enumerates the returned fields (id, name, outlet_id, is_open, open/close times, invoice numbering). This is clearly distinguishable from siblings like get_register_payments_summary, though the description doesn't name any sibling 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?

Usage is implied: use this to enumerate tills before working with a specific register. It mentions pagination via next_after but gives no when-to-use/when-not guidance or any comparison to alternatives such as list_outlets or the register payments summary tool.

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 real context beyond that: the feed is ordered by version ascending, it has no date filter, pagination uses next_after and terminates when data is empty, and it enumerates the returned fields. The stop condition for pagination is the kind of operational detail annotations cannot express.

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?

Ordering and sync purpose come first, the exclusion second, then the payload shape and the pagination recipe. Every clause carries information; there is no filler or 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?

No output schema exists, and the description compensates by listing the returned per-sale fields (id, date, invoice_number, state, customer_id, source, payments, line_items, totals). Combined with the pagination termination rule, an agent has everything needed to call and consume this 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%, so 'after', 'before', and 'page_size' are already fully documented. The description reinforces the pagination loop ('Paginate with next_after, stop when data is empty') but adds no format or constraint detail beyond the schema, and never mentions 'before'. Baseline 3 is appropriate when the schema carries the weight.

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 (sales) plus its ordering semantics (version order, oldest changes first) and its intended use (sync everything that changed). It explicitly carves itself out from search_sales and sales_summary with 'It has NO date filter', so an agent can distinguish it from siblings without reading either 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?

Gives explicit when-to-use ('the way to sync everything that changed') and explicit when-not-to-use with the named alternatives ('for a period use search_sales or sales_summary'). The condition selecting the alternative is fully stated, not inferred.

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?

readOnlyHint=true already declares this as a safe read. The description adds useful behavioral detail: the fields returned and the pagination cursor flow. It does not mention deleted-record inclusion or page limits, but those are covered 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 purpose and returned fields, followed by pagination and endpoint. 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?

With no output schema, the description usefully names the returned fields, and the schema handles all parameter detail. Authentication and rate-limit context is absent, but nothing critical for calling the tool correctly 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 all four pagination parameters are fully documented in the schema. The description reinforces the next_after loop but adds no new parameter semantics beyond that; 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 suppliers') and enumerates the returned fields (id, name, default markup, contact details), plus the underlying endpoint. No supplier-related sibling exists to differentiate from, so the lack of explicit sibling routing is not a real gap.

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 pagination instruction ('Paginate with next_after') implies the read/list use case, but there is no explicit when-to-use guidance or exclusion. Usage is implied rather than 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 already declare readOnlyHint=true, so the safety profile is covered. The description adds the pagination mechanism (next_after) and the GET /tags endpoint, but says nothing about auth needs, rate limits, default ordering, or whether deleted tags are included (the schema covers the deleted 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?

Three terse fragments with zero waste, and the core purpose and returned fields are front-loaded before pagination and endpoint details. Nothing could be removed without losing 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 simple read-only list tool with a fully documented schema and readOnly annotation, the description gives the essential shape: what is listed, what fields come back, and how to paginate. It omits only minor details like default sort order or result ordering, which are not critical for correct invocation.

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 four parameters (after, before, deleted, page_size) are already well documented, including cursor semantics and page-size advice. The description's mention of next_after adds nothing 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?

The description names a specific verb and resource (list product tags) and even lists the returned fields (id, name), so the agent knows exactly what it retrieves. It does not explicitly differentiate itself from siblings like list_brands or list_taxes, leaving that inference to the agent.

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 guidance on when to use this tool versus the many other list endpoints, nor any stated prerequisites or exclusions. The 'Paginate with next_after' note is procedural, not conditional usage 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, so the safety profile is covered. The description adds real context beyond that: the response is a non-paginated full list, and the endpoint (GET /taxes) is disclosed. It does not describe ordering or error behavior, keeping it at a 4.

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

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

Two short sentences with zero waste. The primary purpose is front-loaded, followed immediately by the operationally useful no-cursor note and endpoint.

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 input parameters and no output schema, the description carries the burden of return shape, and it does so by naming the fields returned. The structure of the 'rates' sub-object is not spelled out, a minor gap for a tool this simple.

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 there are no parameter semantics to compensate for. The field list in the description pertains to output, not input, and is a bonus rather than a requirement here.

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 tax groups and their rates' – and enumerates the returned fields (id, name, is_default, rates), which clearly separates it from sibling list tools like list_brands or list_tags. Sibling differentiation is implicit rather than explicit, so it falls just short of a 5.

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

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

There is only one tax-related tool among the siblings, so usage is largely self-evident. The note 'the vendor returns the whole list in one reply (no cursor)' usefully tells the agent not to attempt pagination, but there is no explicit when-to-use vs.-alternative 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, so the safety profile is covered. The description adds useful behavioral context beyond that: it's a GET /users read, it's paginated, and it enumerates exactly which fields come back. No auth or rate-limit detail, but that's a minor gap.

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

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

One tight sentence plus a short endpoint tag, with the resource and returned fields front-loaded and nothing wasted. 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?

There is no output schema, so listing the returned fields is valuable and largely satisfies the return-value need. Pagination is signposted. It could be slightly richer about page termination or ordering, but for a simple read-only list it is close to 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%, so the schema already documents after, before, and page_size in depth. The description only echoes pagination, and its mention of 'next_after' (a response field) rather than the 'after' parameter name could slightly confuse an agent. 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 (List) and resource (the store's users/staff), then enumerates the returned fields and the endpoint. It is clearly distinguishable from siblings like get_user_sale_totals or list_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?

The description implies usage by noting pagination with next_after, but it never states when to use this list vs. a sibling like get_user_sale_totals, nor any exclusions or prerequisites. Usage is implied rather than explained.

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?

With only readOnlyHint available, the description adds meaningful behavior: totals are computed from at most max_pages x page_size sales (so they can cover only a subset of data), only 'closed'-like states count by default, and a truncated reply must be resumed via offset and summed. However, it never states what happens if the underlying sales exceed that page budget and no 'truncated' flag appears, which is the biggest safety caveat for a totals 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?

Front-loaded with purpose and outputs, then constraints (default states, UTC, pagination). Dense but every sentence carries information; the only cost is the long single paragraph that makes the truncation-recovery instruction easy to miss.

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-parameter, no-output-schema aggregation tool it covers purpose, defaults, time semantics, and continuation behavior well. Gaps remain around the shape of the returned breakdowns (e.g. how many 'top products', what the day/outlet keys look like) and what 'truncated' means in terms 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 93%, so the schema already carries nearly all parameter meaning; baseline is a 3. The description does add real semantics the schema can't express — that max_pages x page_size bounds how much data the totals reflect, and the exact default for counted_states — but it says nothing about the filter interaction (e.g. whether product_id restricts the top-products breakdown).

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 ('totals for a period computed here') and enumerates the exact outputs: sale count, net/tax/gross, and breakdowns by state, UTC day, outlet, payment type, plus top products. The clause 'a report needs ONE tool call instead of dozens' implicitly separates it from the paginated list/search sales 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 clear when-to-use context (aggregated reporting rather than raw record retrieval) and explains the default filter plus how to override it with counted_states. It doesn't name a specific sibling alternative (e.g. list_sales / search_sales) as an explicit fallback, so it stops short of full when/when-not routing.

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?

readOnlyHint=true already signals a safe read, so the bar is lower. The description adds genuinely useful behavior: offset paging semantics (pass next_offset, null = last page) and the underlying endpoint. It does not mention the 'deleted' default (active only) or page-size limits, which would be the higher-value additions.

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 tight sentences: searchable fields first, then the paging rule, then the endpoint. Every sentence carries information and nothing is repeated from the schema.

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-param, no-output-schema search tool, the description covers the main filtering and paging story including what next_offset means on return. It leaves the 'deleted' toggle and result-shape/fields unaddressed, which an agent would want before deciding how to page or whether deleted records appear.

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 low at 30%, and the description compensates by naming most filterable fields (email, names, company, phone, mobile, customer_code) and explaining the offset chaining pattern. It omits deleted and page_size, so not fully compensating.

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 ('Find') and resource ('customers') and enumerates the searchable fields. It implicitly separates search-by-field from the sibling list_customers, though it never names that 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?

The enumerated fields imply when to use this over list_customers, and the paging note tells the agent how to paginate, but there is no explicit 'use X instead when...' guidance or statement of prerequisites.

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?

With readOnlyHint already declared, the description usefully adds the paging contract: offset paging, pass next_offset to continue, and null means last page. That is real behavioral context beyond the annotations. It omits that filters combine as AND and that results default to active records only, so a 4 rather than 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 tightly packed sentences: filters, paging contract, endpoint. Front-loaded with the capability and no filler. The endpoint reference is arguably redundant but is a single short clause.

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 nine-parameter, no-output-schema read tool, the description covers the two things an agent cannot infer: the filter surface and the pagination loop (next_offset / null terminator). What is still missing is return-shape description and page_size interaction with offset, but the schema and annotation carry much of the load.

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 one of the nine parameters already carries its own description (including the lowercase-SKU note and next_offset paging hint). The description restates the filter facets but adds no new syntax, format, or constraint detail, 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?

The description states a specific verb and resource ('Filter products by SKU, brand, supplier, tag, product type or variant parent') and enumerates the filter dimensions, which is more informative than the bare title. It stops short of distinguishing itself from the sibling `lightspeedxseries_list_products`, which is exactly the tool an agent would confuse it with.

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: the word 'Filter' plus the list of facets suggests this is the tool for narrowed product lookups. No explicit 'use this when / use list_products instead' routing, no note that no filters returns everything, no guidance on filter combination semantics.

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 safety is covered. The description adds genuine behavioral context beyond that: responses can be large, offset paging terminates when next_offset is null, and dates are interpreted in UTC. It stops short of describing result ordering, default page size behavior, or what a sale record contains.

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 dense sentences with no filler: filters first, then paging mechanics, then the escalation path to sales_summary. The most decision-relevant information (filters and the alternative tool) 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 12-parameter, no-output-schema search tool, it covers the two things the schema cannot: pagination continuation and the existence of a cheaper aggregation alternative. It does not say whether filters combine with AND, what the default ordering is, or that page_size defaults exist, but those are minor against the strong schema coverage.

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 92%, so the schema already documents nearly every parameter including UTC date interpretation and the payment type config_id. The description mostly restates the filter list and adds only the paging continuation convention, which is close to baseline for a high-coverage 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?

Opens with a specific verb and resource ('Find sales') and enumerates the filterable dimensions plus the underlying endpoint. It distinguishes itself from sales_summary for the totals case, but never states how it differs from the sibling list_sales, which an agent must infer.

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 routes the agent away from this tool when period totals are wanted ('use sales_summary instead of paging through this'), and explains how to continue paging. It gives clear context but no exclusions or guidance relative to list_sales or get_sale.

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 flag destructiveHint=true and idempotentHint=true, but the description goes further by explaining the overwrite semantics: current_amount is the NEW TOTAL, not a delta, so sales made since the last read are lost. It also bounds the blast radius ('other outlets and all other product fields stay as they are') and cites the underlying PATCH 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?

Front-loaded with 'WRITE:' as a mode marker, then scope, then the critical overwrite warning, then the unaffected-surface note, then the endpoint. Four dense sentences with no filler or 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?

A single-object destructive mutation with no output schema is fully covered: what is written, what is overwritten, what is preserved, the read-before-write workflow, and user confirmation. No behavioral gap remains that would cause a mis-invocation.

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?

With 100% schema coverage the baseline is 3, and the description adds partial-update semantics ('and/or') plus the loss-consequence framing of current_amount that reinforces the schema's 'total, not a delta' note. It does not add unit or format guidance for the reorder fields beyond what the schema already supplies, so it sits just above 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?

States a specific verb and resource ('set the stock on hand ... and/or the reorder point and reorder amount') with explicit scope ('ONE product at ONE outlet'). The field names in parentheses and the mention of get_inventory_levels make it immediately distinguishable from the read-only inventory 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?

Explicitly instructs to call get_inventory_levels first and to confirm the number with the user before writing, which is the key when-to-use precondition for a destructive overwrite. It also implicitly routes read-only intent to get_inventory_levels, leaving nothing to infer.

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?

Goes well beyond the annotations by disclosing the read-modify-write internals, that the vendor performs a full PUT, and the resulting lost-update race window. That is exactly the operational context an agent needs before mutating a customer, which the annotations alone (readOnly=false, destructive=true, idempotent=true) cannot convey.

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-loads the write/partial-update constraint, then adds the safety caveats and the endpoint tag in dense, waste-free sentences. Every clause adds actionable 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?

No output schema exists, and the description thoroughly covers mutation semantics and side effects, but it leaves return-value behavior and per-field meaning unaddressed for a 21-parameter tool. Mostly complete for correct invocation, with a minor gap on what comes back.

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?

With 21 parameters and only 29% schema description coverage, the description carries real weight by explaining the partial-update semantics (only supplied fields change, others preserved via the internal read). However, it says nothing about individual field meanings, formats, or the customer_group_id/customer_code references, leaving much of the parameter surface undocumented.

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: change fields of an existing customer', naming the verb, resource, and mutation class, plus the underlying endpoint PUT /customers/{customer_id}. This clearly distinguishes it from create_customer and get_customer 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?

Clearly frames this as a partial-field update where only passed fields change, and states what it cannot do (delete, change balances). It doesn't explicitly name sibling tools as alternatives (e.g., create_customer for new records), so it stops just short of full routing 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?

With annotations declaring write/destructive/idempotent, the description still adds useful behavior: the update is narrowly scoped ("Nothing else on the product changes"), a read-then-confirm workflow is required, and the store tax setting determines which price field matters. It does not address failure modes or permissions, and the scoped-PATCH phrasing sits in slight tension with destructiveHint=true, though it is a clarification rather than a contradiction.

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 the WRITE marker, then the value format, then the scope guarantee, then the workflow. Nothing is redundant and the endpoint is appended as a trailing technical note rather than cluttering the lead.

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 tool with annotations covering safety and idempotency and full schema descriptions, the description supplies the missing operational context: value format, field exclusivity, scoping, and read-before-write. The only real omission is any mention of loyalty_amount and of what the response returns, though no output schema exists to lean on.

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; the description goes beyond it by explaining the either/or semantics of price_excluding_tax versus price_including_tax and that the store's tax configuration determines which the till uses. It does not mention the optional loyalty_amount parameter at all, leaving that one to the schema alone.

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?

"WRITE: set the selling price of one product (variant)" gives a specific verb, a specific resource, and an explicit scope limit (one product, price only). "Nothing else on the product changes" plus the PATCH endpoint line separates it cleanly from siblings like set_product_stock and update_customer.

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

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

It states prerequisites clearly: "Read the product first and confirm the new price with the user," which tells the agent both to call get_product beforehand and to seek confirmation. It also advises setting only one of the two price fields and explains the tax-setting decides which is used. It does not explicitly name alternative tools (e.g., set_product_stock) for adjacent price/stock edits, so it stops short of full routing guidance.

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