Lightspeed Retail (R-Series) MCP by usefulapi

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

Annotations only declare this is a non-read-only, non-idempotent, non-destructive write. The description adds real context beyond that: phone/email are stored in the customer's Contact record, a specific minimum-identity requirement applies, the response includes the new customerID, and the backing endpoint is POST /Account/{accountID}/Customer.json. It does not warn about duplicate creation despite idempotentHint=false, which keeps it from a 5.

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

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

Three tight sentences: what it does, the minimum input contract, then the return value and endpoint. Nothing redundant, no restating of the title, and the constraint is front-loaded where an agent will see it.

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 8 optional parameters, no output schema, and sparse annotations, the description covers the essentials: minimum identity requirement, return shape (customerID), and the transport endpoint. It stops short of describing behavior on widely variable fields or duplicate handling, but that is a minor residual gap for a simple create.

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

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

Schema coverage is 100%, so the per-field meanings are already documented and the baseline would be 3. The description earns extra credit by stating the cross-field constraint (at least one of first name, last name, or company) and the Contact storage grouping for email/phone — semantics that exist in neither the schema nor the required-parameter list (required is empty).

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 immediately distinguishes itself from the get_/list_/update_ siblings by describing the write outcome. It also names the returned identifier (customerID), so an agent knows exactly what the call produces.

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

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

Usage is implied by the verb and by the precondition "Give at least a first name, last name or company," which tells the agent what input is required. However, it never says when to use this versus looking up an existing customer first (lightspeedrseries_get_customer / list_customers), which matters for an insert operation that is not idempotent.

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 establishes the safety profile, so the bar is lower, and the description adds real value by previewing the response payload (status, employee limit, currencies) in the absence of an output schema. It says nothing about auth requirements or rate limits, but for a zero-parameter read this is adequate.

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

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

Two short fragments with the resource and payload front-loaded and no filler. The telegram style is efficient, though the appended 'GET /Account/{accountID}.json' references a path parameter that does not exist in the input schema and adds slight ambiguity for a zero-arg call.

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-only call with no output schema, the description supplies both the purpose and a preview of key return fields, which is what an agent needs to decide to call it. Minor gaps: the field list is explicitly partial and no guidance is given on what to do with the account id afterward.

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 no input parameters, so there is nothing to document and the baseline of 4 applies. The trailing endpoint path is informational only and does not imply a caller-supplied argument 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?

States a specific resource (the connected Lightspeed R-Series account) and enumerates exactly what comes back: id, name, status, employee count/limit, and currencies. That is enough to distinguish it from every sibling, which are all list_/get_ calls on other resources (sales, items, customers, employees, shops, vendors).

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?

'Good first call' hints at a bootstrap/discovery role, which is genuinely useful sequencing guidance. However, it never states when-not to use it or names an alternative (e.g. list_shops for shop-level data, get_customer for per-customer detail), so the routing 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?

readOnlyHint=true already tells the agent this is a safe read, so the description's added value is limited to naming included relations and the endpoint shape. It does not clarify that the relation set is controllable/pay-per-relation (that lives in the schema) or what happens if a relation is not requested, which risks the agent assuming Contact/type/notes are always 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?

Two short, front-loaded sentences with no filler; the payload summary comes before the endpoint. The raw 'GET /Account/{accountID}/Customer/{customerID}.json' adds a path template with an accountID the caller never supplies, which is mild noise for an agent.

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

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

For a simple two-parameter read with no output schema, annotations covering read-only and a fully documented schema, the description supplies the essential shape of the response. The only shortfall is not tying the returned relations to the optional relations parameter.

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 relations parameter is fully documented in-schema down to the rate-limit cost and defaults, so the description need not repeat it. Mentioning Contact, customer type and notes echoes the default relation set but adds no new meaning for customer_id beyond its pattern/description.

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 customerID') and enumerates the key returned data (Contact, customer type, notes), which cleanly separates it from lightspeedrseries_list_customers. It stops short of naming that sibling explicitly, so differentiation is implied rather than stated.

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

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

