Loyverse MCP by usefulapi

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

The readOnlyHint annotation already covers the safety profile, so the description's added value is that it names the returned payload — visits, total spent, and points balance — which is meaningful since there is no output schema. It does not mention error behavior for a missing/invalid id.

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

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

Two tight sentences, front-loaded with the action and resource, with the endpoint mapping appended as low-cost reference. Nothing 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 one-parameter read tool with no output schema, the description supplies enough: what it fetches, by what key, and roughly what comes back. Only the behavior on a nonexistent id is unaddressed, a minor gap.

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

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

Schema coverage is 100% and the single parameter customer_id is fully documented (UUID, minLength 1). The description only restates 'by id' and adds no format or validation detail beyond the schema, so baseline 3 applies.

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

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

The description states a specific verb and resource: 'Fetch a single customer by id.' The word 'single' implicitly distinguishes it from the sibling loyverse_list_customers, though the sibling is never named, so routing requires a small 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 implied by 'by id' — call it when you already have a customer id and want one record. There is no explicit when-to-use statement and no named alternative (e.g., loyverse_list_customers) for the case where you don't have an 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 readOnlyHint=true, so the safety profile is covered by structured data rather than the description. The description contributes one useful behavioral detail beyond the schema — that variants are included in the result — plus the underlying GET endpoint. It says nothing about error behavior for a missing id or about permissions.

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 that front-loads the action and resource, then appends the endpoint reference. Every clause earns its place; nothing is padded.

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

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

For a one-parameter read tool with no output schema, the description covers what is needed: what is fetched, the keying identifier, and the fact that variants come along. The absence of an output schema means the return shape is only loosely hinted at, keeping it short of 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?

With a single parameter and 100% schema description coverage ('The item id (UUID).'), the schema already carries the full parameter burden. The description's 'by id' adds no format or constraint detail beyond it, so the baseline 3 applies.

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

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

States a specific verb and resource: 'Fetch a single catalog item by id, with its variants.' The word 'single' implicitly contrasts with the sibling loyverse_list_items, but no alternative is named outright. Clear and unambiguous, though not maximally sibling-differentiated.

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

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

Usage is implied by 'by id' and 'single' — an agent can infer it is for direct lookups when a UUID is known — but there is no explicit when-to-use, when-not-to-use, or pointer to loyverse_list_items for browsing. Guidance exists only by inference.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds real behavioral context beyond that: the resource is derived from the auth token rather than a parameter, and it names the upstream endpoint (GET /merchant/), signalling a lightweight call. It does not describe error behavior for an invalid token, which is the main remaining gap.

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

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

Two short sentences with no filler; the return fields are front-loaded and the usage hint and endpoint follow in order of decreasing importance. Every clause earns its place.

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

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

There is no output schema and no parameters, so the description carries the burden of describing the response, and it does so (business name, email, country, currency). Combined with the documented endpoint, an agent has everything needed to call and interpret this 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?

The tool takes zero parameters, so the 4 baseline applies; the schema is trivially complete at 100% coverage. The description does add the useful nuance that the identity of the merchant comes from the token rather than any argument.

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 (fetch) and resource (the merchant account) and even enumerates the returned fields (business name, email, country, currency). It also clarifies the scoping — the merchant is the one 'this token belongs to' — which cleanly separates it from the get_customer/get_item sibling reads.

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?

"A cheap way to confirm the token works" gives a concrete primary use case (auth/token validation) rather than leaving the agent to guess. There is no explicit when-not or named alternative, but no sibling performs the same merchant lookup, so the guidance is adequate.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description goes beyond that by disclosing the response payload (line items, modifiers, discounts, taxes, payments) and mapping to the underlying API route, which helps the agent anticipate the result shape given there is no output 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?

Two tightly packed sentences: the resource and payload contents come first, the API mapping second. No filler, and the example is embedded inline rather than in a separate clause.

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

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

