Lightspeed X-Series MCP

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

Annotations already declare readOnly, idempotent, non-destructive and open-world, so the safety profile is covered. The description adds real invocation mechanics (base path resolution, leading-slash requirement, query encoding) and points to the llms.txt reference for endpoint specifics. It stops short of rate limits, error semantics or pagination behavior, which matters for an open-world passthrough.

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 dense sentences with zero padding: capability, example endpoints, path resolution rule, parameter encoding, and a reference link. Front-loaded with the capability and constraint.

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?

An output schema exists, so return values need no explanation, and the reference URL offloads endpoint-by-endpoint detail. For a generic open-world passthrough, however, the agent still lacks guidance on pagination and failure behavior, which a definition of this type should at least sketch.

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 0%, so the description must carry parameter meaning and it largely does: path is relative to /api/<version> and must start with '/', params are query parameters with repeated keys for lists. Only the concrete value format of params (types, escaping) and pagination-conveying params remain 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?

States a specific verb (read/GET) on a clearly scoped resource: any X-Series endpoint not covered by a dedicated tool, with concrete example paths (/shifts, /services, /serialnumbers). The phrase 'any other' implicitly distinguishes it from the dozens of dedicated sibling list_*/get_* tools without needing to name 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?

'Read any other X-Series endpoint' implies this is the fallback when no dedicated tool exists, but that is left to inference rather than stated. There is no explicit instruction to prefer list_products/search_sales/get_sale when they fit, and no guidance on when the generic path is inappropriate.

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, idempotentHint, non-destructive behavior, and openWorldHint. The description adds only returned fields, which are already represented by the output schema, and says nothing about not-found behavior, permissions, or matching rules.

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 compact sentence with no filler. The resource and identifier are front-loaded, and every phrase corresponds to useful 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 one-parameter lookup with rich annotations and an output schema, most invocation details are covered structurally. The description still lacks guidance on choosing between this and list_gift_cards and does not explain card-number format or not-found behavior.

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

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

Schema description coverage is 0%, so the description must carry the burden for the single parameter. 'By number' maps the card_number parameter to an exact card identifier, but it does not specify format or matching behavior.

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 (gift card) and the lookup key (card number), and notes returned fields (balance, status, transactions). It is clear, but it does not explicitly distinguish this single-card lookup from the sibling list_gift_cards 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?

The phrase 'by number' implies this is for looking up a specific gift card when the card number is known, which is a useful usage cue. However, there is no explicit when-to-use guidance, no exclusions, and no direct comparison to list_gift_cards.

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, idempotentHint=true, destructiveHint=false, and openWorldHint=true. The description adds useful behavioral context by noting that product lines are included by default, but it does not cover error behavior, authentication, or other operational details.

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, front-loaded sentence with no wasted words. It efficiently conveys the core return scope and default behavior.

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 an output schema and rich annotations, the description does not need to explain return values or safety. However, it remains thin on usage guidance and parameter semantics, leaving some gaps for an agent selecting between this and list_consignments.

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 0%, so the description must compensate. It only vaguely addresses include_products by saying product lines are included 'by default', and it provides no meaning for consignment_id beyond the parameter name.

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 and cardinality: 'One consignment with its totals and (by default) its product lines.' This implicitly contrasts with the sibling list_consignments tool, though it does not use an explicit verb like 'get' or name the sibling.

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_consignments or other siblings. The phrase 'One consignment' implies retrieval by ID, but no alternatives, prerequisites, or exclusions 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds real value beyond that by disclosing the composition of the returned record and the default inclusion of store credit balance, though it says nothing about error behavior when the ID doesn't exist.

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

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

A single dense sentence with no filler; the core result (one customer) is front-loaded and the qualifiers follow. Nothing 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?

An output schema exists, so the description needn't define return structure, and it correctly focuses on scope and defaults. The only gap for a simple get-by-ID tool is the unspecified identifier format.

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 0%, so both parameters are undocumented in the schema. The phrase 'by default, store credit balance' effectively explains the include_store_credit default, but customer_id's expected format (numeric vs. string, opaque ID vs. email) is never clarified.

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-object result (fetch one customer) and enumerates the returned fields: contact details, group, loyalty balance, year-to-date spend, addresses, store credit. 'One customer' implicitly contrasts with the search_customers sibling, but no sibling is named, so differentiation relies on inference.

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: a single-customer lookup by ID. There is no explicit statement of when to prefer this over search_customers or get_customer_group_customers, and no prerequisites or exclusions are mentioned.

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 readOnly, idempotent, open-world and non-destructive, so the safety profile is covered. The description adds one genuine behavioral fact beyond that — results are version-cursor paged — but says nothing about ordering, cursor stability, or what the returned payload contains, and nothing contradicts 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 a single front-loaded fragment with zero waste. That said, it errs toward under-specification rather than economy — there is no room left for the pagination detail that would actually help an agent call it correctly.

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?