Usage is only implied: the 'by customerID' phrasing and the schema hint that the ID comes from lightspeedrseries_list_customers together tell an agent this is the single-record fetch. There is no explicit when-to-use versus list_customers, nor any note on error behavior for a missing ID.

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 useful behavioral context: the shape of the payload (prices, ItemShops stock, category, related records) and the underlying GET endpoint. It omits the rate-limit cost of relation expansion and the default relation set, but those live in the schema's relations description.

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 with the resource and payload contents front-loaded; nothing is wasted, though the raw endpoint path is boilerplate that earns little space for most agents.

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 getter with full schema coverage and annotations declaring readOnly, the description supplies what an agent needs: what is returned and that it is a single-item fetch. No output schema exists, yet the return contents are sketched adequately.

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 both parameters are fully documented in the schema, including the default relation set and rate-limit cost warning. The description only reinforces 'by itemID' and lists a few of the relation-loaded fields, adding marginal meaning beyond structured data — 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: fetches one item by itemID and enumerates what comes back (prices, per-shop stock/ItemShops, category, related records). It is clearly distinct from list_items by the 'One item' framing, though it doesn't explicitly name the listing sibling — the schema's 'from lightspeedrseries_list_items' note does that routing instead.

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 'One item by itemID' phrasing signals single-record retrieval versus the list_* siblings, but there is no explicit when-to-use statement, no note to resolve IDs via lightspeedrseries_list_items first (only the schema says this), and no guidance on when to request extra relations.

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 context about what is returned, including order lines with specific fields plus vendor and shop, but it does not describe error behavior such as a missing order.

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

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

The description is compact and front-loaded, immediately stating the core retrieval target and returned data. The endpoint reference is brief and does not distract from the main purpose.

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 retrieval tool with complete parameter documentation and no output schema, the description gives enough return-shape context to call it correctly. It could be slightly more complete by mentioning behavior when the order is not found or the default relation set.

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 both parameters are already fully documented in the schema. The description reinforces that orderID identifies a single purchase order but adds no meaningful semantics beyond the schema, including for the relations 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?

The description clearly states that this retrieves a single purchase order by orderID and mentions the related records and line fields returned. It implicitly distinguishes itself from list_purchase_orders through the singular scope, though it does not name the sibling 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?

Usage is implied: retrieve one purchase order when its orderID is known. However, the description does not explicitly say when to use this versus lightspeedrseries_list_purchase_orders, nor does it state prerequisites or exclusions.

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 goes beyond it by disclosing the default response composition (SaleLines+Item, SalePayments+PaymentType, Customer) and the underlying endpoint — meaningful since there is no output schema. It does not mention the rate-limit cost of relations or not-found behavior, which the schema carries 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?

A single front-loaded sentence naming the resource, the key, and the payload, capped by the endpoint string. The endpoint is mildly redundant but serves as traceability rather than 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 correctly compensates by describing what comes back by default, which is the main thing an agent needs. Only edge behavior (missing sale, rate-limit consequences of expanding relations) is left unstated, a minor gap for a read-only fetch.

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 both parameters are fully documented in structured data and the baseline applies. The description only echoes saleID and restates the default relations, adding no syntax or trade-off information 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 ('One sale by saleID') plus the exact payload assembled (line items, payments, customer), which separates it cleanly from lightspeedrseries_list_sales and the other get_* siblings. The raw endpoint path reinforces the resource identity.

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 rather than stated: an agent can infer this is the single-record fetch to use after listing sales, but the description never says so or names an alternative. The pointer to list_sales lives only in the schema's sale_id 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?

Annotations already declare readOnlyHint=true, covering the safety profile. The description adds behavioral context by stating the data is hierarchical and listing the returned fields, which helps an agent understand the output shape. However, it does not disclose pagination behavior, authentication needs, or rate limits, leaving some behavioral gaps.

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 concise and front-loaded with the core resource and field list. The second sentence gives the API endpoint, which may be less useful to an agent but does not detract significantly. It is appropriately sized for a simple list tool.

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 5-parameter list tool with 100% schema coverage and readOnly annotations, the description is largely complete. It compensates for the absence of an output schema by explicitly naming the returned fields and noting the hierarchical structure. It does not explain how to use the parent_id filter for hierarchy traversal, but the schema covers that. Overall, it provides sufficient context 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 five parameters are fully documented in the schema. The description does not add any parameter-level meaning beyond what the schema provides. Baseline score of 3 is appropriate when the schema does the heavy lifting.

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 the resource (item categories) and its hierarchical nature, plus enumerates the returned fields (categoryID, name, fullPathName, parentID, nodeDepth). This clearly identifies the tool's purpose. However, it does not explicitly differentiate it from sibling list tools like lightspeedrseries_list_items, which also deal with items; explicit sibling differentiation is missing.

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 no guidance on when to use this tool versus alternatives, nor does it mention any prerequisites or exclusions. It simply states what the tool returns. Usage is only implied by the tool name and 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?

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds genuinely useful behavior beyond that: email search eagerly loads the Contact relation (emails, phones, addresses), and pagination is handled by passing next_url unchanged with other filters ignored. This is real operational context an agent would otherwise have to discover.

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

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

