Read Smaregi stores, products, customers, stock and transactions; manage customers, products, stock.
Scored across 20 tools
Most tools map cleanly to a distinct resource plus action, and the descriptions explicitly disambiguate the closest pair (smaregi_adjust_stock vs smaregi_set_stock, and list_stock vs list_stock_changes). The only mild overlap is the four stock tools, which require reading descriptions to pick correctly.
Every tool uses the same smaregi_ prefix with a consistent snake_case verb_noun pattern (list_, get_, create_, update_, adjust_, set_). No mixed conventions or stray casing.
20 tools for a POS domain spanning products, customers, stores, staff, transactions and stock is defensible, with most tools earning their place. It sits at the upper edge of the comfortable range and could be trimmed.
Core read/write flows (list/get/create/update for products and customers, full stock read/change/set plus history, transaction listing and retrieval) are covered. But there are no delete operations anywhere, and staff, stores and categories are read-only with no create/update, leaving notable gaps.
WRITE: add (positive) or subtract (negative) a quantity to the stock of one product in one store. Not idempotent: a repeat applies the change again. POST /stock/{product_id}/add.
| Name | Required | Description | Default |
|---|---|---|---|
| memo | No | Note stored in the stock history. | |
| store_id | Yes | Numeric Smaregi id (string or number). | |
| product_id | Yes | Numeric Smaregi id (string or number). | |
| stock_amount | Yes | The change: +5 adds five, -3 removes three. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, destructiveHint=true and idempotentHint=false, but the description earns credit by spelling out the practical consequence of non-idempotency ('a repeat applies the change again') rather than just tagging it. It does not disclose whether the resulting level may go negative, what auth/permissions are needed, or what happens on a missing product/store.
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 the write nature signalled first, the core semantics second, and the idempotency caveat third. No filler, no repetition of schema content beyond what the sign convention needs.
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 4-parameter mutation with a fully described schema and no output schema, the definition covers purpose, sign semantics, and non-idempotency, which is enough to invoke it correctly. It stops short of failure modes and permission requirements, which matters slightly more given destructiveHint=true.
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 every parameter is already documented, including the sign convention for stock_amount ('+5 adds five, -3 removes three'). The description restates that same sign convention but adds nothing about store_id/product_id pairing or the memo field, 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 pattern ('add (positive) or subtract (negative) a quantity') plus the resource and scope ('one product in one store'), which clearly separates it from an absolute setter. It never names smaregi_set_stock or smaregi_list_stock, leaving sibling differentiation to inference from the delta semantics.
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?
Implicit usage only: the agent learns this is a relative adjustment rather than an overwrite, which suggests preferring smaregi_set_stock for absolute values. No explicit when-to-use, when-not-to-use, or named alternative is provided, and nothing is said about preconditions such as the product/store existing or needing stock records.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
WRITE: create a customer (member). customerCode, firstName and lastName are required; the contract's own required-column settings may demand more. Not idempotent: calling twice with a different code creates two customers. POST /customers.
| Name | Required | Description | Default |
|---|---|---|---|
| sex | No | Sex: 0 = unknown, 1 = male, 2 = female. | |
| note | No | Note. | |
| rank | No | Member rank. | |
| note2 | No | Second note. | |
| status | No | Member status: 0 = active, 1 = suspended, 2 = card lost, 3 = withdrawn, 4 = merged. | |
| address | No | Address. | |
| storeId | No | Store id the customer belongs to. | |
| lastKana | No | Last name, kana. | |
| lastName | Yes | Last name. | |
| postCode | No | Postal code. | |
| birthDate | No | Birth date, yyyy-mm-dd. | |
| entryDate | No | Enrollment (membership start) date, yyyy-mm-dd; some contracts require it when creating a customer. | |
| faxNumber | No | Fax number. | |
| firstKana | No | First name, kana. | |
| firstName | Yes | First name. | |
| customerNo | No | Customer / member number. | |
| companyName | No | Company name. | |
| mailAddress | No | E-mail address. | |
| phoneNumber | No | Phone number. | |
| customerCode | Yes | Customer code (unique per contract). | |
| mobileNumber | No | Mobile number. | |
| departmentName | No | Department name. | |
| mailReceiveFlag | No | Whether the customer accepts guidance mail: 0 = refuse, 1 = allow (default). | |
| pointExpireDate | No | Point expiry date, yyyy-mm-dd; some contracts require it when creating a customer. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false and idempotentHint=false, but the description adds the concrete consequence of non-idempotency: two calls with different codes create two customers. It also mentions the POST /customers endpoint and contract-specific required-column behavior. It does not describe permissions or response shape, but that is less critical given the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with WRITE, states the required fields, gives the non-idempotency consequence, and ends with the endpoint. Every sentence adds distinct operational value with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 24-parameter creation tool with no output schema, the definition covers the essentials: operation type, required parameters, non-idempotency, contract-dependent requirements, and endpoint. It stops short of describing the expected response or authentication prerequisites, but the annotations and schema fill most remaining 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 most parameter meaning is already documented. The description adds useful semantics beyond the schema by naming the three required parameters and warning that contract-level required-column settings may demand additional fields beyond the schema's required list.
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 -- create a customer (member) -- and distinguishes it from sibling operations such as update_customer and list_customers. An agent can immediately tell that this is the creation path, not a read or update 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?
It gives clear usage context: it is a WRITE operation, customerCode/firstName/lastName are required, and the contract may require additional columns. It also warns that calling twice with a different code creates two customers, which is important selection guidance. However, it does not explicitly state when to use update_customer instead.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
WRITE: create a product. categoryId, productName and price are required. Not idempotent. POST /products.
| Name | Required | Description | Default |
|---|---|---|---|
| tag | No | Tag. | |
| url | No | Product URL. | |
| cost | No | Unit cost. | |
| size | No | Size. | |
| color | No | Color. | |
| price | Yes | Selling price. | |
| division | No | Product division: 0 = normal (default), 1 = prepaid multi-use ticket (only contracts with that feature), 2 = option product. | |
| catchCopy | No | Catch copy. | |
| groupCode | No | Group code. | |
| categoryId | Yes | Category id (smaregi_list_categories). | |
| description | No | Description. | |
| displayFlag | No | Show on the register (0 = hidden, 1 = shown). | |
| productCode | No | Product code (unique per contract). | |
| productKana | No | Product name, kana. | |
| productName | Yes | Product name. | |
| taxDivision | No | Tax division code (0 = tax included, 1 = tax excluded, 2 = tax free). | |
| customerPrice | No | Member price. | |
| salesDivision | No | Sales accounting: 0 = counted in sales (default), 1 = excluded from sales totals. Does not control whether the product can be sold; use displayFlag to hide it from the register. | |
| supplierProductNo | No | Supplier's product number. | |
| productPriceDivision | No | Price division: 1 = standard price (default), 2 = open price. | |
| stockControlDivision | No | Stock control: 0 = stock is managed (default), 1 = stock is not managed. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, idempotentHint=false and openWorldHint=true, so "WRITE" and "Not idempotent" restate structured data rather than adding to it. The description says nothing about error behavior on duplicate productCode, whether the created record can be rolled back, rate limits, or what the call returns.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, front-loaded with the operation type and its required inputs, then the idempotency caveat and the endpoint. Nothing extraneous.
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 21-parameter mutation with no output schema, the description leaves out what comes back (e.g., the new productId) and what happens on conflict. Interaction with smaregi_update_product and the category prerequisite are only discoverable inside the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already explains every field, including the localId-relevant categoryId reference to smaregi_list_categories and the enums-in-prose for division, taxDivision and displayFlag. The description only repeats the three required names, adding no semantics beyond the schema's own required array.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
"WRITE: create a product" gives a specific verb and resource, and the WRITE prefix cleanly separates it from the read siblings (smaregi_get_product, smaregi_list_products). It does not explicitly contrast with smaregi_update_product, so the distinction is inferable rather than stated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to create vs. update, what to do when a product with the same productCode already exists, or what preconditions apply (categoryId must come from smaregi_list_categories — that hint lives only in the schema). "Not idempotent" is a retry warning, not usage routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One product category by id. GET /categories/{category_id}.
| Name | Required | Description | Default |
|---|---|---|---|
| fields | No | Comma-separated top-level field names to return (e.g. productId,productName); fewer fields = smaller replies. | |
| category_id | Yes | Numeric Smaregi id (string or number). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered. The description adds the REST endpoint path, which is mildly useful context, but says nothing about not-found behavior, field projection effects, or reply size beyond what the schema hints.
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 terse sentences, zero filler, with the identity of the tool front-loaded before the endpoint detail. Nothing extraneous.
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-resource read tool with full schema coverage and clear annotations, the description supplies enough to call it correctly. The only gap is absence of return-shape or error context, which is minor given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so both parameters are documented in the schema itself, including the fields projection and id format. The description adds nothing beyond the schema on parameters, 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 ('One product category by id') and the underlying endpoint, which distinguishes it from the plural retrieval siblings like smaregi_list_categories by virtue of the singular/by-id framing. It doesn't explicitly name the sibling, but the resource 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?
'by id' implies the usage condition (you already have a category id), but the description never says when to prefer this over smaregi_list_categories or what to do if the id is unknown. 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.
One customer by id, optionally with the contract's custom fields. Contains personal data. GET /customers/{customer_id}.
| Name | Required | Description | Default |
|---|---|---|---|
| fields | No | Comma-separated top-level field names to return (e.g. productId,productName); fewer fields = smaller replies. | |
| customer_id | Yes | Numeric Smaregi id (string or number). | |
| with_custom_fields | No | Add the custom field values. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
While annotations cover readOnlyHint, the description adds crucial behavioral context not present in the structured data: it discloses that the data 'contains personal data' (a sensitivity requirement) and specifies the exact API endpoint format ('GET /customers/{customer_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?
The definition is extremely concise, using two short, highly efficient sentences to cover the core function, the optional data behavior, and the technical method/resource path without any 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?
Given that this is a simple GET operation, the description provides all necessary context: it retrieves a single entity, uses a customer ID, handles optional custom field expansion, and flags the nature of the data. No critical information 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?
Since the input schema coverage is 100%, the structured schema provides comprehensive semantic definitions for all parameters. The description does not add any clarifying meaning or constraints to the specific parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the action ('Get'), the resource ('customer'), and the primary retrieval method ('by id'). It effectively distinguishes this single-fetch operation from list operations present in the sibling 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?
The description implies usage: use this when a specific customer ID is known. However, it does not explicitly state 'use this instead of list_customers' or provide clear exclusionary criteria for other retrieval methods.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One product by id, optionally with store prices, bundled items, store assignments, reserved stock, attribute items and order settings. GET /products/{product_id}.
| Name | Required | Description | Default |
|---|---|---|---|
| product_id | Yes | Numeric Smaregi id (string or number). | |
| with_prices | No | Add the store/period-specific prices. | |
| with_stores | No | Add the store assignments. | |
| with_order_setting | No | Add the ordering settings. | |
| with_reserve_items | No | Add the free-form reserve items. | |
| with_attribute_items | No | Add the attribute items. | |
| with_inventory_reservations | No | Add the inventory reservations. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description usefully signals that extra sub-resources are opt-in, but it never says that toggling those flags increases payload size or latency, nor anything about error behavior for a missing 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 short sentences with the core action (one product by id) front-loaded and the expansions following. The trailing REST endpoint adds minor navigational value and costs almost nothing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 7-parameter read tool with only one required argument, full schema coverage and no output schema, the description conveys the shape of the call adequately. The loose naming of some optional expansions is the only real gap an agent could stumble on.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents every flag, and the baseline is 3. The description's enumeration mostly mirrors the flags, with slight drift — it mentions "bundled items" and "reserved stock" while the actual parameters are with_reserve_items, with_inventory_reservations and with_attribute_items — so it adds little precision beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource — fetch one product by id — and lists the optional sub-resources that can be pulled in. It implicitly contrasts with smaregi_list_products ("one product" vs. a list) but never names that sibling, so differentiation is inferential rather than explicit.
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?
Using this for a single known id is strongly implied, and the optional with_* expansions hint at a fetch-what-you-need pattern. There is no explicit statement of when to prefer smaregi_list_products or the update/create siblings, and no guidance on when to leave the expansion flags off.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One staff member by id. GET /staffs/{staff_id}.
| Name | Required | Description | Default |
|---|---|---|---|
| fields | No | Comma-separated top-level field names to return (e.g. productId,productName); fewer fields = smaller replies. | |
| staff_id | Yes | Numeric Smaregi id (string or number). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds endpoint context and the single-record scope, but does not mention error behavior such as an unknown id or what happens with the optional fields parameter.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with zero filler, and the key fact (single staff member by id) is front-loaded. Every clause contributes to identifying the operation.
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?
Adequate for a simple two-parameter read tool, especially given complete schema coverage and strong annotations. However, with no output schema, the description could say more about the returned staff record or missing-id behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both parameters are already documented in the schema. The description only reinforces that staff_id selects one staff member and adds no extra meaning about the fields parameter or id formatting.
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 retrieval action and resource: one staff member by id, plus the underlying endpoint. The singular 'one staff member' implicitly distinguishes it from list_staffs, but it does not explicitly name the sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives no guidance on when to use this tool versus smaregi_list_staffs or other staff-related tools. There are no exclusions, prerequisites, or alternative-selection cues beyond the implied single-record lookup.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One store by id. GET /stores/{store_id}.
| Name | Required | Description | Default |
|---|---|---|---|
| fields | No | Comma-separated top-level field names to return (e.g. productId,productName); fewer fields = smaller replies. | |
| store_id | Yes | Numeric Smaregi id (string or number). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds only the underlying GET route, which confirms a non-mutating single-resource lookup, but says nothing about not-found behavior, permissions, or response 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?
Two short sentences, front-loaded with the resource scope before the route. Nothing is wasted, but the brevity borders on under-specification rather than polished concision.
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 single-record read with full schema coverage and clear read-only annotations, the essentials are present. Missing is any hint of the returned payload or how a missing/invalid store id is surfaced, which matters since 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 coverage is 100%, so both parameters (store_id, fields) are fully documented in the schema, including the numeric-id format and the field-projection pattern. The description's 'by id' adds nothing beyond that, which is the expected baseline when the schema does the work.
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: fetch one store by id, plus the exact HTTP route GET /stores/{store_id}. It is distinguishable from the list counterpart by 'One store' vs a collection, though it never names smaregi_list_stores explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied by 'by id'; there is no statement of when to prefer this over smaregi_list_stores or what to do when the id is unknown. No prerequisites or exclusions are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One transaction (receipt) by its transaction id (transactionHeadId), optionally with line items, discounts and payments. Contains personal data. GET /transactions/{transaction_id}.
| Name | Required | Description | Default |
|---|---|---|---|
| with_details | No | Add the line items. | |
| with_payments | No | Add the payments. | |
| transaction_id | Yes | The transactionHeadId. | |
| with_discounts | No | Add the discounts. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds genuinely useful context beyond that — the 'Contains personal data' PII warning and the underlying GET /transactions/{transaction_id} endpoint mapping — but says nothing about not-found behavior, errors, or response 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?
Three short, front-loaded sentences with the resource, the expansion options and the PII caveat each given a clause. The trailing endpoint reference is mildly redundant but cheap and aids API cross-referencing.
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 describing returns. It names the expansions but not the shape of the returned transaction, nor behavior for missing/invalid IDs, leaving a moderate gap for a single-fetch tool flagged as containing personal data.
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 documented in the schema itself, including the ID's string-or-integer union and pattern. The description only restates the flags collectively as 'optionally with line items, discounts and payments' and adds no format or default semantics on top of the schema — baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource — fetch a single transaction (receipt) by transactionHeadId — and enumerates the optional expansions (line items, discounts, payments). The singular/plural contrast with smaregi_list_transactions is implicit rather than named, so it stops short of explicit 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?
Usage is only implied: 'by its transaction id' signals that an ID must already be known, which indirectly points to the list tool for discovery. There is no explicit when-to-use/when-not guidance, no mention of what to do if the ID is unknown, and no prerequisite statements.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List product categories (departments): id, code, name, parent, level. Use the ids when creating or filtering products. GET /categories.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number, from 1 (default 1). Pass the previous reply's next_page. | |
| sort | No | Sort order: comma-separated field names, ':desc' for descending (e.g. updDateTime:desc). | |
| limit | No | Results per page, 1-500 (default 50). | |
| fields | No | Comma-separated top-level field names to return (e.g. productId,productName); fewer fields = smaller replies. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the field list and the underlying endpoint (GET /categories), but says nothing about result volumes, pagination behavior, or ordering that would help an agent plan a follow-up call.
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: the payload shape first, then the actionable guidance. Nothing is padded and the most useful information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple, fully annotated read-only list tool with complete schema coverage and no output schema, this covers what the agent needs. A brief note that results are paginated would fully close the gap, but the schema already carries that.
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 four paging/sort/fields parameters are fully documented in the schema, including the cursor-style 'pass the previous reply's next_page' hint. The description adds no parameter detail, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ('List product categories') and enumerates the returned attributes (id, code, name, parent, level), which clearly separates it from the singular smaregi_get_category sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides a concrete downstream usage cue ('Use the ids when creating or filtering products'), giving the agent a reason to call this before smaregi_create_product or smaregi_list_products. It does not explicitly say when to prefer this over the single-record smaregi_get_category, so it stops short of full routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List customers (members): id, code, number, name, phone, e-mail, address. Smaregi cannot search by name, phone or e-mail: filter by customer code, member number, id range or update time, or page through. Contains shoppers' personal data. GET /customers.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number, from 1 (default 1). Pass the previous reply's next_page. | |
| sort | No | Sort order: comma-separated field names, ':desc' for descending (e.g. updDateTime:desc). | |
| limit | No | Results per page, 1-500 (default 50). | |
| fields | No | Comma-separated top-level field names to return (e.g. productId,productName); fewer fields = smaller replies. | |
| updated_to | No | Only customers changed at or before this date-time (31 days at most). | |
| customer_no | No | Only the customer with this member number. | |
| updated_from | No | Only customers changed at or after this date-time (ISO 8601 with timezone). | |
| customer_code | No | Only the customer with this exact customer code. | |
| customer_id_to | No | Only customers with an id at or below this. | |
| customer_id_from | No | Only customers with an id at or above this. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered; the description adds the non-obvious behavioral constraint that Smaregi cannot search by name/phone/e-mail and flags that the payload contains shoppers' personal data. No mention of rate limits or reply size limits beyond what the schema states.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences: returned fields first, then the search constraints and alternatives, then the PII caveat. Every sentence carries actionable information with no 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 and 100% schema coverage on ten optional params, the description supplies the missing pieces: what is returned, how to filter given the name/phone limitation, and a data-sensitivity warning. Nothing essential for a correct first call is absent.
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 3 is the baseline; the description earns an extra point by explaining the intended filtering strategy (code, member number, id range, update time, pagination) that a caller would otherwise have to infer by reading all ten property descriptions. It adds strategy, not syntax, but that strategy is the piece the schema lacks.
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 plus the exact fields returned (id, code, name, phone, e-mail, address) and the underlying endpoint GET /customers, so the agent knows precisely what comes back. It does not, however, acknowledge the sibling smaregi_get_customer, which overlaps with the single-record filter modes it describes.
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 rules out searching by name, phone or e-mail and redirects to the supported filters (customer code, member number, id range, update time) or paging — a clear 'how to use' instruction that prevents failed attempts. No explicit when-not condition vs. get_customer, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List products with id, category, code, name, price, cost and update time. Filter by category, code, group code, display flag or update time (a 31-day maximum range). GET /products.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number, from 1 (default 1). Pass the previous reply's next_page. | |
| sort | No | Sort order: comma-separated field names, ':desc' for descending (e.g. updDateTime:desc). | |
| limit | No | Results per page, 1-500 (default 50). | |
| fields | No | Comma-separated top-level field names to return (e.g. productId,productName); fewer fields = smaller replies. | |
| group_code | No | Only products with this group code. | |
| updated_to | No | Only products changed at or before this date-time (the range may span 31 days at most). | |
| category_id | No | Only products of this category id. | |
| display_flag | No | 1 = shown on the register, 0 = hidden. | |
| product_code | No | Only the product with this exact product code. | |
| updated_from | No | Only products changed at or after this date-time (ISO 8601 with timezone). | |
| supplier_product_no | No | Only products with this supplier product number. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the returned field set and the 31-day window constraint, but the window is largely duplicated in the updated_to schema field, and it says nothing about pagination flow (next_page) or reply size behaviour that the page/limit/fields parameters imply.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences with the resource and returned fields front-loaded, then the filter scope. The trailing 'GET /products' is minor but useful noise for endpoint mapping; nothing else 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?
For an 11-parameter, non-destructive list tool with no output schema and full schema documentation, the description covers enough: what comes back (id, category, code, name, price, cost, update time) and which filters exist. The main omission is any hint that results are paginated and that callers should follow next_page.
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 11 parameters are already documented in the schema, which sets the baseline at 3. The description names five of the filter dimensions (category, code, group code, display flag, update time) but omits supplier_product_no, sort, fields and the paging parameters, adding only marginal value over the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource ('List products') and enumerates the returned fields plus the available filters, so the agent knows exactly what this returns. It never names smaregi_get_product as the single-record alternative, so sibling differentiation is only inferable from the list-vs-get naming, not stated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The filter list and the '31-day maximum range' note give real context about how to narrow results, which is beyond a bare purpose statement. However, there is no explicit when-to-use guidance against smaregi_get_product, no note on when to paginate, and no exclusions, so 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 staff members: id, code, name, role, e-mail. Passwords are never returned. GET /staffs.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number, from 1 (default 1). Pass the previous reply's next_page. | |
| sort | No | Sort order: comma-separated field names, ':desc' for descending (e.g. updDateTime:desc). | |
| limit | No | Results per page, 1-500 (default 50). | |
| fields | No | Comma-separated top-level field names to return (e.g. productId,productName); fewer fields = smaller replies. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered; the description adds genuinely useful context that passwords are never returned, plus the endpoint 'GET /staffs'. It adds no detail on ordering defaults, page size behavior, or what an empty result looks like, so it remains modest 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?
Three short sentences with zero filler: purpose and returned fields first, the security caveat second, the endpoint last. Nothing is buried or 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?
For a read-only list endpoint with full schema coverage and no output schema, the description covers purpose, returned fields, and a key data-sensitivity caveat. A note on pagination semantics (using next_page from the prior reply) would fully round it out, though the schema already carries that.
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 each of the four parameters (page, sort, limit, fields) carries a clear description including defaults and formats. The tool description adds no parameter semantics of its own, 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 staff members') and enumerates the returned fields (id, code, name, role, e-mail), which lets an agent distinguish a bulk list from the singular smaregi_get_staff sibling. It stops short of naming that sibling explicitly, so the differentiation is inferred rather than stated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied: 'List staff members' suggests a collection fetch and the pagination parameters hint at multi-page iteration, but there is no explicit guidance on when to prefer this over smaregi_get_staff for a single record. No exclusions or prerequisites are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List stock levels per store and product (stockAmount, reserved amount). Filter by store or product. Smaregi only lists a product once its quantity has changed at least once. An update-time filter needs both bounds (31 days at most). GET /stock.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number, from 1 (default 1). Pass the previous reply's next_page. | |
| sort | No | Sort order: comma-separated field names, ':desc' for descending (e.g. updDateTime:desc). | |
| limit | No | Results per page, 1-500 (default 50). | |
| fields | No | Comma-separated top-level field names to return (e.g. productId,productName); fewer fields = smaller replies. | |
| store_id | No | Only this store id. | |
| product_id | No | Only this product id. | |
| updated_to | No | Only stock changed at or before this date-time (give updated_from as well). | |
| updated_from | No | Only stock changed at or after this date-time (give updated_to as well). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, non-destructive, openWorld), so the description's contribution is the extra context it supplies: results are incomplete until a product's quantity has changed at least once, and the date filter has a bounded 31-day window requiring both endpoints. That is meaningful behavioral disclosure beyond the structured fields, though return shape and pagination behavior are left unaddressed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four short sentences, front-loaded with the resource and returned quantities before the filtering caveats. The trailing 'GET /stock.' is essentially noise for an agent that has the tool name, but the rest is dense with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an 8-parameter, all-optional read tool with no output schema and annotations covering safety, the description supplies the non-obvious constraints an agent needs to call it correctly. Pagination and sorting are delegated to the schema, which documents them fully, so nothing critical is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so every parameter is already documented, including the updated_from/updated_to pairing note. The description adds only the 31-day maximum window and confirms the store/product filter semantics, which is marginal value over the schema; baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('List stock levels per store and product') and even names the returned quantities (stockAmount, reserved amount), so the agent knows exactly what comes back. It does not explicitly contrast itself with the close sibling smaregi_list_stock_changes, leaving the agent to infer the difference between current levels and change history.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives concrete usage context: filter by store or product, and the update-time filter requires both bounds with a 31-day maximum. The caveat that Smaregi only lists a product once its quantity has changed sets expectations about result completeness. No explicit when-not or named alternative tool (e.g. smaregi_list_stock_changes) is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The stock change history of one product in one store: date, amount, division (sale, purchase, transfer, adjustment...). GET /stock/changes/{product_id}/{store_id}.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number, from 1 (default 1). Pass the previous reply's next_page. | |
| sort | No | Sort order: comma-separated field names, ':desc' for descending (e.g. updDateTime:desc). | |
| limit | No | Results per page, 1-500 (default 50). | |
| fields | No | Comma-separated top-level field names to return (e.g. productId,productName); fewer fields = smaller replies. | |
| store_id | Yes | Numeric Smaregi id (string or number). | |
| product_id | Yes | Numeric Smaregi id (string or number). | |
| target_date | No | Only changes of this target date, as Smaregi formats it (yyyy-mm-dd). | |
| stock_division | No | Only changes of this stock division code. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds the useful detail of what a record contains (date, amount, division), but says nothing about pagination behavior, result size, or whether an unknown product/store errors versus returning empty — all of which the agent would benefit from knowing.
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 single sentence naming the resource and its scope, followed by the returned fields. The trailing GET path is arguably redundant for an agent, but it is short and does no harm.
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 a fully documented schema and no output schema, the description gives enough to call it correctly: scope, returned fields, and the division vocabulary. Only the routing versus smaregi_list_stock and pagination expectations are 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 coverage is 100%, so page, sort, limit, fields, target_date, and stock_division are all documented in the schema itself. The description adds no filter semantics beyond restating the product/store scoping, 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 ('stock change history') along with the exact scope: one product in one store. It implicitly separates itself from smaregi_list_stock (current stock) and smaregi_adjust_stock (mutation) via the word 'history', but it never names those siblings to make the boundary explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied by the word 'history' and the presence of a target_date filter. There is no explicit when-to-use or when-not-to-use guidance, and no pointer to smaregi_list_stock for current levels or smaregi_adjust_stock for corrections, which are the obvious alternatives in this sibling set.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the stores (shops) of the Smaregi contract: id, code, name, address, phone. Use the ids to filter stock and transactions. GET /stores.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number, from 1 (default 1). Pass the previous reply's next_page. | |
| sort | No | Sort order: comma-separated field names, ':desc' for descending (e.g. updDateTime:desc). | |
| limit | No | Results per page, 1-500 (default 50). | |
| fields | No | Comma-separated top-level field names to return (e.g. productId,productName); fewer fields = smaller replies. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true and destructiveHint=false, so safety is covered. The description adds value by naming the concrete fields returned (id, code, name, address, phone) and the underlying endpoint GET /stores, giving an agent a picture of the response shape despite no output schema. It does not discuss pagination behavior, which the schema covers instead.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, front-loaded with the core verb and resource, followed by returned fields and the practical downstream use. "GET /stores" is marginally low-value but cheaply signals the endpoint. No filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description compensates by listing the returned fields, which is the main thing an agent needs. Pagination, sorting and sparse fieldsets are handled entirely by the 100%-covered input schema, and read-only safety is carried by annotations, so nothing critical is missing; only explicit sibling differentiation would make it 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 page, sort, limit and fields are all fully documented in the schema including defaults, ranges and examples. The description adds nothing about parameters beyond the implicit point that returned fields include the listed attributes. 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 the stores (shops) of the Smaregi contract") and enumerates the returned fields, so an agent knows exactly what comes back. It does not distinguish itself from the sibling smaregi_get_store, which likely fetches a single store, so the list-vs-single contrast is left implicit.
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?
"Use the ids to filter stock and transactions" gives a useful downstream purpose, implying when this tool is a prerequisite for stock/transaction calls. However it offers no explicit when-not guidance and no mention of when to prefer smaregi_get_store over this list, so usage remains 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.
List sales transactions (receipts) in a time window of at most 31 days: id, date-time, division (1 = normal sale, 2 = deposit, 3 = withdrawal...), store, terminal, customer, totals. Optionally with the line items (limit 100 then). Contains shoppers' personal data. GET /transactions.
| Name | Required | Description | Default |
|---|---|---|---|
| to | Yes | End of the window (at most 31 days after from). | |
| from | Yes | Start of the window: transaction date-time (when Smaregi received it), ISO 8601 with timezone. | |
| page | No | Page number, from 1 (default 1). Pass the previous reply's next_page. | |
| sort | No | Sort order: comma-separated field names, ':desc' for descending (e.g. updDateTime:desc). | |
| limit | No | Results per page, 1-500 (default 50). | |
| fields | No | Comma-separated top-level field names to return (e.g. productId,productName); fewer fields = smaller replies. | |
| store_id | No | Only this store id. | |
| with_details | No | Add the line items: none (default), summary or all. Any other value than none caps limit at 100. | |
| customer_code | No | Only this customer code. | |
| transaction_uuid | No | Only the transaction with this receipt number. | |
| transaction_head_division | No | Transaction division: 1 normal sale, 2 deposit, 3 withdrawal, 4 advance payment, 5 advance refund, 6 points added, 7 points deducted, 8 points expired, 9 coupon ticket, 11 tip, 13 miles added, 14 miles deducted, 15 value card deposit, 16 receipt. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuine context beyond that: the 31-day hard window, the effective 100-row cap when line items are requested, and the warning that responses contain shoppers' personal data. It does not describe pagination behavior beyond the schema, keeping it out of 5 territory.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
It is a compact, front-loaded block that leads with the verb and resource, then scope, then return content, then caveats. The inline division-code gloss partly duplicates the enum documentation, which is minor waste but not damaging.
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 read tool with no output schema, the description usefully summarizes the returned fields, the window constraint, the line-item tradeoff and the privacy caveat. Only the routing to the single-receipt sibling 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 the schema already explains every parameter including defaults, pagination and the division enum. The description largely restates the division codes and the with_details limit cap that the schema already spells out, adding little new 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 uses a specific verb and resource ('List sales transactions (receipts)') and scopes it to a window of at most 31 days, then enumerates the returned fields. It separates itself from the singular smaregi_get_transaction only implicitly by being a windowed list, and never names the sibling directly, so it falls short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 31-day window bound and the note that requesting line items caps the limit at 100 do give some operational guidance, and the personal-data warning signals caution. However, there is no explicit statement of when to prefer this over smaregi_get_transaction or how the optional filters (customer_code, store_id, transaction_uuid) change the mode of use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
WRITE: set the absolute stock quantity of one product in one store, replacing the current quantity. Use smaregi_adjust_stock for a relative change. PATCH /stock/{product_id}.
| Name | Required | Description | Default |
|---|---|---|---|
| memo | No | Note stored in the stock history. | |
| store_id | Yes | Numeric Smaregi id (string or number). | |
| product_id | Yes | Numeric Smaregi id (string or number). | |
| stock_amount | Yes | The new quantity. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds the crucial specificity of what is destroyed: the current quantity is replaced, not incremented. It does not cover auth/permission requirements or whether the memo is written to stock history, which keeps it just short of 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three terse clauses, front-loaded with the WRITE marker and the absolute-vs-relative distinction before the endpoint. No filler sentences.
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 4-parameter mutation with full schema coverage, annotations covering the safety profile, and no output schema to explain, the description carries what matters. The only real gap is the unmentioned optional memo parameter and any permission prerequisites.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3, but the description adds genuine meaning the schema lacks: stock_amount is an absolute level that overwrites, not a delta — the schema only says 'The new quantity.' It also frames product_id/store_id as a single product in a single store pairing.
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 quantity of one product in one store — and adds the PATCH endpoint. It explicitly distinguishes itself from the sibling smaregi_adjust_stock, so an agent can route 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?
Names the alternative (smaregi_adjust_stock) and the exact condition that selects it (relative change vs. absolute set). That is an explicit when-to-use-which rule, not an implied one.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
WRITE: change fields of one customer (only the fields you pass are changed). Overwrites the old values. PATCH /customers/{customer_id}.
| Name | Required | Description | Default |
|---|---|---|---|
| sex | No | Sex: 0 = unknown, 1 = male, 2 = female. | |
| note | No | Note. | |
| rank | No | Member rank. | |
| note2 | No | Second note. | |
| status | No | Member status: 0 = active, 1 = suspended, 2 = card lost, 3 = withdrawn, 4 = merged. | |
| address | No | Address. | |
| storeId | No | Store id the customer belongs to. | |
| lastKana | No | Last name, kana. | |
| lastName | No | Last name. | |
| postCode | No | Postal code. | |
| birthDate | No | Birth date, yyyy-mm-dd. | |
| entryDate | No | Enrollment (membership start) date, yyyy-mm-dd; some contracts require it when creating a customer. | |
| faxNumber | No | Fax number. | |
| firstKana | No | First name, kana. | |
| firstName | No | First name. | |
| customerNo | No | Customer / member number. | |
| companyName | No | Company name. | |
| customer_id | Yes | Numeric Smaregi id (string or number). | |
| mailAddress | No | E-mail address. | |
| phoneNumber | No | Phone number. | |
| customerCode | No | Customer code (unique per contract). | |
| mobileNumber | No | Mobile number. | |
| departmentName | No | Department name. | |
| mailReceiveFlag | No | Whether the customer accepts guidance mail: 0 = refuse, 1 = allow (default). | |
| pointExpireDate | No | Point expiry date, yyyy-mm-dd; some contracts require it when creating a customer. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds genuine value on top of that: it clarifies PATCH semantics (only passed fields change, omitted fields preserved) and that supplied values overwrite existing ones, which an agent could otherwise easily get wrong. It stops short of mentioning permissions, failure modes, or whether fields can be cleared.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three terse fragments totalling one sentence, front-loaded with the WRITE marker and the essential PATCH semantics. Nothing is padded and no clause is 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?
For a 25-parameter destructive mutation with no output schema, the description covers the write nature, partial-update behavior, and the endpoint. What remains unstated — auth requirements, error behavior, and how to unset a field — are minor but not negligible gaps for a destructive 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 description coverage is 100% across all 25 properties, including enum-like value meanings for sex, status, and mailReceiveFlag, so the schema carries parameter meaning. The description adds no parameter-level detail beyond the general partial-update rule, which is the expected baseline-3 outcome.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
"WRITE: change fields of one customer" is a specific verb + resource, and the parenthetical scopes it to a partial update of a single record. It does not explicitly contrast with smaregi_create_customer, but the create/update distinction is evident from the wording.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus smaregi_create_customer or smaregi_get_customer, and no prerequisites (auth scope, whether the customer must exist) are stated. The partial-update note implies the editing scenario but names no alternative or exclusion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
WRITE: change fields of one product (only the fields you pass are changed), for example its price or name. Overwrites the old values. PATCH /products/{product_id}.
| Name | Required | Description | Default |
|---|---|---|---|
| tag | No | Tag. | |
| url | No | Product URL. | |
| cost | No | Unit cost. | |
| size | No | Size. | |
| color | No | Color. | |
| price | No | Selling price. | |
| division | No | Product division: 0 = normal (default), 1 = prepaid multi-use ticket (only contracts with that feature), 2 = option product. | |
| catchCopy | No | Catch copy. | |
| groupCode | No | Group code. | |
| categoryId | No | Category (department) id, see smaregi_list_categories. | |
| product_id | Yes | Numeric Smaregi id (string or number). | |
| description | No | Description. | |
| displayFlag | No | Show on the register (0 = hidden, 1 = shown). | |
| productCode | No | Product code (unique per contract). | |
| productKana | No | Product name, kana. | |
| productName | No | Product name. | |
| taxDivision | No | Tax division code (0 = tax included, 1 = tax excluded, 2 = tax free). | |
| customerPrice | No | Member price. | |
| salesDivision | No | Sales accounting: 0 = counted in sales (default), 1 = excluded from sales totals. Does not control whether the product can be sold; use displayFlag to hide it from the register. | |
| supplierProductNo | No | Supplier's product number. | |
| productPriceDivision | No | Price division: 1 = standard price (default), 2 = open price. | |
| stockControlDivision | No | Stock control: 0 = stock is managed (default), 1 = stock is not managed. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag destructiveHint=true, idempotentHint=true, and openWorldHint=true, so the safety profile is covered. The description adds genuine value beyond that by disclosing PATCH semantics — "only the fields you pass are changed" — and that passed values overwrite existing ones, which the annotations do not convey. It stops short of mentioning auth/permission needs or failure modes.
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 WRITE marker and the partial-update rule, then the overwrite consequence, then the endpoint. No filler and nothing buried.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 22-parameter mutation tool with full schema coverage and rich annotations, the description covers what matters most: it is a write, it is a partial update, and it overwrites. What is missing is how to source the product_id and any contract-level caveats (e.g., division changes requiring specific contract features), which the schema hints at but the description does not reinforce.
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 every one of the 22 parameters carries its own description (including enum-like meanings for division, taxDivision, salesDivision), so the schema does the heavy lifting. The description only gives "price or name" as illustrative examples and adds no format, constraint, or interaction detail beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
"WRITE: change fields of one product" gives a specific verb (change/update), resource (one product), and scope (single record), plus the HTTP verb and path (PATCH /products/{product_id}). It is unmistakably distinct from sibling smaregi_create_product and smaregi_update_customer without needing to open 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?
The description establishes the update context and implicitly distinguishes itself from creation by saying "change fields of one product," but it never explicitly says when to use this over smaregi_create_product, nor how to obtain a valid product_id (e.g., via smaregi_list_products or smaregi_get_product). 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.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
smaregi_adjust_stocksmaregi_create_customersmaregi_create_productsmaregi_get_categorysmaregi_get_customersmaregi_get_productsmaregi_get_staffsmaregi_get_storesmaregi_get_transactionsmaregi_list_categoriessmaregi_list_customerssmaregi_list_productssmaregi_list_staffssmaregi_list_stocksmaregi_list_stock_changessmaregi_list_storessmaregi_list_transactionssmaregi_set_stocksmaregi_update_customersmaregi_update_productQuery Loyverse POS receipts, shifts, items, inventory and customers, and update stock and customers.
Read store products, orders, customers, categories and coupons; adjust inventory and update orders.
Read Megaventory products, stock, orders and partners; create clients, sales and purchase orders.
Read Lightspeed R-Series items, stock, sales, customers and POs; create customers and set stock.
Add one secure layer between your agents and this server.