An output schema exists, so return values need not be explained. But for a tool with a required identifier and two undocumented pagination parameters, the description leaves too much unresolved — how to page, what the cursor is, and how this differs from other customer-listing tools.

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 0%, so all three parameters (customer_group_id, after, page_size) rely on the description for meaning, and it explains none of them. 'Version-cursor paged' gestures at the paging model but does not clarify that 'after' is the version cursor or how page_size interacts with it.

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 fragment 'Customers in a customer group' identifies the resource and its scope well enough that an agent can guess it lists customers belonging to a given group. However, there is no explicit verb and no differentiation from siblings like search_customers or get_customer, so the agent must infer the distinction from the group-scoping alone.

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

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

There is no statement of when to use this tool rather than search_customers or get_customer, and no prerequisites or exclusions are mentioned. The only contextual hint is '(version-cursor paged)', which describes mechanics, not selection 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 readOnly, idempotent, non-destructive and openWorld, so the safety profile is covered. The description adds genuinely useful behavior: include_variants can return hundreds of rows (a volume warning), outlet uses substring matching, and hide_zero suppresses empty rows — details not derivable from the annotations or 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 tight sentences, front-loaded with the resource and scope, then the caveats that matter. Every clause carries information an agent needs; nothing is padding.

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?

An output schema exists, so return-value structure needn't be restated, and the description covers the main pitfalls (row volume, substring filtering, default hide_zero). The remaining gap is product_id semantics and how this tool relates to list_inventory_levels.

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 0%, so the description carries the burden, and it does explain three of four parameters well (variant family expansion, substring outlet matching, zero-row suppression). It leaves product_id entirely unexplained — whether it expects an internal ID, a variant ID, or a handle, and whether a variant ID works when include_variants is false.

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 concrete resource and scope: stock on hand per outlet for one product/variant, including reorder point, reorder amount and average cost. An agent immediately knows what data it returns. It does not, however, distinguish this from the sibling list_inventory_levels, which sounds closely related.

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 rather than stated: it's a per-product lookup, so an agent can infer it's for a single SKU rather than a bulk stock scan. The description never says when to prefer it over list_inventory_levels or list_stock_adjustments, and gives no 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?

Annotations already cover read-only, idempotent, open-world and non-destructive, and the description adds real context beyond them: prices are tax-exclusive and results are capped at limit. That cap is the key behavioral trait (silent truncation), though the description doesn't say whether truncation is detectable or how to page past it.

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 dense sentence with no filler, and the returned-field list and filtering rules are front-loaded. The missing verb ('Prices in a price book') makes it read slightly as a fragment rather than an instruction, but nothing 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?

With an output schema present, the description needn't explain return shape, and it covers the main calling concerns: required price book scope, filter options, and the result cap. Remaining gaps (pagination/truncation handling, ordering of results) are minor for a simple lookup tool.

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

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

Schema description coverage is 0%, so the description must carry the load, and it does for three of four parameters: product_ids filtering, query as a name substring match (semantics not in the schema), and limit as a cap. price_book_id is only implied by 'in a price book', and no syntax details (e.g. max limit) are given.

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 the resource and its scope precisely: prices belonging to a specific price book, with the returned fields (name, product_id, price, tax, markup) enumerated. The phrase 'in a price book' distinguishes it from siblings like search_products or get_product, though no sibling is named explicitly for routing.

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 explains how to filter (product_ids or name-substring query) but never says when this tool is the right choice versus get_product, search_products, or list_products. There is no when-to-use, when-not-to-use, or alternative recommendation, leaving the agent to infer selection from the 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?

Annotations already declare readOnly, idempotent, and non-destructive, so the safety profile is covered. The description adds useful content about the object graph returned, but omits error behavior (missing product) and key precedence, which matter for an openWorld lookup.

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

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

Two short sentences, front-loaded with the resource and its returned sub-entities, then the addressing keys. Nothing is redundant, though a few more words on exclusivity would have been worth the space.

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 an output schema present, the description does not need to explain return values, and the annotation set covers the read-only semantics. Still, for a two-parameter lookup with zero schema documentation, the absence of guidance on parameter precedence and not-found behavior leaves a real gap.

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

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

Schema description coverage is 0%, so the description must carry the burden. It clarifies that sku is an alternate lookup key and that product_id identifies the record, but leaves unresolved whether the parameters are mutually exclusive, which takes precedence, or the expected formats.

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 resource ('One product') and enumerates the related entities returned (family, brand, category, supplier, tags, variant attributes), which distinguishes it from the plural sibling list_products. It does not explicitly name the sibling alternatives, but the singular scoping makes the role clear.

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 the two lookup keys ('Pass product_id, or sku'), which implies a targeted single-record fetch. However, it never says when to prefer this over search_products or list_products, nor what happens if both keys are supplied or neither is.

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 this as a read-only, idempotent, non-destructive operation, and the description adds useful behavioral context by explaining that full=True returns the raw API object and can be very large. It does not mention permissions or rate limits, but the important output-size caveat is clearly disclosed.

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

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

The definition is front-loaded and appropriately sized, with no redundant sentences. The first sentence is dense but still organized around the returned family structure and variant fields.

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

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