With one required parameter and no output schema, the description supplies what the schema cannot: an outline of the returned receipt contents and the endpoint it maps to. It is nearly complete; only a note on behavior for an invalid/unknown receipt number is missing.

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

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

Schema description coverage is 100% and the single parameter is fully documented inline, so the schema carries the load. The description only restates the receipt-number format with the same example already in the schema, adding no additional constraint or syntax detail. Baseline 3 applies.

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

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

Specific verb (Fetch) plus a single, well-defined resource (a receipt by receipt number), with a concrete example format. The word 'single' cleanly distinguishes it from the sibling loyverse_list_receipts, and it even enumerates the payload contents so the agent knows the depth of the fetch.

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

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

Usage is implied by 'fetch a single receipt by its receipt number', but the description never explicitly says when to prefer this over loyverse_list_receipts or what happens if the number is unknown. No prerequisites or error conditions 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=true, so the safety profile is covered. The description adds only the raw endpoint (GET /categories), saying nothing about pagination behavior, default soft-deleted handling, or result ordering that would help an agent behave correctly.

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 very short sentences with the purpose front-loaded and zero filler. Nothing extraneous, though that terseness is the source of the gaps scored elsewhere.

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

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

For a simple read-only list tool with full schema coverage and annotations carrying the safety profile, this is minimally viable. It stops short of describing pagination flow or default filtering, which an agent iterating pages would benefit from.

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

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

Schema description coverage is 100%, so all four parameters are already documented in the schema. The description adds no syntax or format detail beyond that, making the baseline 3 appropriate.

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

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

States a specific verb (List) and resource (item categories), and the API endpoint mapping confirms the scope. It doesn't explicitly contrast with siblings, but the resource noun makes it distinguishable from loyverse_list_items, loyverse_list_discounts, etc.

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

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

No when-to-use context, no mention of how it relates to loyverse_upsert_category, and no pagination workflow guidance despite a cursor parameter. Usage is only implied by the tool 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 readOnlyHint=true, so safety is covered. The description adds genuine behavioral context beyond that: default sort order (newest first) and the aggregate fields returned per customer. It stops short of describing pagination flow, though the cursor parameter schema covers that.

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

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

Three compact sentences with the key behavior (ordering, returned fields) front-loaded and no filler. The trailing 'Loyverse: GET /customers' is marginal restatement but is short and harmless.

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

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

With no output schema, the description usefully enumerates the prominent returned fields (visits, total spent, points balance), compensating for the missing return contract. All 8 parameters are covered by the schema, so an agent has enough to invoke it correctly.

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

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

Schema description coverage is 100%, so the schema already documents all 8 parameters with examples. The description only echoes the email/ids filters and adds nothing about limit, cursor, or the created/updated time bounds. Baseline 3 is appropriate when the schema carries the load.

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

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

States a specific verb (list) and resource (loyalty customers), and adds valuable detail about sort order ('newest first') and returned fields ('visits, total spent and points balance'). It does not explicitly distinguish itself from the singular sibling loyverse_get_customer, though 'List' vs 'get' implies the distinction.

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?

'Filter by email or ids' hints at when the tool is useful for lookups, but there is no explicit when-to-use/when-not guidance and no routing to the alternative loyverse_get_customer for single-record fetches. Usage is implied rather than stated.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds useful content semantics (what a discount record contains and that applicability information is included), but says nothing about result size, pagination, or soft-deleted handling in the body — that lives only in the schema.

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

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

Two short sentences with the substantive content front-loaded; the parenthetical enumeration of discount types earns its place. The trailing 'Loyverse: GET /discounts.' is endpoint trivia an agent cannot act on, marginally diluting an otherwise tight description.

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

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

No output schema exists, so the description is the only place a return shape could be sketched, and it only loosely implies 'configured discounts and where they apply' without describing the list or pagination behavior. Combined with a fully covered input schema and readOnly annotation, it is adequate but leaves the response side thin.

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

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