The description is compact and front-loaded with purpose before behavior and endpoint. The field enumeration is slightly noisy but every sentence carries information; nothing is padded.

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

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

For a read-only, 9-parameter, fully documented list tool with no output schema, the description covers search intent, relation-loading side effects and pagination adequately. Return shape is left implicit, but that is the main remaining gap and is minor given the 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 100%, so every parameter is already documented in the schema; baseline is 3. The description hints at filter semantics but muddies them by listing customerID, customerTypeID and createTime alongside name/company/email, none of which are input parameters — a small risk of the agent assuming they are filters.

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 ("Search customers") and names the searchable fields (name, company, email), making it clearly distinguishable from get_customer and create_customer. It stops short of explicitly naming those siblings as alternatives, so it is clear but not maximally differentiated.

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

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

Usage context is implied by "Search customers by name, company or email" and the next_url pagination note, but there is no explicit guidance on when to use this list/search tool versus get_customer for a single lookup, nor any mention of archive filtering as a usage consideration. Adequate but with clear gaps.

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, and the description adds the GET endpoint and returned employee fields. It does not disclose pagination behavior, default archived filtering, or the Contact relation semantics; there is no annotation 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?

The description is two terse sentences with little waste, front-loading the returned fields and ending with the endpoint. The fragmentary "Employees:" opening is slightly rough, but the definition remains efficient.

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 input schema and readOnlyHint, the description supplies the returned fields and endpoint, compensating for the absence of an output schema. Usage guidance is weak, but the calling requirements are mostly covered by the structured fields and annotations.

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

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

All five input parameters have complete schema descriptions, so the schema already supports correct invocation and the baseline is 3. The description mentions how the returned employeeID can be used to filter sales, but it does not add meaningful semantics for the input parameters 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 title/name and description identify employee records and the Employee endpoint, with a field list, so the resource is clear. It does not explicitly say "list" in the description or differentiate from other list_* siblings beyond the Employee resource, which keeps it from a 5.

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

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

The only usage-related sentence is "Use employeeID to filter sales," which is a cross-tool hint rather than guidance on when to call this tool. There is no explanation of when to use list_employees versus alternatives or when particular filters should be applied.

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; the description usefully adds that shopID 0 returns aggregate all-shops records rather than a real shop, and that next_url drives pagination. It omits any note on default page size or how totals behave across shops, but the added behavioral context is real.

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 tight sentences, front-loaded with the resource and its records, then the shopID-0 caveat, then pagination and endpoint. The field list earns its place because there is no output schema, though it is slightly dense.

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 8 optional parameters, no output schema, and minimal annotations, the description covers the essentials: record shape/fields, the aggregate-shop special case, and pagination. It leaves the exact response envelope and total-count behavior unspecified, a minor gap given the field enumeration.

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

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

Schema description coverage is 100%, so parameters are already well documented. The description reinforces the shopID 0 and next_url semantics, which is genuinely helpful, but adds nothing about min_qoh/max_qoh or modified_since beyond what the schema states.

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: stock levels per item per shop as ItemShop records, enumerating the fields returned. This distinguishes it from sibling list_items and list_shops by scope (per-item-per-shop quantities), though it never names an alternative explicitly.

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

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

Gives practical guidance on two things: shopID 0 means the all-shops summary and paging uses next_url. It does not say when to prefer this over list_items/list_shops or when a filter (e.g., min_qoh) is the right approach, so 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?

With readOnlyHint=true already covering the safety profile, the description adds useful behavioral context: it lists returned item fields, notes that include_stock adds ItemShops quantities and that shopID 0 means all shops, and explains pagination via next_url. It does not cover auth, rate limits, or error behavior, but it goes meaningfully beyond the 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 five short sentences, front-loads the core purpose, and each sentence adds useful information about response fields, stock inclusion, pagination, or the endpoint. It is efficient with no obvious filler.

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

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