Given the output schema exists and annotations cover safety, the description supplies enough context about the default compact response and the full raw-object option. The main remaining gap is routing guidance against sibling product-retrieval tools.

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 0%, so the description must carry parameter meaning. It explains the full parameter well, including the raw-object and large-output behavior, but product_id is only inferable from the tool name and is not described in terms of expected format or source.

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 variant family for one product, including what family details and variant lines are returned. It does not explicitly differentiate itself from sibling tools such as get_product or search_products, so it falls 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?

The description explains the default compact output and the full=True raw API object behavior, but it gives no guidance on when to use this tool versus get_product, search_products, or list_products. No exclusions or alternative-selection conditions are provided.

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 cover the safety profile (readOnly, idempotent, non-destructive), and the description adds genuinely new behavioral context: product lists are truncated and returned as counts plus the first product_limit entries. It does not cover behavior when the ID is unknown, but the truncation disclosure is the important signal.

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 dense sentence whose most important fact – it returns one promotion – is front-loaded, with the truncation caveat in parentheses. Slightly fragmentary, but no wasted words.

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

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

With an output schema present, return details need not be spelled out, and the description still tells the agent the response is a hybrid of full nested data and truncated lists. The main gap is the undocumented include_products 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 description coverage is 0%, so the description must carry parameter meaning. It clearly explains the effect of product_limit on each product list, but says nothing about include_products (a toggle that changes response shape) or the expected format of promotion_id.

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 (a single promotion) and enumerates what comes back: rules, promo codes, and applicable products. The singular framing implicitly contrasts with list_promotions, though the sibling is never named.

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 call this versus list_promotions or search tools, and no preconditions or exclusions. The only cue is the implied need for a promotion_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?

Annotations already declare this as a read-only, idempotent, non-destructive operation, so safety is covered. The description adds that line items and deliveries are returned, but does not explain how include_lines affects that response.

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 front-loaded sentence with no wasted text. It could be slightly more informative, but it is appropriately brief for a simple read 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?

The output schema exists, so return values need not be detailed, and annotations cover safety. However, with 0% schema description coverage, the missing explanation of include_lines and the required purchase_order_id is a meaningful gap.

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

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

Schema description coverage is 0%, so the description must compensate for both parameters. It does not mention purchase_order_id or explain include_lines, even though the latter controls whether line items are returned.

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 precisely: a single purchase order, including its line items and deliveries. That clearly distinguishes it from list_purchase_orders, although it does not name the 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?

There is no explicit when-to-use guidance or comparison with alternatives. The singular scope implies use over list_purchase_orders when one order is needed, but this is left 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 readOnly, idempotent, non-destructive, and openWorld, so the safety profile is covered. The description adds one genuinely useful behavioral fact: it reports on the register's current or last session rather than an arbitrary date range, which explains why there is no date parameter. It does not clarify what happens when no session exists or whether amounts are net of refunds.

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 with the resource front-loaded and zero filler. It is efficient, though the 'current/last' phrasing packs ambiguity into very few words rather than resolving 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?

For a single-parameter read tool with full annotations and an output schema, the description covers the core idea and the session scoping, so it is broadly sufficient. It still leaves the register_id semantics and the current-versus-last distinction unexplained, which matters when the tool has no date-range 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 description coverage is 0% and the only parameter, register_id, is never described in the description beyond the possessive phrase 'a register's'. No format, source, or lookup guidance is given, so the description does not compensate for the undocumented 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 names a specific resource (payment totals broken out by payment type) and a scope (a register's current/last session), so the agent can infer it returns an aggregated breakdown rather than raw payments. However, there is no verb and no differentiation from nearby siblings such as sales_summary, get_user_sale_totals, or list_payment_types. It is adequately specific but leaves the agent guessing how it differs from other summary tools.

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 sales_summary, get_user_sale_totals, or list_payment_types, and no prerequisites or exclusions. The agent must infer usage from the name and the one-line summary 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?

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds only the minor insight that this is a cheap-looking first call and what fields come back; it says nothing about failure modes (e.g. no configured retailer) or freshness of the settings.

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

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

Two short sentences, front-loaded with the payload description and followed by the sequencing advice. Nothing is redundant with the schema or annotations.

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?

An output schema exists, so return values need no explanation, and the description still names the key fields for quick scanning. Only the missing edge-case behavior (what happens if no retailer is configured) keeps it from a 5.

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 the description could clarify about arguments. The mention of currency/time zone correctly implies no filtering input is needed.

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 and enumerates the returned fields (name, currency, time zone, settings), which clearly distinguishes it from sibling list/get tools like api_get or list_outlets. Lacks an explicit statement of what a 'retailer' scopes (single account vs collection), so it stops 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?

'Call this first if you need the currency or local time zone' is an explicit when-to-use directive that tells the agent to bootstrap from this call rather than fetching it later. It gives no when-not guidance or named alternatives, which keeps it below a 5.

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

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

Annotations already declare readOnly, idempotent, non-destructive and open-world, so the safety profile is covered. The description adds only that the response is a full record rather than a summary; it says nothing about behavior on missing IDs or whether totals are computed at read time.

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 fragment with zero filler, and the scope statement is front-loaded. It is terse to the point of being a content list rather than a sentence, which slightly limits readability.

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

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