Schema description coverage is 100%, so all six filters are fully documented in the schema itself, including ISO 8601 format examples and the deleted_at behavior of show_deleted. The description adds no further parameter meaning, which meets the baseline for full-coverage schemas.

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+resource ('List configured discounts') and goes further by enumerating the discount subtypes (fixed/variable percent or amount, discount-by-points) and noting it also returns where they apply. That distinguishes it from any single-record retrieval sibling, though it never positions itself against the other loyverse_list_* 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 when-to-use guidance, no mention of when to reach for this versus loyverse_get_item or other list tools, and no hint that the optional filters (discount_ids, date ranges, show_deleted) can narrow results. 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?

The readOnlyHint annotation already establishes this as a safe, non-destructive read, so the description isn't burdened with the safety profile. It adds useful context by naming the endpoint (GET /employees) and disclosing that store access and owner status are returned, but says nothing about pagination behavior despite cursor/limit parameters.

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

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

Two tight sentences with no filler: the return-content detail is front-loaded and the endpoint hint trails efficiently. Every clause earns its place.

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

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

For a read-only list tool with no output schema, the description covers the returned fields plus the endpoint, and the schema fully documents all 8 optional filters. It is nearly complete, with only pagination mechanics left to the parameter descriptions.

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

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

Schema description coverage is 100%, with every parameter (including limit bounds and date-range formats) fully documented in the schema. The description contributes no additional parameter meaning, so the baseline 3 applies.

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

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

States a specific verb and resource ('List employees') and even previews the returned fields (accessible stores, owner flag), so the agent knows exactly what comes back. The employees resource is distinct from every sibling (customers, items, receipts, stores, etc.), though the description never explicitly differentiates itself from an alternative employee-fetching path.

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 when-to-use instruction, no mention of when filters like employee_ids or the date bounds matter, and no named alternative. Usage is only implied by the literal name; the description adds no routing or context guidance.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds genuinely useful behavior beyond that: it discloses the returned content shape (stock level per variant per store) and the upstream endpoint (GET /inventory), which matters given there is no output schema. Pagination behavior itself is left to the schema's cursor/limit descriptions.

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

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

Two compact sentences: the core purpose is front-loaded and the filter hint plus endpoint reference follow without padding. Nothing is repeated verbatim from the schema.

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

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

For a six-parameter, optional-argument list tool with no output schema, the description covers purpose, filterability, and upstream source, which is enough to invoke it correctly. It could say slightly more about result granularity when no filters are supplied, but the schema carries the remaining detail.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters including limit bounds, cursor, and ISO timestamps. The description only echoes the store/variant filters and adds no new syntax, format, or defaulting detail, matching the baseline for fully documented schemas.

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

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

States a specific verb and resource ('List current stock (`in_stock`) per variant per store') with the granularity (per variant, per store) made explicit, which cleanly separates it from siblings like loyverse_list_variants and loyverse_set_inventory_levels.

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

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

Gives a concrete use scenario ('the answer to "what is running low?"') and explains that results can be narrowed via store/variant filters, which tells the agent when this tool fits. It stops short of naming an alternative or stating when not to use it (e.g., no contrast with the setter tool).

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

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

readOnlyHint=true already tells the agent this is a safe, non-mutating read, so the description is not carrying the safety burden. It adds useful scope detail about what is returned (per-store pricing, taxes, modifiers), but says nothing about pagination behavior, result caps, or rate limits, which matter for an 8-parameter list endpoint.

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

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

Two compact sentences with the resource and returned fields front-loaded and no filler. The trailing 'Loyverse: GET /items' endpoint mapping is marginal but harmless for tracing to the underlying API.

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

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

With no output schema, the description usefully enumerates the returned data (SKU, barcode, price, cost, per-store pricing, category, taxes, modifiers), which is exactly the gap it needs to fill. It omits any mention of pagination or that soft-deleted records only appear when show_deleted is set, leaving minor gaps.

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

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

