Query Loyverse POS receipts, shifts, items, inventory and customers, and update stock and customers.
Scored across 21 tools
Every tool targets a distinct resource and action — list_* vs get_* pairs (items/get_item, customers/get_customer, receipts/get_receipt) are clearly separated, and entity-specific tools like list_variants, list_inventory and list_shifts don't collide. The only mild overlap is list_items (which embeds variants) and list_variants, but the descriptions make the boundary clear.
Uniform loyverse_<verb>_<noun> pattern throughout: get_*, list_*, upsert_*, set_inventory_levels. The 'upsert' verb is used consistently for create-or-update operations, and the prefix is applied uniformly, so naming is fully predictable.
21 tools is on the heavier side, but it maps to a genuinely broad POS domain (customers, items, variants, inventory, receipts, shifts, discounts, taxes, payments, employees, stores, suppliers, categories, merchant) with roughly 1-2 operations each. The count is justified by resource breadth rather than redundancy.
Read coverage is strong (list/get for all major entities, plus inventory writes), but the write surface is thin: items, employees, discounts, taxes and stores cannot be created or updated, and there are no delete operations anywhere. An agent doing setup or catalog maintenance would hit dead ends.
Fetch a single customer by id, with visits, total spent and points balance. Loyverse: GET /customers/{customer_id}.
| Name | Required | Description | Default |
|---|---|---|---|
| customer_id | Yes | The customer id (UUID). |
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 value beyond that by enumerating the payload contents (visits, total spent, points balance) and citing the underlying endpoint GET /customers/{customer_id}, which matters because no output schema exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One compact sentence front-loads the action, scope, and return fields, with the endpoint reference appended. Nothing is padded and nothing important 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?
For a read-only single-record fetch with no output schema, the description compensates adequately by listing the notable returned fields. Minor gaps remain around error behavior for unknown ids and whether related records are paginated, but the core need is met.
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 has its own description identifying it as a UUID, so the schema does the heavy lifting. The description only adds the redundant 'by id' framing; baseline 3 applies for a one-parameter tool with full schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (fetch) and resource (a single customer) and names the exact returned fields. The word 'single' distinguishes it cleanly from loyverse_list_customers in the sibling set.
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 'fetch a single customer by id' implies this is the one-at-a-time counterpart to loyverse_list_customers, but no alternative is named and no condition is given for choosing between them. 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.
Fetch a single catalog item by id, with its variants. Loyverse: GET /items/{item_id}.
| Name | Required | Description | Default |
|---|---|---|---|
| item_id | Yes | The item id (UUID). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
readOnlyHint=true already tells the agent this is a safe read. The description adds useful scope ('with its variants'), clarifying that variant data comes along, but says nothing about error behavior for missing ids or response shape beyond 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?
A single front-loaded sentence naming the action and resource, plus a compact endpoint reference. No filler, nothing redundant beyond the title.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description carries the burden of explaining return values; it partially does so by mentioning variants, but omits error handling for unknown ids and any surrounding object shape. Adequate but with a clear gap for a getter.
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 item_id parameter is fully documented in the schema as a UUID. The description only restates 'by id' and adds no format or constraint detail beyond the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description gives a specific verb (fetch) and resource (single catalog item) and adds that variants are included, plus the underlying endpoint GET /items/{item_id}. It is clearly a single-item lookup contrasted with list-style siblings, though it never names loyverse_list_items explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'by id' phrasing implies use when you already have an item id, which distinguishes it from loyverse_list_items, but no explicit when-to-use or when-not guidance is given. Usage 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.
Fetch the merchant account this token belongs to — business name, email, country and currency. A cheap way to confirm the token works. Loyverse: GET /merchant/.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
readOnlyHint=true already declares the safety profile, and the description adds value beyond that: it discloses that the result is scoped to the calling token (no merchant id argument), what fields come back, and that the call is cheap/near-free. It stops short of describing rate limits or error behavior for an invalid token.
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 core purpose and payoff, followed by the endpoint reference. Every clause carries information and 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?
With no output schema, the description usefully summarizes the shape of the return (business name, email, country, currency), and for a zero-parameter read-only call there are no other gaps an agent would need filled before invoking 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?
The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a no-arg tool is a 4. The description correctly conveys that identity comes implicitly from the token rather than an 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 this token belongs to), and enumerates the returned fields (business name, email, country, currency). This is clearly distinct from the get_/list_ siblings, which all target other resources such as customer, item, or 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?
Explicitly frames when to reach for it: 'A cheap way to confirm the token works,' which tells the agent this is a lightweight credential sanity-check. It does not name an alternative tool or state exclusions, but for a token-scoped singleton fetch none are really needed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch a single receipt by its receipt number (e.g. 2-1008), with line items, modifiers, discounts, taxes and payments. Loyverse: GET /receipts/{receipt_number}.
| Name | Required | Description | Default |
|---|---|---|---|
| receipt_number | Yes | The receipt number, e.g. 2-1008. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already establishes this as a safe read. The description goes beyond it by disclosing what the response contains (line items, modifiers, discounts, taxes, payments) and mapping to the underlying API call, which is meaningful since no output schema exists. It omits not-found/error 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 front-loaded sentence carrying purpose, identifier, return contents, and endpoint mapping with zero filler. Nothing could be removed without losing information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, describing the returned contents is the right move and it is done well; the single required parameter and read-only nature are covered. Only error/not-found behavior is left implicit, a minor gap for a simple getter.
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 documented in the schema. The description's example format ('2-1008') merely repeats what the schema already states, so it adds no meaning beyond the structured data.
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 receipt') and scopes it with 'by its receipt number', which cleanly distinguishes it from the sibling loyverse_list_receipts. An agent can select it 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 implied by 'single receipt by its receipt number', which tells the agent this is the lookup path when a receipt number is known, but no alternative is named and no exclusions (e.g. use loyverse_list_receipts when the number is unknown) are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List item categories. Loyverse: GET /categories.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Page size, 1-250 (Loyverse default 50). | |
| cursor | No | The `cursor` from the previous page's response. Omit for the first page. | |
| show_deleted | No | Also return soft-deleted records (they carry deleted_at). | |
| categories_ids | No | Comma-separated list of category ids to return. |
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 the underlying endpoint ('Loyverse: GET /categories'), which is modestly useful context, but it says nothing about pagination behavior or soft-deleted handling beyond what the schema fields already state.
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 purpose front-loaded and no filler. The endpoint reference is slightly redundant but not wasteful, and the definition is never hard to scan.
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 with fully documented parameters and no output schema, this is adequate but minimal. It omits any mention of paging flow or how results relate to sibling list endpoints, so it meets the minimum viable bar without exceeding 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 100%, so limit, cursor, show_deleted, and categories_ids are all documented in the schema itself. 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'), which is clear on its own. It does not, however, explicitly distinguish itself from the write sibling loyverse_upsert_category or from other list_* tools, so an agent gets clarity but no sibling 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?
No when-to-use guidance, no prerequisites, and no mention of alternatives such as loyverse_upsert_category for mutation or how this differs from loyverse_list_items/variants. 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.
List loyalty customers, newest first, with visits, total spent and points balance. Filter by email or ids. Loyverse: GET /customers.
| Name | Required | Description | Default |
|---|---|---|---|
| No | Only the customer with this email. | ||
| limit | No | Page size, 1-250 (Loyverse default 50). | |
| cursor | No | The `cursor` from the previous page's response. Omit for the first page. | |
| customer_ids | No | Comma-separated list of customer ids to return. | |
| created_at_max | No | Only records created at or before this time (ISO 8601 UTC, e.g. 2026-03-30T18:30:00.000Z). | |
| created_at_min | No | Only records created at or after this time (ISO 8601 UTC, e.g. 2026-03-30T18:30:00.000Z). | |
| updated_at_max | No | Only records updated at or before this time (ISO 8601 UTC, e.g. 2026-03-30T18:30:00.000Z). | |
| updated_at_min | No | Only records updated at or after this time (ISO 8601 UTC, e.g. 2026-03-30T18:30:00.000Z). |
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 behavioral context the annotations do not: the sort order (newest first) and the fact that each record carries visits, total spent and points balance. It stops short of describing pagination limits or rate 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?
Two compact sentences with zero filler; the scope, sort order and return payload are front-loaded before the filter hint and the API endpoint reference.
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 discloses the salient return fields and ordering, which is what an agent most needs. Minor gaps remain around paging behavior and whether an empty filter returns the full customer set, but the definition is largely self-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 every parameter (email, limit, cursor, customer_ids, the four timestamp bounds) is already documented in the schema. The description's 'filter by email or ids' restates two of them without adding syntax or format detail, so it earns only the baseline 3.
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 loyalty customers') plus the returned fields (visits, total spent, points balance) and sort order ('newest first'). It implicitly distinguishes itself from the sibling loyverse_get_customer by being the plural/list variant, but never names that sibling explicitly, so differentiation 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?
'Filter by email or ids' hints at how to narrow results, but there is no statement of when to use this list tool versus loyverse_get_customer for a single record, nor any note on pagination workflow beyond what the schema implies. Usage is implied rather than prescribed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List configured discounts (fixed/variable percent or amount, discount-by-points) and where they apply. Loyverse: GET /discounts.
| Name | Required | Description | Default |
|---|---|---|---|
| discount_ids | No | Comma-separated list of discount ids to return. | |
| show_deleted | No | Also return soft-deleted records (they carry deleted_at). | |
| created_at_max | No | Only records created at or before this time (ISO 8601 UTC, e.g. 2026-03-30T18:30:00.000Z). | |
| created_at_min | No | Only records created at or after this time (ISO 8601 UTC, e.g. 2026-03-30T18:30:00.000Z). | |
| updated_at_max | No | Only records updated at or before this time (ISO 8601 UTC, e.g. 2026-03-30T18:30:00.000Z). | |
| updated_at_min | No | Only records updated at or after this time (ISO 8601 UTC, e.g. 2026-03-30T18:30:00.000Z). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already establishes this as a safe read, lowering the disclosure bar. The description adds useful return-content context (discount types and applicability) and the REST endpoint, but omits pagination, default result limits, and auth requirements.
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 zero filler; the resource and scope come first and the endpoint hint trails as a compact second clause.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only list tool with full schema coverage and annotations covering safety, the description is nearly sufficient. It could still note pagination behavior or that soft-deleted records are excluded by default, but no output schema is needed.
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 filter parameters (discount_ids, show_deleted, created/updated bounds) are already fully documented with formats and examples. The description adds nothing param-specific, making the baseline 3 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?
Clear verb+resource ('List configured discounts') with extra specificity about the discount variants returned (fixed/variable percent or amount, discount-by-points) and their applicability. It is self-differentiating from siblings like list_taxes or list_payment_types by resource, but never names or contrasts an alternative explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no when-to-use guidance, no prerequisites, and no mention of alternatives among the many sibling list tools. The agent can infer it retrieves the discount catalog, but nothing steers selection or warns about exclusions (e.g., deleted records without show_deleted).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List employees, with the stores each can access and whether they are the owner. Loyverse: GET /employees.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Page size, 1-250 (Loyverse default 50). | |
| cursor | No | The `cursor` from the previous page's response. Omit for the first page. | |
| employee_ids | No | Comma-separated list of employee ids to return. | |
| show_deleted | No | Also return soft-deleted records (they carry deleted_at). | |
| created_at_max | No | Only records created at or before this time (ISO 8601 UTC, e.g. 2026-03-30T18:30:00.000Z). | |
| created_at_min | No | Only records created at or after this time (ISO 8601 UTC, e.g. 2026-03-30T18:30:00.000Z). | |
| updated_at_max | No | Only records updated at or before this time (ISO 8601 UTC, e.g. 2026-03-30T18:30:00.000Z). | |
| updated_at_min | No | Only records updated at or after this time (ISO 8601 UTC, e.g. 2026-03-30T18:30:00.000Z). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
readOnlyHint=true already tells the agent this is a safe read. The description usefully discloses what the records contain (accessible stores, owner flag), but says nothing about pagination, default page size behavior, or soft-deleted record handling beyond what the schema states. 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 tight sentences with zero filler; the payload description (stores, owner) is front-loaded and the API endpoint reference is a compact trailing note.
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 full schema coverage and annotations, the description covers purpose and return content. It lacks pagination guidance (relevant given cursor/limit) and store-access semantics, but no output schema exists and the core need is met.
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 eight parameters are fully documented in the schema itself (limit range, cursor, filters, show_deleted). The description adds no parameter-level meaning, which is the correct baseline 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 ('List') and resource ('employees') and adds scope detail — each employee's accessible stores and owner status. This distinguishes it cleanly from sibling list tools (list_customers, list_stores, etc.).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The purpose implies when to use it (retrieving employees), but there is no explicit when/when-not guidance, no mention of alternatives, and no note about pagination workflow despite the cursor parameter. Usage is inferable but not guided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List current stock (in_stock) per variant per store. Filter by stores and/or variants — the answer to 'what is running low?'. Loyverse: GET /inventory.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Page size, 1-250 (Loyverse default 50). | |
| cursor | No | The `cursor` from the previous page's response. Omit for the first page. | |
| store_ids | No | Comma-separated store ids. | |
| variant_ids | No | Comma-separated variant ids. | |
| updated_at_max | No | Only levels updated at or before this time (ISO 8601 UTC, e.g. 2026-03-30T18:30:00.000Z). | |
| updated_at_min | No | Only levels updated at or after this time (ISO 8601 UTC, e.g. 2026-03-30T18:30:00.000Z). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint=true annotation already establishes this as a safe read, so the description only needs to add context. It contributes the per-variant-per-store granularity and the `in_stock` field name, but says nothing about pagination behavior, rate limits, or whether all rows or a page are returned.
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 primary verb+resource claim is front-loaded and the use-case and endpoint follow. No filler or redundancy.
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 full schema coverage and readOnlyHint, the description covers purpose, filtering scope, and the key returned field. There is no output schema, but it hints at the return shape well enough; only pagination/multi-page behavior is unstated.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so every parameter is already documented in the schema, and the baseline is 3. The description echoes the store/variant filtering but adds no syntax, defaults, or semantics beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('List current stock (`in_stock`) per variant per store') plus the underlying endpoint (GET /inventory). The list-vs-write distinction from the sibling loyverse_set_inventory_levels is immediately inferable from the naming and the read framing.
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 clear use case — 'the answer to what is running low?' — and explains the store/variant filtering axes. It stops short of naming loyverse_set_inventory_levels as the write counterpart or stating when this should not be used, so no explicit exclusion or alternative routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List catalog items with their variants (SKU, barcode, price, cost, per-store pricing), category, taxes and modifiers. Loyverse: GET /items.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Page size, 1-250 (Loyverse default 50). | |
| cursor | No | The `cursor` from the previous page's response. Omit for the first page. | |
| items_ids | No | Comma-separated list of item ids to return. | |
| show_deleted | No | Also return soft-deleted records (they carry deleted_at). | |
| created_at_max | No | Only records created at or before this time (ISO 8601 UTC, e.g. 2026-03-30T18:30:00.000Z). | |
| created_at_min | No | Only records created at or after this time (ISO 8601 UTC, e.g. 2026-03-30T18:30:00.000Z). | |
| updated_at_max | No | Only records updated at or before this time (ISO 8601 UTC, e.g. 2026-03-30T18:30:00.000Z). | |
| updated_at_min | No | Only records updated at or after this time (ISO 8601 UTC, e.g. 2026-03-30T18:30:00.000Z). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
readOnlyHint=true already tells the agent this is a safe read. The description adds useful context about what the response contains (nested variants with pricing, taxes, modifiers), but says nothing about pagination behavior, rate limits, or result-size expectations beyond what the schema's cursor implies.
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 substantive capability statement leads and the endpoint reference trails. No hedging, no redundancy, 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 full schema coverage and no required parameters, the description tells the agent what is returned (including nested variants and per-store pricing) and that it maps to GET /items. With annotations covering safety and the schema covering inputs, nothing essential 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 all eight parameters (limit, cursor, items_ids, show_deleted, and the four timestamp filters) are fully documented in the schema, so the baseline of 3 applies. The description lists response content rather than parameter meaning and therefore adds little beyond the structured field docs.
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 catalog items) and enumerates the returned data (variants, SKU, barcode, price, cost, per-store pricing, category, taxes, modifiers), plus the underlying endpoint. It does not, however, distinguish itself from close siblings like loyverse_list_variants or loyverse_get_item, so an agent must infer the boundary.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the bulk-catalog-listing use case but gives no explicit when-to-use, when-not-to-use, or routing to siblings such as loyverse_get_item (single item) or loyverse_list_variants (variants only). With several near-neighbour list/get tools in the sibling set, more guidance would help.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the payment types (cash, card, integrated terminals…) and the stores where each is available. Receipt payments reference these ids. Loyverse: GET /payment_types.
| Name | Required | Description | Default |
|---|---|---|---|
| show_deleted | No | Also return soft-deleted records (they carry deleted_at). | |
| created_at_max | No | Only records created at or before this time (ISO 8601 UTC, e.g. 2026-03-30T18:30:00.000Z). | |
| created_at_min | No | Only records created at or after this time (ISO 8601 UTC, e.g. 2026-03-30T18:30:00.000Z). | |
| updated_at_max | No | Only records updated at or before this time (ISO 8601 UTC, e.g. 2026-03-30T18:30:00.000Z). | |
| updated_at_min | No | Only records updated at or after this time (ISO 8601 UTC, e.g. 2026-03-30T18:30:00.000Z). | |
| payment_type_ids | No | Comma-separated list of payment type ids to return. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
readOnlyHint=true already establishes the safety profile, and the description adds useful context that store availability is returned per payment type and that receipt payments reference these ids. It does not disclose pagination, result ordering, or whether soft-deleted records are excluded by default, so it adds only moderate value beyond the annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, front-loaded with the resource and its shape, followed by the receipt-id linkage and endpoint. The trailing 'Loyverse: GET /payment_types' is implementation trivia but compact; no filler otherwise.
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 endpoint with no output schema and 100% documented parameters, the description covers what the tool returns (payment types plus their store availability) and why the result matters. Only pagination/result-shape behavior is left unstated.
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 (show_deleted, created_at/updated_at bounds, payment_type_ids) are already fully documented in the schema. The description adds no parameter-level details such as filter combinability or the default for show_deleted, 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 (payment types), with concrete examples (cash, card, integrated terminals) and the linkage to store availability and receipt payment ids. It clearly separates itself from sibling list_* tools by resource, though it does not name any specific alternative.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied: 'Receipt payments reference these ids' hints that this tool is used to resolve payment type ids found on receipts, but there is no explicit when-to-use or when-not-to-use statement and no named alternative among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List sales and refund receipts, newest first, with line items, payments, discounts and taxes. Filter by store, time range or receipt numbers — the core of any sales question. Loyverse: GET /receipts.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Page size, 1-250 (Loyverse default 50). | |
| order | No | Only receipts with this order name/number. | |
| cursor | No | The `cursor` from the previous page's response. Omit for the first page. | |
| source | No | Only receipts from this source (e.g. an app name). | |
| store_id | No | Only receipts from this store. | |
| created_at_max | No | Only records created at or before this time (ISO 8601 UTC, e.g. 2026-03-30T18:30:00.000Z). | |
| created_at_min | No | Only records created at or after this time (ISO 8601 UTC, e.g. 2026-03-30T18:30:00.000Z). | |
| updated_at_max | No | Only records updated at or before this time (ISO 8601 UTC, e.g. 2026-03-30T18:30:00.000Z). | |
| updated_at_min | No | Only records updated at or after this time (ISO 8601 UTC, e.g. 2026-03-30T18:30:00.000Z). | |
| receipt_numbers | No | Comma-separated receipt numbers to return, e.g. 2-1008,2-1009. | |
| since_receipt_number | No | Only receipts created at or after the receipt with this number. | |
| before_receipt_number | No | Only receipts created up to the receipt with this number. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the safe-read profile is covered. The description adds real context beyond that: newest-first ordering and that each receipt includes line items, payments, discounts and taxes. It does not mention pagination/cursor behavior or result limits, which would round it out.
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; the resource and payload contents come first, filters second. No filler and nothing repeated from the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only list tool with no output schema, the description covers the resource, contents, ordering and main filter axes. Pagination handling is delegated to the well-documented cursor/limit params, so only minor gaps remain.
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 12 parameters are already documented in the schema. The description only loosely restates three filter categories (store, time range, receipt numbers), adding no syntax or semantics beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('List sales and refund receipts') plus the scope of returned data (line items, payments, discounts, taxes). This clearly separates it from the singular sibling loyverse_get_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?
'Filter by store, time range or receipt numbers — the core of any sales question' gives contextual usage and hints at the primary filter axes, but never states when to prefer this over loyverse_get_receipt for a single receipt, nor any exclusion conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List cash-register shifts with their cash, gross/net sales, refunds, discounts, taxes, per-payment-type totals and pay-in/pay-out movements — the end-of-day view. Loyverse: GET /shifts.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Page size, 1-250 (Loyverse default 50). | |
| cursor | No | The `cursor` from the previous page's response. Omit for the first page. | |
| store_ids | No | Comma-separated list of store ids to return. | |
| created_at_max | No | Only shifts opened at or before this time (ISO 8601 UTC, e.g. 2026-03-30T18:30:00.000Z). | |
| created_at_min | No | Only shifts opened at or after this time (ISO 8601 UTC, e.g. 2026-03-30T18:30:00.000Z). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
readOnlyHint=true already declares the safety profile, so the description's main added value is the field-level inventory of what each shift record contains — genuinely useful since no output schema exists. It does not disclose pagination behavior, default/maximum page semantics, or rate limits, but for a read-only list with a fully described schema that is a modest 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 sentences, front-loaded with the resource and its contents, with the API endpoint mapping tucked at the end. The long field enumeration is dense but each item is substantive, not filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only, 5-parameter list tool with full schema coverage, the description covers what the tool is and what it returns, compensating for the absent output schema. The only omissions are pagination mechanics and any note about ordering or volume of results, which are minor here.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so limit, cursor, store_ids and both created_at bounds are already fully documented in the schema. The description adds no filter syntax, timezone, or paging guidance beyond that, so the baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (List) and resource (cash-register shifts) and then enumerates the exact contents returned — cash, gross/net sales, refunds, discounts, taxes, per-payment-type totals, pay-in/pay-out movements. The 'end-of-day view' framing plus the 'Loyverse: GET /shifts' mapping makes it unmistakable against the other loyverse_list_* siblings, which cover different resources.
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 'the end-of-day view' implies the scenario (closing/reconciling a register), which is useful implied context. However, there is no explicit when-to-use guidance, no statement of what it is not for, and no pointer to an alternative sibling for a different kind of shift or sales query.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the merchant's stores (locations) with their addresses. Store ids are what the receipt, shift and inventory filters take. Loyverse: GET /stores.
| Name | Required | Description | Default |
|---|---|---|---|
| store_ids | No | Comma-separated list of store ids to return. | |
| show_deleted | No | Also return soft-deleted records (they carry deleted_at). | |
| created_at_max | No | Only records created at or before this time (ISO 8601 UTC, e.g. 2026-03-30T18:30:00.000Z). | |
| created_at_min | No | Only records created at or after this time (ISO 8601 UTC, e.g. 2026-03-30T18:30:00.000Z). | |
| updated_at_max | No | Only records updated at or before this time (ISO 8601 UTC, e.g. 2026-03-30T18:30:00.000Z). | |
| updated_at_min | No | Only records updated at or after this time (ISO 8601 UTC, e.g. 2026-03-30T18:30:00.000Z). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
readOnlyHint=true already declares this is a safe read. The description adds the returned shape (addresses) and the downstream role of store ids, but says nothing about pagination behavior or how show_deleted changes results, which is meaningful for a Loyverse 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?
Three short sentences, front-loaded with the core action, with no filler. Every clause (returned fields, downstream use, endpoint reference) carries information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list tool with full schema coverage and annotations, the description covers what the tool returns and why it matters. Only the absence of pagination/cursor hints keeps it from being fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all six filter parameters are already documented in the schema. The description adds no syntax or filtering detail beyond that, which is the expected baseline 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 the merchant's stores (locations)') and adds what is returned (addresses), which is more than a tautology. It is clearly distinguishable from sibling list_* tools by resource, though it names no 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?
'Store ids are what the receipt, shift and inventory filters take' tells the agent why it would call this tool and when the output matters downstream. There is no explicit when-not guidance or named alternative, but the usage context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List suppliers with their contact details. Loyverse: GET /suppliers/.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Page size, 1-250 (Loyverse default 50). | |
| cursor | No | The `cursor` from the previous page's response. Omit for the first page. | |
| show_deleted | No | Also return soft-deleted records (they carry deleted_at). | |
| suppliers_ids | No | Comma-separated list of supplier ids to return. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
readOnlyHint=true already establishes this is a safe read. The description adds that contact details are included in the response, but says nothing about pagination behavior (the cursor loop), result count, or whether deleted records are excluded by default — all things the schema only hints at via 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 short sentences, front-loaded with the purpose; the endpoint reference is arguably redundant but harmless. Nothing extraneous, nothing buried.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so the description carries some burden for return shape, and 'contact details' is only a partial answer. For a simple, zero-required-param list tool with fully covered parameters this is workable but 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 four parameters (limit, cursor, show_deleted, suppliers_ids) are already documented in the schema. The description adds no parameter-level meaning beyond that, 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 the payload hint 'contact details' plus the underlying endpoint. It is clearly distinguishable from the get_* siblings by resource, though it never explicitly contrasts with the nearest relatives (loyverse_upsert_supplier, the other 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 or when-not-to-use guidance, no mention of the sibling upsert_supplier, and no explanation of how pagination should be driven across calls. The agent must infer everything about invocation context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List taxes with their rate, whether they are INCLUDED in or ADDED to the price, and the stores they apply in. Loyverse: GET /taxes.
| Name | Required | Description | Default |
|---|---|---|---|
| tax_ids | No | Comma-separated list of tax ids to return. | |
| show_deleted | No | Also return soft-deleted records (they carry deleted_at). | |
| created_at_max | No | Only records created at or before this time (ISO 8601 UTC, e.g. 2026-03-30T18:30:00.000Z). | |
| created_at_min | No | Only records created at or after this time (ISO 8601 UTC, e.g. 2026-03-30T18:30:00.000Z). | |
| updated_at_max | No | Only records updated at or before this time (ISO 8601 UTC, e.g. 2026-03-30T18:30:00.000Z). | |
| updated_at_min | No | Only records updated at or after this time (ISO 8601 UTC, e.g. 2026-03-30T18:30:00.000Z). |
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 does add what the returned records contain (rate, inclusive/additive pricing, store applicability), but says nothing about pagination, result volume, or the soft-delete behavior surfaced by show_deleted.
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 written sentences with the payload description front-loaded; the trailing 'Loyverse: GET /taxes' endpoint mapping is marginal but harmless and cheap. No padding or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description usefully compensates by naming the fields a caller can expect. For a straightforward zero-required-parameter list tool with a fully described schema and a read-only annotation, this is nearly sufficient; only pagination/volume behavior is unstated.
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 (tax_ids, show_deleted, created_at bounds, updated_at bounds) are already fully documented. The description adds no filter syntax or usage nuance beyond the schema, so the baseline of 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 (taxes), plus the salient attributes returned: rate, INCLUDED vs ADDED price treatment, and applicable stores. No sibling tool lists taxes, so an agent can distinguish it immediately by name and description 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?
Listing usage is implied by the verb and the name, but there is no explicit when-to-use guidance, no mention of when to reach for filters like created_at_min/updated_at_min, and no named alternative. Nothing misleading, but nothing beyond the obvious.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List item variants — the sellable SKUs — optionally for given items or one SKU. Variant ids are what inventory levels are keyed on. Loyverse: GET /variants.
| Name | Required | Description | Default |
|---|---|---|---|
| sku | No | Only the variant with this SKU. | |
| limit | No | Page size, 1-250 (Loyverse default 50). | |
| cursor | No | The `cursor` from the previous page's response. Omit for the first page. | |
| items_ids | No | Comma-separated item ids whose variants to return. | |
| show_deleted | No | Also return soft-deleted records (they carry deleted_at). | |
| variants_ids | No | Comma-separated list of variant ids to return. | |
| created_at_max | No | Only records created at or before this time (ISO 8601 UTC, e.g. 2026-03-30T18:30:00.000Z). | |
| created_at_min | No | Only records created at or after this time (ISO 8601 UTC, e.g. 2026-03-30T18:30:00.000Z). | |
| updated_at_max | No | Only records updated at or before this time (ISO 8601 UTC, e.g. 2026-03-30T18:30:00.000Z). | |
| updated_at_min | No | Only records updated at or after this time (ISO 8601 UTC, e.g. 2026-03-30T18:30:00.000Z). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
readOnlyHint=true already declares this is a safe read, so the bar is lower. The description adds useful domain context (variant ids are what inventory levels are keyed on, backing endpoint GET /variants) but says nothing about pagination behavior, even though cursor/limit params 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?
Three short clauses, all front-loaded: what it lists, what a variant is, and how to scope the call. Every sentence carries information an agent can act on.
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 and full schema parameter coverage, the description is nearly sufficient; the main missing piece is any note on paging semantics or result ordering, which the schema only partially implies.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all ten parameters are already documented in the schema, establishing a baseline of 3. The description only gestures at the sku/items_ids filtering modes without adding syntax or defaults beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Names a specific verb+resource ('List item variants') and immediately defines the domain term ('the sellable SKUs'), distinguishing it from the sibling loyverse_list_items. It also states the scope of filtering and the significance of the returned ids.
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?
'optionally for given items or one SKU' implies the filtering modes, but there is no explicit when-to-use-this-vs-list_items guidance and no when-not conditions. The agent must infer that variants are the inventory-keyed records rather than items.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set the ABSOLUTE stock (stock_after) of one or more variants at given stores — e.g. after a stock count. This overwrites the current level rather than adding to it; read the current levels with loyverse_list_inventory first so they can be restored. Loyverse: POST /inventory.
| Name | Required | Description | Default |
|---|---|---|---|
| inventory_levels | Yes | The stock levels to set. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only carry destructiveHint=true; the description adds the crucial specific behavior that it overwrites the level rather than adding to it, that it sets an absolute value, and the recovery guidance to read current levels first. This is meaningful context beyond the flag.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences with the destructive absolute-overwrite behavior front-loaded, followed by the recovery prerequisite and the API endpoint. No filler; every clause carries information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter mutation with a fully documented schema and destructiveHint, the description supplies the one thing structured data can't: the overwrite semantics and restoration advice. No output schema exists but none is needed for a set operation.
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 baseline is 3. The description lifts stock_after meaning further by calling it the ABSOLUTE new level (vs. a delta), which the schema's terse 'new stock level' doesn't stress, and confirms multi-variant/multi-store input.
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 (set) and resource (inventory levels/stock), and immediately clarifies scope with 'one or more variants at given stores'. It also distinguishes the operation from an additive one, so an agent knows exactly what class of action this is.
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?
Names the trigger ('after a stock count') and explicitly routes to the sibling tool loyverse_list_inventory to read current levels first so they can be restored. That is a concrete when-to-use plus a prerequisite alternative, leaving little to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create an item category, or rename/recolor one by passing its id. Loyverse: POST /categories.
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | Existing category id to update. Omit to create. | |
| name | Yes | The category name (required). | |
| color | No | Display color on the POS. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations supply only destructiveHint=true, so the description must carry most of the burden. It clarifies that the operation is an upsert and that id triggers an in-place rename/recolor, but never says whether unspecified fields are preserved or cleared, what permissions are needed, or what the response contains.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, front-loading the create/update distinction before the endpoint reference. Nothing is padded, and the API route hint is short enough to be useful without bloat.
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 upsert with full schema coverage and no output schema, the description covers the key ambiguity (create vs update). It falls just short on mutation behavior details such as field retention and error cases, which the single destructiveHint annotation does not resolve.
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 three parameters (id, name, color with enum) are already documented in the schema, including the 'omit to create' semantics. The description merely restates that id drives update mode; 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 ('Create an item category') plus the exact update semantics ('rename/recolor one by passing its id'). An agent can immediately distinguish the create path from the update path, including which fields are mutable.
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 the explicit condition that selects each mode — omit id to create, pass id to update — which is real routing guidance within the tool. It does not, however, position itself against siblings like loyverse_list_categories (read path) or explain any prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a loyalty customer, or update one by passing its id. Loyverse does not document whether omitted fields survive an update, so on update fetch the customer first and send the full record. Loyverse: POST /customers.
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | Existing customer id to update. Omit to create. | |
| city | No | City, town or village. | |
| name | Yes | The customer's name (required). | |
| note | No | A note about the customer. | |
| No | Email address. | ||
| region | No | Province, state or prefecture. | |
| address | No | Street address. | |
| postal_code | No | Postal / ZIP code. | |
| country_code | No | Two-letter ISO 3166-1 alpha-2 country code, e.g. US. | |
| phone_number | No | Phone number. | |
| customer_code | No | Your own customer code (e.g. a loyalty card number). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only supply destructiveHint=true; the description adds the substantive behavioral risk that Loyverse does not document whether omitted fields survive an update, implying omitted fields may be wiped, and prescribes the safe workflow. That is real operational disclosure beyond the annotation, consistent with destructiveHint. It stays at 4 because nothing is said about return values, idempotency, or auth needs.
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 the create/update scope and the data-loss warning front-loaded, then the operational instruction. The trailing 'Loyverse: POST /customers.' endpoint note is marginally extraneous for an agent but costs little.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with destructiveHint=true, no output schema, and full schema coverage, the description covers everything an agent needs to call it safely: mode selection, required name, and the fetch-then-send-full-record rule. Return-value detail is unnecessary given parameter documentation.
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 all 11 parameters carry their own descriptions, including `id` ('Existing customer id to update. Omit to create.'). The description restates the create-vs-update role of `id` but adds no format, constraint, or field-level meaning beyond the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States specific verbs and resource ('Create a loyalty customer, or update one by passing its `id`') and immediately pairs the create/update duality with the discriminator parameter. This clearly separates it from read/list siblings like loyverse_get_customer and loyverse_list_customers, and scopes it to 'customer' versus the upsert_category/upsert_supplier siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit mode selection ('Omit to create' / pass `id` to update) and a concrete prerequisite workflow: fetch the customer first and resend the full record on update. It does not name the alternative tool (loyverse_get_customer) explicitly nor state when not to use this tool, so it stops short of the top band.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a supplier, or update one by passing its id. Loyverse does not document whether omitted fields survive an update, so on update send the full record. Loyverse: POST /suppliers/.
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | Existing supplier id to update. Omit to create. | |
| city | No | City, town or village. | |
| name | Yes | The supplier company name (required). | |
| note | No | A note about the supplier. | |
| No | Email address. | ||
| region | No | Province, state or prefecture. | |
| contact | No | Contact person's name. | |
| website | No | Website URL. | |
| address_1 | No | Address line 1. | |
| address_2 | No | Address line 2. | |
| postal_code | No | Postal / ZIP code. | |
| country_code | No | Two-letter ISO 3166-1 alpha-2 country code, e.g. US. | |
| phone_number | No | Phone number. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare destructiveHint=true; the description goes further by disclosing the ambiguity around omitted fields on update and prescribing a workaround (send the full record). It does not cover auth requirements, error behavior, or whether an update can clear existing fields, but it adds real behavioral value beyond the annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tightly written sentences that lead with the mode switch and immediately follow with the critical caveat; nothing is padded. The trailing 'Loyverse: POST /suppliers/.' is a minor, format-conventional addition rather than a load-bearing sentence.
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 no output schema and a destructive annotation, the description covers the two things an agent must know: how to pick create vs update and the partial-update risk. Missing only finer details such as uniqueness of `name` or what an update returns.
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 13 parameters are already documented. The description's mention of `id` driving create-vs-update duplicates the schema text ('Existing supplier id to update. Omit to create.'); only the full-record advice is new, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb pair and resource ('Create a supplier, or update one by passing its id') with the exact mechanism that switches between the two modes. No sibling tool writes suppliers, so the distinction from loyverse_list_suppliers and the other upserts 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?
Explicitly tells the agent how to choose the update path (pass `id`) versus the create path (omit it), and adds the operational rule to send the full record on update. It stops short of naming alternatives or exclusions, but the when-to-use guidance is concrete.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
loyverse_get_customerloyverse_get_itemloyverse_get_merchantloyverse_get_receiptloyverse_list_categoriesloyverse_list_customersloyverse_list_discountsloyverse_list_employeesloyverse_list_inventoryloyverse_list_itemsloyverse_list_payment_typesloyverse_list_receiptsloyverse_list_shiftsloyverse_list_storesloyverse_list_suppliersloyverse_list_taxesloyverse_list_variantsloyverse_set_inventory_levelsloyverse_upsert_categoryloyverse_upsert_customerloyverse_upsert_supplierRead store products, orders, customers, categories and coupons; adjust inventory and update orders.
Check products, stock on hand, customers, orders, invoices and quotes, and create records.
Read Foxy transactions, subscriptions, customers, carts and coupons; update customers and subs.
Check classes, attendance, customers, memberships and invoices in TeamUp and register customers.
Add one secure layer between your agents and this server.