With an output schema present, return values needn't be explained, yet the description spends its length listing them anyway. For a simple one-param read tool this is close to sufficient, but it omits not-found behavior and the distinction from search_sales.

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 0% and the single parameter carries no title beyond 'Sale Id', so the description must compensate. It gets partial credit because 'One sale in full' makes clear sale_id identifies a single record, but it adds no format, source, or validation detail.

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

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

States the resource (a single sale) and enumerates the payload components (line items, payments, taxes, customer, totals), which distinguishes it from aggregate siblings like sales_summary. The verb is only implied by the name 'get', and no explicit sibling is named, so it stops 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?

Usage is only implied by the required sale_id and the singular 'One sale' framing: fetch details for a known sale. It never says when to prefer this over search_sales or what to do if the ID is unknown.

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 cover the safety profile: read-only, idempotent, non-destructive, and open-world. The description adds useful scope by saying the report spans all customers, but it does not add further behavioral context such as auth requirements, rate limits, or aggregation behavior.

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

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

The description is a single front-loaded sentence with no wasted words. It states the resource and scope immediately.

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

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

For a zero-parameter, read-only reporting tool with a full output schema and safe annotations, the description supplies enough to invoke it correctly. It could be slightly stronger if it named what the report contains or when to choose it over other report tools, but the structured fields cover most needs.

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?

This tool takes zero parameters, so parameter semantics are inherently simple. The schema coverage is complete, and there is no parameter behavior for the description to clarify.

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, a store credit report, and its scope, across all customers. It is clear enough to distinguish from customer-specific tools like get_customer, but it does not explicitly differentiate itself from other report-oriented siblings 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 'across all customers' implies an aggregate reporting use case rather than per-customer lookup. However, it gives no explicit when-to-use guidance, no exclusions, and no named alternatives among the many sibling tools.

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 readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The only extra context is 'as reported by Lightspeed', which hints at the data source but says nothing about aggregation period, caching, or what 'totals' includes. With annotations carrying the burden, this adds very little.

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

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

It is a single short phrase with no wasted words, but it is undersized for the information an agent needs. Brevity here comes at the cost of specificity rather than from efficiency.

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?

An output schema exists so return values need not be explained, but the description omits the aggregation window (all-time? date range?) and the provenance of user_id, both of which are essential to calling this correctly. For a reporting tool, that is a material gap.

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

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