Schema description coverage is 100%, so every parameter including limit, cursor, show_deleted, and the created/updated time windows is already documented in the schema. The description adds no filtering or format detail beyond that, so the baseline 3 is correct.

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

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

States a specific verb (List) and resource (catalog items) and enumerates the sub-resources returned (variants, category, taxes, modifiers), so an agent can distinguish it from loyverse_list_categories or loyverse_list_variants. It never names the obvious alternative, loyverse_get_item, for single-item retrieval, so it falls short of full sibling differentiation.

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

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

There is no when-to-use guidance: nothing says this is the bulk retrieval path versus loyverse_get_item for a single record, and no conditions or prerequisites are given. Pagination usage is implicit at best from the cursor parameter in the schema.

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

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

The readOnlyHint annotation already establishes this is a safe read. The description adds useful relational context (types are linked to stores, receipts reference these ids) and the upstream endpoint, but says nothing about pagination, result size, or sort order for a list endpoint. With annotations covering the safety profile, this is adequate but not rich.

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 what is returned, then the practical linkage to receipts. No filler and nothing repeated from 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?

No output schema exists, yet the description names the key returned fields (payment types plus their store availability) and the receipt-id relationship, which is the main thing an agent needs. It stops short of describing pagination or the soft-delete flag's interaction with the listing, a minor gap for a read-only list.

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

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

Schema description coverage is 100%, with all six filters (show_deleted, created_at/updated_at bounds, payment_type_ids) documented in the schema itself. The description adds no parameter-level meaning, so the baseline 3 applies.

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

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

States a specific verb and resource (List the payment types) and adds scope detail that distinguishes it: it also returns the stores where each type is available. The note that receipt payments reference these ids ties the resource to a concrete use, so an agent knows exactly what this returns.

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 sentence 'Receipt payments reference these ids' implies when an agent would need this tool (resolving payment_type ids seen on receipts), but there is no explicit when-to-use, when-not-to-use, or named alternative among the many sibling list_* tools. 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 readOnlyHint=true, so safety is covered. The description adds genuinely useful behavioral detail beyond that: results are ordered newest first and each receipt carries line items, payments, discounts and taxes. It does not mention pagination behavior or result-size limits, though the cursor parameter in the schema hints at 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?

Two tight sentences, front-loaded with the core verb and resource, then the filter/usage note. Every clause carries information; 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?

With no output schema, the description usefully enumerates the returned payload components and ordering, and the 100%-covered schema handles all 12 filter parameters. The only gap is explicit pagination guidance, which is inferable from the cursor parameter but not stated.

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

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

Schema description coverage is 100% across all 12 parameters, so the schema already carries the semantics. The description only loosely restates the filter axes (store, time range, receipt numbers) and adds no format or syntax detail beyond what the schema documents, so the baseline 3 applies.

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

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

States a specific verb (List) and resource (sales and refund receipts) plus scope details: newest-first ordering and included line items, payments, discounts and taxes. This cleanly separates it from loyverse_get_receipt, which fetches a single receipt.

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

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

Gives clear context for use ('the core of any sales question') and enumerates the filter axes (store, time range, receipt numbers). It stops short of explicitly naming when to prefer a sibling such as loyverse_get_receipt for a single record or which filter combination is appropriate.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds genuine value beyond that by enumerating the returned data categories and citing the upstream endpoint ('Loyverse: GET /shifts'). It omits pagination/cursor behavior and any rate-limit context, so it stops short of a 5.

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

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

A single front-loaded sentence; the scope ('List cash-register shifts') comes before the field enumeration, and the endpoint tag is a compact trailer. The long field list is slightly heavy but earns its place since no output schema exists.

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

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