For a 17-parameter read-only list/search tool with no output schema, the description gives endpoint context, partial return structure, stock inclusion behavior, and pagination. It does not exhaustively document return values or the accountID path requirement, but the high schema coverage and annotations make it largely sufficient for 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 17 parameters are already documented in the schema. The description mentions include_stock and next_url, but those are already covered there and it does not add filter syntax or additional meaning beyond the schema; baseline 3 is appropriate.

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

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

The description states a specific verb/resource: 'Search the product catalog' and gives the GET endpoint for items. It is clearly a plural item retrieval/search tool, but it does not explicitly distinguish itself from siblings like get_item or list_inventory.

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 'Search the product catalog' implies usage for catalog lookups, and it mentions include_stock and next_url as optional patterns. However, it gives no explicit when-to-use guidance, exclusions, or alternatives such as using get_item for a single item.

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 safe-read profile is covered. The description adds the underlying endpoint path, which is mildly useful context, but says nothing about pagination limits, default ordering, or how archived/complete filtering interacts with results — all behavioral details an agent would benefit from.

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 fragments with zero filler, and the resource is front-loaded before the endpoint. It is efficient, though the terseness tips into under-specification rather than economy.

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 eight optional parameters and no output schema, the field enumeration is a reasonable stand-in for describing return shape, and the schema fully documents inputs. But the description omits pagination behavior and the relationship to get_purchase_order, leaving gaps an agent must resolve by opening the schema and guessing.

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%, including enum values and the next_url continuation rule, so the schema carries the parameter burden. The description's field list (orderID, vendorID, shopID, etc.) partially maps to filterable concepts like vendor_id and shop_id but adds no syntax or constraint detail 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?

The description identifies the resource ('Purchase orders to vendors') and enumerates the returned fields, plus the endpoint GET /Account/{accountID}/Order.json, which implies retrieval. However it is a noun phrase with no explicit verb and never states that it returns a paginated list, so the purpose is inferable rather than stated. It also does nothing to distinguish itself from the sibling lightspeedrseries_get_purchase_order.

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 list tool versus get_purchase_order, nor any mention of filtering strategy, paging, or the next_url continuation flow described in the schema. The agent must infer all selection logic from the tool name alone.

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 is consistent with a read-only listing, and the description adds behavior beyond annotations: the default date field is completeTime, include_lines toggles the SaleLines relation, and pagination is driven by next_url. It does not disclose rate limits or default page size behavior beyond the schema, keeping it at 4.

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

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

Dense and front-loaded: return fields first, then filtering, then pagination and endpoint, with no filler sentences. The leading field enumeration is slightly redundant given the absent output schema, but it earns its place by compensating for that gap.

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 13 optional parameters, no output schema, and no destructive behavior, the description covers what matters: return shape, filterable dimensions, default date semantics, relation includes, and pagination. Missing only peripheral behavior such as rate limits or error conditions.

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

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

Schema coverage is 100%, so the parameters are already documented with patterns, enums and defaults. The description adds only marginal value beyond the schema—reiterating the filter set, the completeTime default for date_field, and that include_lines means items sold—so the baseline 3 applies.

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

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

States a specific verb+resource ('Sales history' listing) and enumerates exactly what is returned (saleID, completed/voided flags, completeTime, totals, customerID, employeeID, shopID, registerID). The plural 'list' plus the pagination hint distinguishes it cleanly from the sibling get_sale, which fetches a single record.

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 context for use: filter by date range on completeTime (default) or timeStamp, plus shop/customer/employee, and set include_lines only when line items are needed. It never explicitly contrasts itself with get_sale for single-record lookups or states exclusions, so it falls short of a 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?

readOnlyHint=true already establishes the safety profile, so the description's job is lighter; it adds that the response carries shopID, name, time zone, and archived flag, plus the underlying endpoint. It does not say whether archived shops are included by default or describe pagination behavior, but these are minor against the annotation coverage.

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

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

Two sentences plus an endpoint reference, front-loaded with the resource and returned fields. The raw "GET /Account/{accountID}/Shop.json" path is mild filler for an agent, but nothing else 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 read-only, zero-parameter-required list tool with full schema coverage and no output schema, the description usefully fills the return-value gap and explains how shopID is consumed elsewhere. The one residual ambiguity — whether archived shops appear by default — keeps it from being fully complete.

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

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