Schema description coverage is 0% and the single required parameter user_id is undocumented in the schema. The description's phrase 'a staff user's' only weakly implies that user_id is a staff user identifier; it does not say where to obtain it or whether it differs from a customer id.

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 resource (a staff user's sales totals) and a source (Lightspeed), but gives no verb and no scope, so an agent cannot tell whether this returns a single figure, a breakdown, or a time series. It is distinguishable from list_users, but not clearly from 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?

There is no statement of when to use this instead of sales_summary or get_sale, and no prerequisite noted (e.g. that user_id comes from list_users). The agent must infer usage entirely from the name.

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

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

Annotations already declare read-only, idempotent, non-destructive, open-world behavior, so the description need not restate safety. It adds useful context with 'Version-cursor paged,' which tells the agent this is a paginated list endpoint, though it does not explain cursor mechanics.

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 resource categories, then filters, then pagination. It is telegraphic but efficient; no sentence is wasted, though sentence fragments reduce readability slightly.

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

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

Given existing safety annotations and an output schema, the description provides enough context to call the list endpoint correctly for common type/status filtering. The main remaining gap is outlet_id and exact pagination parameter semantics.

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

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

Schema description coverage is 0%, so the description must compensate, and it does explain type and status values plus cursor-based pagination. However, it omits outlet_id entirely and does not clarify after versus page_size 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?

The description names the resource domain precisely by defining consignments as stock orders, transfers, returns, and stocktakes, which is clearer than the bare tool name. It does not explicitly say 'list' or contrast with get_consignment, but the paged phrasing implies a collection endpoint.

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 supplies valid type and status values, which implies how to filter the list, but gives no explicit when-to-use guidance or alternatives such as get_consignment. Usage is inferable from the filter examples 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, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds nothing beyond that: it does not mention pagination behavior despite exposing page_size/page_number, does not describe ordering or result limits, and 'with state' is too vague to count as behavioral disclosure.

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

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

A single front-loaded sentence with no filler; every clause carries information. It is arguably too terse for a six-parameter list tool, but the brevity itself is not waste.

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?

An output schema exists, so return values need not be explained. However, for a paginated list tool with six optional parameters and no schema documentation, the description leaves an agent guessing about paging, the fulfillment_type/state filters, and default behavior.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It only touches outlet_id and sale_id (and ambiguously fulfillment_state via 'with state'), leaving page_size, page_number, and fulfillment_type completely unexplained. Two of six parameters covered at zero schema coverage is insufficient.

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 resource (fulfillments) and parenthetically defines the domain as pickups/deliveries/shipping, which is more than the name alone conveys. The verb is only implied via the tool name, but 'list ... optionally by outlet or sale' makes it clear this is a filtered fetch, distinct from siblings like list_outlets or get_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?

The phrase 'optionally by outlet or sale' implies the intended filtering scenarios, but there is no explicit when-to-use guidance, no mention of when not to call it versus get_sale or search_sales, and no stated prerequisites. Usage is inferable 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 readOnly, idempotent and non-destructive, so the safety profile is covered. The description adds nothing about paging behavior, default page size, ordering, or what the returned list contains, so beyond the status filter it contributes no behavioral context.

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

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

It is a single short sentence with no padding, which is good. Brevity here crosses into under-specification, though, since the only content is the status filter example.

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?

An output schema exists, so return values needn't be explained, but for a three-parameter list tool with zero schema coverage the description omits pagination semantics and alternative-tool guidance. That leaves the agent guessing on two of the three parameters.

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 0%, so the description must carry the parameter burden, but it only mentions status and gives example values. The before cursor and page_size parameters are completely unexplained, including what unit before is measured in.

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 the resource (gift cards) and the status filter, and the tool name supplies the list verb, so the intent is recoverable. However, it is a noun phrase fragment with no verb, and it doesn't distinguish this from the sibling find_gift_card.

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 says the status filter is optional but never says when to call this versus find_gift_card, nor how pagination should be used. An agent has to infer that this is the enumeration path and that one would be the lookup path.

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 annotations already declare readOnly, idempotent, openWorld, and non-destructive behavior. The description adds useful context beyond that by stating the maximum page size and identifying the inventory quantities returned where provided.

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 and front-loads the main purpose and filters, followed by pagination and use cases. It is efficient overall, though some phrasing is fragmented across line breaks rather than fully polished.

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?

An output schema exists, so return values need not be fully described, and annotations cover safety. But with seven parameters at 0% schema description coverage, the missing semantics for three filtering/grouping parameters leave the definition only minimally adequate for complex inventory queries.

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 0% across seven parameters. The description explains pagination and outlet/product filtering, but leaves group_variants, include_inactive, and root_product_ids entirely unexplained, so it only partially compensates for the schema gap.

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 resource and scope: inventory levels across the catalog, with optional outlet and product filters. It does not explicitly distinguish itself from sibling tools such as get_inventory or list_stock_adjustments, so it is clear but not fully sibling-differentiating.

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

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

It gives explicit usage contexts: 'what's in stock at outlet X' and low-stock reviews. However, it does not state when not to use it or name alternatives like get_inventory, so routing guidance is helpful but not complete.

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 readOnly, idempotent, non-destructive, openWorld, so the safety profile is fully covered. The description adds almost nothing beyond listing returned fields, which the output schema already provides, and says nothing about completeness or ordering of the collection.

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 short sentence with zero filler, and the key scoping word 'All' is front-loaded. Nothing is wasted and nothing an agent needs is buried.

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

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

With zero parameters and a present output schema, the description need not explain return shape or pagination. It is complete for a trivial list call, though it could note whether the result is paginated or 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The parenthetical only clarifies the entity, not a 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?

Names the resource (outlets) and disambiguates it as stores/warehouses, so an agent knows exactly what entity type it gets back. It reads as a noun phrase rather than a verb+resource, but the listing intent is unambiguous and no sibling covers outlets.

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 word 'All' implies a full unfiltered enumeration, which is minimal but real context, and there is no competing sibling for outlets so routing risk is low. It never states prerequisites, exclusions, or when to prefer a filtered lookup over this call.

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, idempotentHint, openWorldHint and non-destructive, so the safety profile is covered. The description adds nothing behavioral beyond that — no note on whether the list is tenant-scoped, cached, or paginated, and no indication of how these values relate to payment records elsewhere.

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

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

A single short sentence with no filler, and the illustrative examples are front-loaded. It is a fragment without a verb, but nothing 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 zero-argument, read-only reference listing with both annotations and an output schema, the description supplies the one thing the structured fields cannot: what the enumerated payment types actually look like. An absence of scoping/tie-in guidance to sale and payment tools keeps it from a 5.

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

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

Zero parameters, so there are no semantics to explain; baseline 4 applies. The parenthetical examples arguably do double duty in describing the kind of values the caller will receive.

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 is a noun phrase ('Payment types configured') that effectively restates the tool name rather than stating an action verb. The parenthetical examples (cash, card, gift card, store credit) do add concreteness about what a 'payment type' is, which lifts it above pure tautology, but it offers no differentiation from reference-data siblings such as list_reference or list_taxes.

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 call this versus alternatives, no prerequisite, and no exclusion. Usage is only inferable from the name 'list_payment_types' — an agent must guess that this is the reference set to fetch before interpreting payment 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?

Annotations already declare readOnly/ idempotent/ non-destructive, so safety is covered. The description adds genuinely useful behavior beyond that: the page token is a version cursor sourced from the previous response's version.max, which tells the agent how iteration actually works. It omits ordering guarantees, whether the cursor expires, and any rate/size limits.

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

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

Three short sentences with no filler; the resource and cursor mechanic come first and the sibling redirect last, in the order an agent needs them.

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?

An output schema exists, so return shape needn't be spelled out, and the paging loop is explained. The remaining gap is `page_size` semantics and termination behavior, which matter for a tool whose whole purpose is iterating a collection.

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 0%, so both parameters rest entirely on this description. `after` is well explained as the prior response's version.max, but `page_size` (default 100, max unknown) receives no mention at all, leaving half 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?

States the concrete resource (product collection page) and its pagination model (version cursor), which is more specific than a bare 'list products'. It also explicitly contrasts itself with search_products, so an agent can tell the two apart. The label 'raw' is slightly jargon-y but the core purpose is unambiguous.

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

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

'Prefer search_products to find items' gives an explicit alternative plus the condition that selects it, which is the main routing decision for this tool. It stops short of stating the positive case (full enumeration/export-style traversal) or any exclusions like volume limits, so it is clear but not complete.

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 readOnly, idempotent, and non-destructive behavior, so the description only needs to add operational context. It usefully discloses the default scope and that name is a partial match, but says nothing about pagination despite a page_size parameter, and gives no ordering or volume expectations.

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

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

The description is very short and front-loads the scope default, with no wasted sentences beyond the redundant opening word 'Promotions.' The telegraphic fragment style is compact but slightly awkward.

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?

Because an output schema exists, return values need not be explained. But for a list tool with four undocumented schema parameters and a sibling get_promotion, the absence of page_size semantics and any comparison against the single-promotion tool leaves it only minimally 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 0%, so the description must carry parameter meaning, and it explains scope, partial-name matching, and outlet_ids linkage reasonably well. However, page_size is completely undocumented, leaving one of four parameters without any semantic guidance.

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 is essentially the fragment 'Promotions.' plus filter notes, so the listing verb and resource come mostly from the tool name rather than the description. It is distinguishable from get_promotion only by inference, not by an explicit statement that this returns multiple promotions.

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 documents the scope values (current_upcoming default, past, all) but never says when to choose this tool over get_promotion or other list tools. There is no explicit when-to-use/when-not-to-use guidance, only implied filtering behavior.

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 readOnly, idempotent, non-destructive and openWorld, so the safety profile is covered. The description adds one genuinely useful behavioral fact — that paging is version-cursor based — but does not explain how the cursor behaves or whether results are stable/ordered.

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 short fragment — nothing is wasted, but it is terse to the point of under-specification rather than being efficiently front-loaded 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?

An output schema exists so return values needn't be described, but for an openWorld paginated list tool the description should at least explain how to page (what `after` accepts, whether the cursor is a version marker). That critical piece 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 0% for both parameters, so the schema only supplies names and defaults (after=0, page_size=100). The phrase "version-cursor paged" hints that `after` is a cursor, but neither parameter's meaning, units, nor iteration semantics are clarified.

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?

"Purchase orders (version-cursor paged)" names the resource but never states the verb (list/retrieve) — it essentially restates the tool name. The only added content is the paging style, so an agent learns little beyond what the name already conveys.

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?

No guidance on when to use this versus get_purchase_order or other list_* siblings, no mention of filters, and no instructions for what to do with the cursor. Usage is only inferable from the name.

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 establish read-only, idempotent, non-destructive, and open-world behavior. The description adds useful behavioral context by stating the required `sales:read` scope and cursor pagination via `after`, though it omits return format, pagination limits, and whether results are all quotes or filtered by some implicit scope.

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 extremely short and front-loaded, with no wasted words. It is under-specified rather than verbose, but structurally it delivers the auth scope and pagination note immediately.

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

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

An output schema exists, and annotations cover safety semantics, so the description does not need to explain return values. However, for a two-parameter list tool with 0% schema description coverage, the description is minimally complete: it explains `after` but not `limit`, and gives no usage 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 0%, so the description must carry parameter meaning. It explains `after` as a cursor for pagination, but says nothing about `limit`, its default of 100, or any bounds, leaving one of two parameters 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?

The description identifies the resource (quotes) and notes an auth scope (`sales:read`), but the verb is only implied by the tool name and the description does not explicitly state scope like all quotes or filtered quotes. There are no quote-related siblings, so sibling differentiation is less critical, but purpose remains only adequately clear.

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 no when-to-use guidance, no alternatives, and no exclusions. It only conveys an auth scope and pagination style, which does not help an agent decide when this tool is appropriate versus other list/search tools.

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 readOnly, idempotent, non-destructive, and open-world, so the safety profile is covered. The description adds only the set of valid kinds; it says nothing about whether results are paginated, how large collections are, or whether the collections are static reference data versus live records. An output schema exists, so return shape need not be explained.

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

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

Two sentences, front-loaded with the action, followed by the value list; no filler. The enum enumeration is long but every token is load-bearing since the schema does not define 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 one required parameter, an output schema, and full annotations, the description supplies the one genuinely missing piece (the valid kind values) and needs little else. The residual gap is the absence of any routing guidance against overlapping sibling list/get tools.

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 0% and the kind property has no enum and no description, so the description carries the entire burden — and it does, listing all ten accepted values exhaustively. It stops short of explaining what each collection contains or whether values are case-sensitive, which leaves some ambiguity for a required discriminator.

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 clear verb (list) and resource (reference collection) and enumerates the concrete collections available via kind, which is more specific than the bare name. It does not, however, distinguish itself from lookalike siblings such as list_taxes, list_payment_types, or list_outlets, which could plausibly overlap with outlet_taxes or the other kinds.

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 enumeration of kinds implies when the tool applies, but there is no explicit guidance on when to use this lookup tool versus the dozens of dedicated siblings (list_taxes, list_outlets, list_payment_types, list_products) that appear to return overlapping data. An agent must infer the selection rule.

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, idempotentHint=true and destructiveHint=false, so the safety profile is covered by structured data. The description adds only that results include outlet and open/closed state, which duplicates what the output schema likely conveys; it says nothing about ordering, pagination, or filtering scope.

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 economical sentence with the resource and returned attributes front-loaded and zero filler. It is arguably overly terse for the amount of surrounding capability, but nothing in it wastes space.

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 parameters, full annotation coverage, and an output schema to describe return values, the description needs only to establish scope and identity, which it does. A note on ordering or whether inactive registers are included would have closed the remaining gap.

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

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

The tool takes zero parameters, so the schema has nothing to explain and no semantic gap exists. Baseline 4 applies; the description adds no parameter information because none is needed.

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?

Names a specific resource (registers/tills) and states what the listing includes: outlet association and open/closed state. It is clearly distinguishable from siblings like list_outlets or list_payment_types, though it never uses an explicit verb ("List") or calls out that differentiation.

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

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

The description gives no guidance on when to prefer this tool over siblings such as list_outlets, nor any preconditions or exclusions. The single sentence is purely descriptive of contents, leaving usage entirely 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 readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds one genuine behavioral fact beyond them — that results are version-cursor paged — but does not explain what the cursor version refers to, whether results can shift between pages, or 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?

A single compact phrase with the resource and the pagination trait front-loaded; nothing is wasted. It is terse to a fault, but structure itself is clean.

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?

An output schema exists so return values needn't be described, but for a cursor-paged listing tool with 0% schema coverage the description leaves the pagination contract and parameter meanings underspecified. The agent knows what the tool returns at a high level but not how to drive it.

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

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

Schema description coverage is 0%, so the description must carry both parameters. "version-cursor paged" weakly hints that "after" is a cursor, but neither "after" nor "page_size" is explained, and default behavior (after=0, page_size=100) is left to the schema with no guidance on reasonable page sizes.

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?

Names the resource and clarifies what counts as a stock adjustment ("manual corrections, damages, ..."), which is useful since the tool name alone is ambiguous. However no verb is stated and there is no differentiation from the many other list_* siblings; the agent must infer this is a listing call from the 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?

No guidance on when to use this versus list_inventory_levels, get_inventory, or the other inventory-related siblings. No prerequisites, no exclusions, no statement of typical use case.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint, so the safety profile is fully covered by structured data. The description adds only 'with rates', which is a return-content hint largely duplicated by the output schema, and discloses nothing about scoping or completeness.

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

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

It is only six words, so it cannot be accused of padding, but it is a sentence fragment rather than a front-loaded statement of action. Brevity here reflects under-specification more than efficiency.

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 trivial, zero-parameter list tool with full annotations and an output schema, very little prose is required, and the description's silence on return shape is acceptable. Still, it never states that all configured taxes are returned unfiltered, which is the one fact an agent would want.

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 there is nothing for the description to disambiguate; the baseline of 4 applies. The phrase 'with rates' adds a small amount of meaning about what each returned tax object 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?

The fragment 'Sales taxes configured, with rates' identifies the resource (sales tax configurations) and hints at returned rates, so an agent can infer it's a list operation. However, there is no verb and no explicit statement that it enumerates all records, leaving the purpose 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?

No guidance is given about when to call this versus siblings such as list_reference or api_get, nor any prerequisites or exclusion conditions. The description offers no routing information at all.

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, idempotentHint, openWorldHint and non-destructive behavior, so the safety profile is fully covered. The description adds the shape of each record (id, name, account type, outlets), but since an output schema exists this is largely redundant rather than new behavioral context.

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

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

Two short sentences, front-loaded with the resource and its fields, followed immediately by the actionable chaining advice. No filler or restatement of the tool name.

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

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

Annotations and an output schema carry the safety and return-format burden, and the zero-param schema needs no explanation. The only gap is scope: it doesn't say whether all staff users are returned at once or whether results are paginated/limited.

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, which is the baseline-4 case; there is nothing for the description to disambiguate. The guidance about feeding returned ids into other tools compensates slightly for the absence of any filtering options.

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 precisely as 'Staff users' and enumerates the returned fields (id, name, account type, outlets), so an agent can distinguish it from list_outlets, get_customer, or get_user_sale_totals. It lacks an explicit verb ('list' is only implied by the name), but the intent is unambiguous.

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

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

It gives a useful downstream routing hint: use the returned ids with get_user_sale_totals or search_sales(user_id=...). That is chaining guidance rather than selection guidance — it never states when to call list_users versus another listing tool, nor mentions pagination or scope limits.

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 readOnly/idempotent/non-destructive, and the description adds genuinely non-obvious behavior: it filters to closed sales unless `states` is passed, includes returns as negatives, and caps results at 20,000 sales with a `truncated` signal. That last point tells the agent exactly how to detect and react to incomplete data, which is the kind of context annotations 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 core purpose, then delivers defaults, grouping values, return shape and the truncation escape hatch in tight, information-dense sentences. No sentence is filler, and the truncation caveat is placed at the end where it functions as a recovery instruction.

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?

An output schema exists, so listing return fields is mildly redundant but harmless, and the description covers dates, grouping, state filtering and the cap. The gaps are `top` (pagination/limit behavior) and `outlet_id` (whether it scopes the whole report) — both undocumented in schema and description, which matters for a 6-parameter aggregation 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 0%, so the description carries the load and does much of it: date format (YYYY-MM-DD), inclusive bounds, default of today, and — critically — the allowed group_by values (outlet, day, user, product, none), which the schema does not enumerate. The `top` and `outlet_id` parameters are left completely unexplained, keeping it out of 5 territory.

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 (revenue totals over a date range) and enumerates the grouping dimensions, which clearly separates it from row-level siblings like search_sales and get_sale. It never names those siblings explicitly, so an agent must infer the boundary between this aggregate summary and get_user_sale_totals.

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

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

Gives concrete usage conditions: closed sales by default, 'pass states to change', and 'narrow the range if `truncated` is true' — that is real when-to-do-what guidance. However, it offers no comparison against the closest alternatives (search_sales, get_user_sale_totals, get_register_payments_summary), so an agent still has to guess when this aggregation is preferred over a detail listing.

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 readOnly/idempotent/non-destructive, so the safety profile is covered, but the description adds nothing behavioral. Critically, with 8 optional parameters it never says what happens on an empty call (does it return all customers up to limit=50?), nor whether matching is exact, prefix, or fuzzy — a significant undisclosed trait for a search 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?

A single front-loaded sentence with zero padding — the verb and resource lead. It is efficient, though the brevity edges into under-specification given the tool's eight-parameter surface.

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?

The output schema exists, so return values need not be explained, and annotations cover safety. But for an open-world search with eight all-optional parameters and no schema documentation, the description omits matching semantics, multi-criteria behavior, and the meaning of limit — gaps an agent must guess at.

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 0%, so the description must carry the load: it names email, name, company, phone, and customer code, which maps to roughly six of the eight parameters. It leaves first_name vs last_name, mobile vs phone, and the limit parameter unexplained, so it only partially compensates for the coverage gap.

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") plus the searchable fields, so the operation is immediately identifiable. It does not differentiate from siblings such as get_customer or get_customer_group_customers, leaving the agent to infer which entry point retrieves a single known customer versus a search.

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

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

There is no guidance on when to choose this over get_customer, no statement about whether at least one criterion is required, and no note on whether multiple criteria are combined with AND or OR. The field list hints at what can be searched but gives no conditions 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?

Annotations already declare readOnly/idempotent/non-destructive, so safety is covered. The description adds real behavioral context the annotations don't: matching is case-insensitive and requires every word to match across four fields, and it names the return shape (product_id, name, variant, SKU, retail prices). It omits that inactive products are excluded by default.

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 searches, what it returns, what to call next. No filler, and the core capability 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 3-param read-only search with an output schema, the description covers matching semantics and next steps well. The gaps are the two optional parameters (limit, include_inactive), which affect whether the agent sees all matches or only active products.

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 0%, so the description must compensate. It thoroughly explains query semantics (fields searched, case-insensitivity, all-words-must-match), but says nothing about limit (default 25, i.e. pagination/truncation risk) or include_inactive, which materially changes results.

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 and the exact searchable fields (name, variant name, SKU, barcode). Combined with the follow-up routing to get_inventory/get_product, an agent can distinguish this from list_products or list_inventory_levels without opening any 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 tells the agent what to do after a hit (get_inventory for stock, get_product for detail), which is useful sequencing guidance. It stops short of naming when NOT to use this — e.g. list_products for enumeration or get_product_family for grouping — despite those siblings existing.

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 readOnly, idempotent, non-destructive, so safety is covered. The description adds non-obvious context the annotations cannot: dates are local store dates in YYYY-MM-DD and inclusive, defaulting to today, and the meaning of each state value (e.g. pending = on account/layby). It omits any pagination/limit 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?

Three tightly packed sentences, no filler, and the highest-value facts (date semantics and the compact/get_sale fork) come first.

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?

An output schema exists, so return shape need not be described. However, for an 11-parameter filter tool with zero schema descriptions, leaving seven filter parameters unexplained (and no mention of the limit parameter's effect) leaves real ambiguity about how to scope a search.

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 0%, so the description carries the full burden. It explains three of eleven parameters well (date_from/date_to format and defaults, states enumeration values and default-all, compact toggle), but limit, user_id, outlet_id, product_id, customer_id, register_id and invoice_number have no meaning documented in either schema or 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?

Opening verb+resource ('Find sales') is specific, and the description explicitly contrasts compact rows against get_sale(id), separating it from the sibling detail tool. It does not distinguish itself from sales_summary or get_user_sale_totals, which also touch sale data.

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 routing: use search_sales for compact rows, set compact=False or call get_sale(id) when full line items are needed. Date filtering defaults are stated. No explicit when-not-to-use against sales_summary, but the primary alternative is named.

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