With no output schema, the description usefully compensates by describing the shape of the return (sales, refunds, taxes, payment-type totals, pay-in/out movements). Pagination semantics (cursor chaining, default page size) are left entirely to the schema, which is the only notable 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 100%, with all five parameters (limit, cursor, store_ids, created_at_min/max) fully documented in the schema itself. The description adds no parameter-level meaning, so the baseline 3 applies.

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

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

States a specific verb ('List') and resource ('cash-register shifts') and enumerates the returned aggregates (cash, gross/net sales, refunds, discounts, taxes, per-payment-type totals, pay-in/pay-out), which makes it clearly distinguishable from sibling listers like loyverse_list_receipts. An agent can tell what it gets without opening the schema.

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

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

Usage is only implied via the phrase 'the end-of-day view', which signals a reporting/reconciliation context. There is no explicit when-to-use or when-not-to-use guidance, and no alternative tool (e.g. loyverse_list_receipts) is named for shift-level vs receipt-level data.

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

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

readOnlyHint=true already tells the agent this is a safe read, so the bar is lower. The description adds that addresses are returned and that ids feed other filters, but it says nothing about pagination, result size, or how show_deleted/soft-deleted records behave, so the added behavioral context is modest.

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

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

Two compact sentences plus an endpoint mapping, with the core purpose front-loaded and no filler. Every clause carries information (scope, returned fields, downstream id usage, API path).

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

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

For a read-only list tool with six fully documented optional filters and readOnlyHint covering safety, the description is largely sufficient. It does not address pagination or the volume of results, which is a minor gap given there is no output schema.

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

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

Schema description coverage is 100%, so all six filters (store_ids, show_deleted, created/updated min-max) are already documented with format and semantics. The description adds only that store ids are consumed by receipt/shift/inventory filters, which is marginal extra meaning over the schema; baseline 3 is correct.

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 ("List the merchant's stores (locations)") and the payload shape ("with their addresses"). It also clarifies that store ids are the key consumed by receipt/shift/inventory filters, which helps distinguish this from the other list_* siblings, though it never names a sibling directly.

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

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

The sentence about store ids being what receipt, shift and inventory filters take implies the main reason to call this tool (resolving store ids for later filtering), but it is implied rather than an explicit when-to-use statement. No alternatives or when-not conditions are given.

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

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

readOnlyHint=true already establishes this as a safe read, and the description confirms it lists suppliers with contact details. It adds no further behavioral context such as pagination semantics, soft-delete handling, or rate limits, though those are partly covered by the schema parameter descriptions.

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

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

One short purpose sentence followed by an endpoint reference; front-loaded and free of filler. The second sentence is largely redundant given the tool name and could be dropped, keeping it just short of a 5.

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

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

For a simple read-only, zero-required-parameter listing tool with full schema coverage and annotation-declared safety, this is sufficient. No output schema exists, but since the description needn't explain return values in depth, the omission is minor.

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

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

Schema description coverage is 100%, with limit, cursor, show_deleted, and suppliers_ids all documented in the schema itself. The description adds no formatting, filter-combination, or ordering semantics beyond what the schema already provides, so the baseline 3 applies.

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

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

States a specific verb (list) and resource (suppliers) and adds a return-content hint ('with their contact details'). It distinguishes itself from the many sibling list_* tools by noun alone, but offers no explicit contrast with loyverse_upsert_supplier or loyverse_list_customers.

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

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

There is no guidance on when to use this versus alternatives, nor any prerequisites or exclusions. Usage must be inferred entirely from the tool name, and the trailing 'Loyverse: GET /suppliers/.' adds endpoint notation rather than selection guidance.

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

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

readOnlyHint=true already establishes this as a safe read, so the bar is lower. The description adds that each tax carries its rate, inclusion mode, and store applicability, which is useful output context, but it says nothing about pagination, result limits, or authentication needs. Modest value beyond 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?

One front-loaded sentence covering returned fields, followed by a compact API mapping (GET /taxes). Zero filler and nothing redundant.

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

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