Schema coverage is 100%, so sort, limit, next_url, and include_contact are already fully documented in the schema. The description adds nothing about parameters — the field list refers to return values, not inputs — which is acceptable but not additive.

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

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

States a specific verb and resource ("List the account's shops"), clarifies that shops are store locations, and enumerates the fields returned. The resource is unmistakably distinct from the sibling list_* tools for customers, items, sales, vendors, etc.

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 second sentence gives downstream guidance ("Use shopID to filter sales, inventory and purchase orders"), which implies this is a discovery/enumeration step feeding other calls. However, it never states when to use this versus alternatives or any preconditions, leaving usage 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?

readOnlyHint=true already declares the safety profile, so the description need not restate it. It contributes the returned field set and the endpoint path, which is meaningful value given there is no output schema, but it says nothing about pagination behavior or how archived records interact with results beyond what the schema already states.

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?

A single compact statement with the resource front-loaded and no filler sentences. The field-list-plus-endpoint form is terse but every element 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 enumerated return fields are a useful substitute for a response contract, and all six parameters are fully documented in the schema. Only pagination semantics and filtering behavior are left implicit, which is a minor gap for a simple list 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 coverage is 100%, with enum values, defaults, and ranges all documented, so the baseline of 3 applies. The description adds no parameter syntax or filtering nuance 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 identifies the resource (vendors/suppliers), enumerates the returned fields, and names the underlying endpoint, so an agent knows this is a vendor-listing read. It never uses an explicit verb but the resource and field list make the operation unambiguous and distinct from siblings like list_customers or list_items.

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 statement of when to use this tool versus alternatives, nor any prerequisites or exclusions. The sibling tools differ by resource, so an agent can infer some routing, but the description itself provides no usage context.

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 readOnly=false, idempotent=true and destructive=true; the description adds genuinely new context by declaring partial-update (PATCH-like) semantics and giving the concrete PUT path. It does not explain the destructive risk the annotation warns about, nor authorization needs, so a 4 rather than 5.

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

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

Three short sentences, front-loaded with the action and the partial-update rule, followed by the exclusion and endpoint. The field enumeration is mildly redundant with the schema but not wasteful.

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

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

For an 8-parameter mutation with full schema coverage and annotations carrying the safety profile, the description covers action, update semantics, scope exclusions and endpoint. Return behavior is not described, but no output schema exists and the omission is minor.

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

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

Schema description coverage is 100%, so every parameter is already documented with pattern/length constraints. The description only names field families (description, default cost, SKUs, category) and omits ean/upc, adding little beyond the schema — 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?

Specific verb ("Change fields") on a specific resource ("an existing item") with the updatable field families enumerated. It also separates itself from the sibling lightspeedrseries_update_stock by declaring that prices and stock are out of scope here.

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

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

States the key usage condition — only passed fields are modified — and explicitly routes quantity changes to lightspeedrseries_update_stock. It lacks any precondition guidance (e.g. that the item must already exist, or what happens on unknown IDs), so not quite a 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 destructiveHint=true and idempotentHint=true, but the description adds the substantive semantics: the value overwrites rather than increments, and the write targets an ItemShop record via a specific endpoint. That 'sets, does not add' warning is exactly the behavioral context an agent needs before a destructive write.

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

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

The leading 'CHANGES STOCK COUNTS' hook front-loads the mutation, then each subsequent clause carries a distinct load: overwrite semantics, scale guidance, exclusion, identification options, endpoint. No filler.

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

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

No output schema exists, yet nothing essential is missing for a 4-param destructive write: scope, overwrite behavior, valid identifier sources, and the shopID 0 pitfall are all covered. The remaining ambiguity (both IDs supplied) is minor.

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 that by explaining that shop identification is an either/or choice between shop_id and item_shop_id and where each comes from. It still doesn't state whether the two are mutually exclusive or which wins if both are supplied.

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 — 'sets (does not add to) the quantity on hand of one item in one shop' — with the crucial absolute-vs-increment distinction spelled out. This clearly separates it from siblings like update_item, which touches item attributes rather than per-shop stock.

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 usage: 'Use for correcting a few items; for many items use an inventory count in Lightspeed,' and gives a hard exclusion: 'Not for shopID 0 (the all-shops summary).' Both a preferred alternative and a when-not condition are present.

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