With no output schema, the description partially compensates by naming three returned fields, but it omits the rest of the tax record shape and any pagination or result-size behavior. For a six-parameter list tool with no output schema, this is only minimally sufficient.

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

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

Schema description coverage is 100%, so all six parameters are already documented in the schema (tax_ids, show_deleted, and the four ISO 8601 time bounds). The description adds no filtering semantics beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb+resource (list taxes) and enumerates what each record carries: rate, INCLUDED vs ADDED price treatment, and applicable stores. No sibling tool lists taxes, so the resource alone differentiates it from the list_categories/list_items family.

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

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

Usage is implied by the name and the filter parameters (tax_ids, show_deleted, created/updated ranges), but the description gives no explicit when-to-use guidance, no statement that it returns the full collection by default, and no alternatives to consider. Adequate but with clear gaps.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds a genuinely useful domain fact not present in any structured field: variant ids are the key inventory levels are stored against, which tells the agent how this tool chains into loyverse_list_inventory and loyverse_set_inventory_levels. It stops short of describing pagination or return shape.

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

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

Front-loaded with purpose, then the disambiguation, then the underlying endpoint. Three short units with no redundancy. The 'Loyverse: GET /variants' tail is minor but defensible for an API-mirroring toolset.

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

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

For a 10-parameter, all-optional list tool with annotations covering the safety profile, the description covers selection well. With no output schema present, a sentence about what a returned variant record contains would close 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?

Schema description coverage is 100% across all 10 parameters, so the schema already carries the semantics. The description only alludes to the items_ids/sku filters generically and adds no format, default, or interaction detail beyond the schema. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb and resource (list item variants) and immediately disambiguates the domain term: variants are the sellable SKUs, distinct from the parent items covered by loyverse_list_items. The agent can tell what this returns without opening the schema.

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

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

It implies the two filtering modes ('optionally for given items or one SKU'), which maps to items_ids and sku, but never states when to reach for this over loyverse_list_items or loyverse_list_inventory, and gives no exclusions or prerequisites. Usage is inferable but not spelled out.

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

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

Annotations declare destructiveHint=true, so the danger signal is already present; the description adds real value on top by explaining that this overwrites rather than adds and advising a pre-read so levels can be restored. It stops short of covering rate limits, partial-failure behavior on large batches, or what the call returns, so it is strong but not exhaustive.

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 with no redundancy; the absolute/overwrite constraint is front-loaded before the recovery advice, and the endpoint note is a compact implementation anchor rather than 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?

With no output schema, the description still supplies the operationally critical facts: absolute semantics, the destructive overwrite, and the pre-read recovery step. It omits return shape and multi-item failure semantics for the up-to-250 array, which are minor gaps for a single-parameter tool.

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

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

Schema coverage is 100%, so the schema already documents store_id, variant_id and stock_after, giving a baseline of 3. The description earns an extra point by nailing down the semantics of stock_after as an absolute target level rather than a delta, which is the one interpretation an agent could plausibly get wrong.

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

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

States a specific verb and resource ('Set the ABSOLUTE stock of one or more variants at given stores') with the concrete example of a stock count, and the word 'absolute' immediately separates it from any incremental/upsert sibling. An agent can distinguish it from loyverse_list_inventory without opening either schema.

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

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

Gives an explicit trigger ('e.g. after a stock count'), names the read counterpart ('read the current levels with loyverse_list_inventory first'), and states the overwrite-vs-add distinction that determines whether this tool is the right one. Nothing about when to choose it 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 destructiveHint=true, and 'rename/recolor' is consistent with mutation. The description adds little beyond that: it does not say whether an update overwrites unspecified fields (e.g., does omitting `color` clear it), what permissions/API key are needed, or whether renaming affects items referencing the category. The 'POST /categories' note is implementation detail rather than agent-relevant 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?

One tight sentence front-loads the primary action and the branch condition, with no filler. The trailing 'Loyverse: POST /categories.' fragment is redundant for an agent choosing a tool, which keeps it just under the top mark.

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 only 3 fully documented params, no output schema, and a destructiveHint annotation, the essentials are covered. However, for a destructive mutation the description omits what an update does to fields not supplied and whether existing item associations are affected, leaving 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 100%, including the create-vs-update meaning of `id`, the 64-char name bound and the color enum, so the baseline is 3. The description's mention of `id` restates what the schema already documents and adds no format or edge-case 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?

The description gives a specific verb and resource ('Create an item category') and unpacks the dual create/update behavior by explaining that passing an `id` switches to rename/recolor. No sibling does the same thing (upsert_customer/upsert_supplier target different resources), so no explicit routing is needed, but the description also doesn't differentiate itself from the read-side sibling loyverse_list_categories.

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?

'Omit to create' / 'passing its `id`' gives a clear condition that selects between the two modes of this tool. It stops short of stating when-not to use it (e.g., to enumerate categories use list_categories) or any prerequisites, so it is clear context without 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 only supply destructiveHint=true; the description adds the far more useful behavioral detail that Loyverse does not document whether omitted fields survive an update, and converts that into the required workflow of fetching and re-sending the full record. That is exactly the destructive-update risk an agent needs surfaced, plus the underlying endpoint.

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

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

Three short sentences with zero filler: the create/update distinction comes first, the risky behavior second, the endpoint last. Every clause carries information an agent would otherwise have to guess.

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

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

For an 11-parameter destructive upsert with no output schema, the description covers the highest-risk gap (field loss on update) and the endpoint, which is sufficient to call it correctly. It is slightly thin on what the call returns (created vs updated customer shape) and any auth/rate-limit context, which is minor given the 100% schema coverage.

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

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

Schema description coverage is 100%, so every one of the 11 parameters is already documented in the schema, including 'id' with 'Omit to create.' The description's mention of `id` therefore does not add meaning beyond the schema, and the remaining fields (address, country_code, customer_code, etc.) receive no extra semantics. Baseline 3 applies.

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

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

The description names a specific resource (loyalty customer) and both verbs (create or update), with the discriminator for the update path stated explicitly ('by passing its `id`'). It also pins the operation to the concrete API surface ('Loyverse: POST /customers'), so an agent can separate it from loyverse_get_customer and loyverse_list_customers without reading 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?

It clearly states when the update branch applies and gives an actionable prerequisite ('on update fetch the customer first and send the full record'), which is real when-to-use guidance rather than a restatement. It does not, however, name the sibling to fetch with (loyverse_get_customer) or exclude any misuse case, so it stops short of full routing.

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

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

Significantly exceeds the minimal destructiveHint=true annotation: it warns that Loyverse does not document whether omitted fields survive an update, so the caller should send the full record. That explains the replace-like semantics behind the destructive hint, which annotations alone cannot convey. No auth or rate-limit context, and the endpoint mention (POST /suppliers/) adds 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?

Three short sentences, front-loaded with the operation and its mode switch, then the caveat, then the endpoint. Every sentence carries weight and none is redundant with the schema.

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

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

For a 13-parameter upsert with full schema coverage and no output schema, the description covers the operation mode and the main behavioral risk. The remaining gap is modest: no mention of what the call returns for the new/updated record or how errors surface.

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

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

Schema description coverage is 100%, so the baseline is 3; the description adds the one piece of semantics the schema implies but does not emphasize — that `id` switches the operation from create to update and that a partial update may wipe unspecified fields. It adds real guidance beyond field-level descriptions.

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 (create/update a supplier) and immediately disambiguates the dual mode with the mechanism: 'update one by passing its `id`'. An agent can distinguish this from loyverse_list_suppliers and the other upsert_* siblings 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 how to choose between create and update ('Omit to create' is echoed, and 'update one by passing its `id`'), which is the only real decision for this tool. It stops short of naming alternative tools or stating prerequisites/failure conditions, so it is clear context rather than a full when/when-not treatment.

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