Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@kronan-mcp Search for gluten-free bread in Reykjavik"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MCP server for the Krónan grocery store API. Claude can browse products, manage shopping notes, handle checkout, and track orders from Krónan's Snjallverslun (smart store) in Iceland.
25 tools over the Model Context Protocol:
Category | Tools |
Products |
|
Checkout |
|
Orders |
|
Shopping notes |
|
Product lists |
|
Purchase stats |
|
Account |
|
Related MCP server: Willys MCP Server
npm install -g kronan-mcpOr run directly with npx (no install needed):
npx kronan-mcpTokens are created in the Krónan Snjallverslun user settings. You need an account with Audkenni (Iceland's electronic ID) login. Go to your user or customer group settings page and create an access token. Tokens are prefixed with act_.
Add to your project's .claude/settings.local.json or global ~/.claude/settings.json:
{
"mcpServers": {
"kronan": {
"command": "npx",
"args": ["kronan-mcp"],
"env": {
"KRONAN_ACCESS_TOKEN": "act_your_token_here"
}
}
}
}Then ask Claude things like:
"Search for milk on Krónan"
"What's in my shopping note?"
"Add 2x of SKU 02500188 to my checkout"
"Show my recent orders"
src/
├── client.ts HTTP client wrapping all Krónan API endpoints
├── index.ts MCP server registering tools via @modelcontextprotocol/sdk
└── types.ts TypeScript interfaces matching the OpenAPI schemaAuth is Authorization: AccessToken <token> on every request. Rate limit is 200 requests per 200 seconds per user. The client detects 429 responses and tells the caller to wait.
All prices are integers in ISK (no decimals). 230 means 230 kr.
Errors go through a typed KronanApiError with status codes. The token is scrubbed from error messages so it doesn't leak to the LLM. Auth failures and rate limits get their own user-facing messages.
set_order_substitution and set_line_completion use read-then-toggle patterns. They're not idempotent. Don't retry on timeout without checking current state first.
Full OpenAPI schema at openapi-schema.yaml.
npm install && npm run build # Build from source
npm run dev # Watch mode (recompiles on change)
npm test # Run tests
npm run test:watch # Watch mode tests31 tests on the HTTP client: constructor validation, error paths (429, timeouts, JSON parse failures), token scrubbing, toggle method validation, eligibility endpoint edge cases.
npm testAdd product lines to the active checkout. Set replace=true to replace all existing lines.
| Name | Required | Description | Default |
|---|---|---|---|
| lines | Yes | Lines to add | |
| replace | No | Replace all existing lines (default: false) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the replace behavior but omits side effects (e.g., whether lines are appended or added), error conditions, or authentication requirements. For a mutation tool, this is minimal.
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 concise, front-loaded sentences with no extraneous information. Every word 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 simple add tool, the description provides basic context. However, with no output schema, return values are unexplained. It does not differentiate from many sibling tools that also modify lines, and lacks guidance on when the checkout is ready for lines.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with descriptions for all parameters. The description adds a hint about replace=true but no further semantics beyond the schema. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (add), resource (product lines), and context (active checkout). It effectively distinguishes this tool from sibling tools that deal with orders, shopping notes, or other checkout actions.
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 hints at usage with the replace flag but does not specify when to use this tool vs alternatives like update_product_list_item or clear_product_list. No exclusions or context about prerequisites (e.g., checkout must be active) are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add a line to the shopping note. Provide exactly one of text (freeform) or sku (linked product), not both.
| Name | Required | Description | Default |
|---|---|---|---|
| sku | No | Product SKU to link (mutually exclusive with text) | |
| text | No | Freeform text for the line (mutually exclusive with sku) | |
| quantity | No | Quantity |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description bears full responsibility. Only states the action and mutual exclusivity without disclosing ordering, permissions, side effects, or behavior when quantity is omitted.
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, no wasted words, front-loaded with the purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for a simple parameter set with full schema coverage, but no output schema and missing details on success/error behavior or constraints.
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 description adds minor value by restating mutual exclusivity already present in schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Add a line to the shopping note' with a specific verb and resource. It also distinguishes from sibling tools like change_shopping_note_line and delete_shopping_note_line.
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 guidance on mutual exclusivity of text and sku, but lacks context on when to use this tool versus alternatives or when to prefer text over sku.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reorder shopping note lines to match the store's aisle layout for efficient in-store shopping
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden for behavioral disclosure. It implies a mutation (reordering) but does not detail side effects, such as whether the original order is overwritten, if the operation is reversible, or any required permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that conveys the tool's action and rationale without any extraneous words. It is well-structured and 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?
Given zero parameters and no output schema, the description is somewhat adequate but lacks details on behavioral traits (e.g., mutation, idempotency) that an agent might need to safely invoke it. It does not mention if the tool operates on the current shopping note or requires a specific context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no parameters, so the description does not need to explain parameters. As per guidelines, 0 parameters yields a baseline of 4. The description adds context about the tool's purpose, which is sufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Reorder shopping note lines' and the purpose 'to match the store's aisle layout for efficient in-store shopping'. It specifies the verb and resource, but does not explicitly differentiate from the sibling tool 'reorder_shopping_note_lines', which may have a similar function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'reorder_shopping_note_lines' or 'sort_product_list'. There are no usage conditions, prerequisites, or exclusions stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update the text or quantity of an existing shopping note line
| Name | Required | Description | Default |
|---|---|---|---|
| text | No | New text | |
| token | Yes | Line UUID token | |
| quantity | No | New quantity |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It only says 'Update', implying mutation, but omits details like whether partial updates are supported, if other fields are preserved, or any side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no wasted words. It is front-loaded with the verb and resource, but could be slightly more structured.
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 update tool, the description covers the basic purpose. However, without output schema or annotations, it lacks behavioral context (e.g., idempotency, error states) and sibling differentiation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description mentions 'text or quantity', but this adds little beyond the schema descriptions. It does not explain values or constraints further.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Update' and the resource 'shopping note line', and specifies the mutable fields (text or quantity). This distinguishes it from siblings like 'add_shopping_note_line' or 'delete_shopping_note_line'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool vs alternatives (e.g., when to update versus delete and re-add). No context about prerequisites or conditions is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check if the shopping note contains products that can be ordered from a store
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of disclosing behavior. It only states the basic check function without revealing side effects (expected to be none), required permissions, or edge cases (e.g., empty shopping note, partial eligibility). This lack of detail limits the agent's ability to anticipate tool behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: a single sentence of 14 words. It is front-loaded with the verb and object, and every word is necessary. There is no superfluous information, making it easy for an agent to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of an output schema, the description does not specify what the tool returns (e.g., boolean, list of eligible items, or error). It also lacks details about prerequisites (e.g., must have a shopping note with products). The description is too minimal for the agent to fully understand the tool's behavior and results.
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 input schema has zero parameters, so schema coverage is 100%. The description adds value by clarifying that the tool operates on the current shopping note, which is not explicitly part of the schema. Since there are no parameters, the baseline is 4, and the description provides useful context 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 clearly states the tool's purpose: checking if products in a shopping note are orderable from a store. It uses a specific verb ('check') and resource ('shopping note products eligibility'). It is distinct from sibling tools like 'apply_store_product_order' (which places orders) and other shopping note 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 provides no guidance on when to use this tool versus alternatives. It does not mention that this is a prerequisite check before ordering, nor does it list any conditions or exclusions. The context implies it should be used before 'apply_store_product_order', but this is not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove all items from a product list without deleting the list itself
| Name | Required | Description | Default |
|---|---|---|---|
| token | Yes | Product list UUID token |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. Description only states the action without disclosing behavioral traits such as irreversibility, side effects, or whether it triggers notifications. Lacks important safety context for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, extremely concise and front-loaded with essential information. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool is simple with 1 parameter and no output schema. Description is adequate but lacks information on return value or confirmation of action. Could be more complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with parameter 'token' described as 'Product list UUID token'. Description adds no additional meaning beyond the schema, meeting baseline expectation.
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?
Description clearly states verb 'remove all items' from a product list, and distinguishes from sibling 'delete_product_list' by specifying it does not delete the list itself. Also contrasts with 'clear_shopping_note' for a different resource.
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?
Description implies usage for clearing a product list without deletion, but does not explicitly state when to use it vs alternatives like 'update_product_list' or 'delete_product_list'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete all lines from the shopping note (the note itself is preserved)
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, description notes that the note itself is preserved, which is a key behavioral trait. Could mention irreversibility or permissions, but for a simple operation it is sufficient.
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?
Single sentence, no unnecessary words. Front-loaded with action and resource.
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?
Complete for a tool with no parameters and no output schema. Sufficient for agent to understand and invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, and schema coverage is 100%. Description adds value by explaining the tool's action beyond the schema, which is empty.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the verb 'delete' (all lines) and resource 'shopping note', with explicit note that the note itself is preserved. Distinguishes from sibling 'delete_shopping_note_line' which deletes a single line.
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?
Implied usage: use when needing to clear all lines while keeping the note. No explicit when-not or alternative mentioned, though sibling tools exist for finer-grained operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new product list
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | List name | |
| description | No | List description |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description should disclose behavioral traits beyond creation. It only states 'Create' without mentioning side effects, permissions, or return behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise but lacks necessary detail. It does not waste words but fails to provide valuable context.
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 no annotations, the description is insufficient for a create operation. It does not explain what the tool returns or any side effects, leaving the agent underinformed.
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 input schema covers 100% of parameters with descriptions. The tool description adds no additional meaning beyond the schema, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'create' and the resource 'product list', making the tool's purpose understandable. However, it does not differentiate from sibling tools like 'update_product_list' or 'get_product_list'.
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 usage guidelines are provided. The description does not indicate when to use this tool versus alternatives, nor does it mention any prerequisites or context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove a specific archived shopping note line
| Name | Required | Description | Default |
|---|---|---|---|
| token | Yes | Archived line UUID token |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description only says 'Remove', which implies destruction, but provides no additional behavioral context such as permanence, side effects, or permissions. With no annotations, the description carries full burden but is minimal.
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?
Single sentence, front-loaded verb, zero wasted words. Perfectly concise for the tool's simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the tool's primary action but lacks return value or confirmation message. For a simple delete, missing output info is a minor gap; could be more complete with typical return expectations.
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 description does not add meaning beyond the schema's 'Archived line UUID token'. While sufficient, no extra context (e.g., how to obtain token) is provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Remove') and the target resource ('specific archived shopping note line'), effectively distinguishing it from siblings like delete_shopping_note_line (active lines) or clear_shopping_note (all lines).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. It does not specify prerequisites (e.g., must have archived line) or when not to use it (e.g., for active lines), leaving the agent to infer from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove specific lines from an order by their IDs. Service lines and the last remaining line cannot be deleted.
| Name | Required | Description | Default |
|---|---|---|---|
| token | Yes | Order token | |
| lineIds | Yes | IDs of lines to delete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses important behavioral restrictions (cannot delete service lines or the last line), but does not discuss side effects, permissions, or irreversibility. Adequate but not comprehensive.
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: first states purpose, second provides key constraints. No unnecessary words. Front-loaded with essential 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?
The description covers purpose and main restrictions, but lacks information about return values, error cases, or whether the operation is reversible. For a deletion tool with no output schema and no annotations, more detail would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for both parameters. The description adds context by reiterating the operation and introducing constraints that affect parameter usage, adding value 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 clearly states the action (remove lines), the object (from an order), and the method (by their IDs). It also distinguishes from sibling tools by specifying 'from an order' and adding constraints about what cannot be deleted.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides constraints on when not to use (service lines and last line cannot be deleted), but lacks explicit guidance on when to use this tool over alternatives like delete_shopping_note_line or delete_product_list. No comparison with siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Permanently delete a product list and all its items
| Name | Required | Description | Default |
|---|---|---|---|
| token | Yes | Product list UUID token |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. 'Permanently delete' indicates destructiveness but lacks details on irreversibility, permissions required, or side effects (e.g., cascading deletions). This is insufficient for a destructive operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-formed sentence that conveys the essential information with no redundancy or unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (one parameter, no output schema) and the description covers the basic action. However, given siblings like clear_product_list, a brief note on when to delete vs clear would improve completeness. As it stands, it is minimally adequate.
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% for the only parameter (token), and the schema already describes it as 'Product list UUID token'. The description adds no additional meaning or context beyond what the schema provides, 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?
The description clearly states the action ('permanently delete') and the target resource ('a product list and all its items'), using a specific verb and resource. It implies distinction from siblings like clear_product_list, which likely only removes items.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like clear_product_list or update_product_list. The description does not mention prerequisites, when deletion is appropriate, or what distinguishes it from similar tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove a line from the shopping note
| Name | Required | Description | Default |
|---|---|---|---|
| token | Yes | Line UUID token |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It only mentions removal without disclosing side effects, reversibility, or permissions needed. This is insufficient for a destructive operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no redundancy. However, it could include additional structural elements like prerequisites or outcome without losing conciseness.
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 delete operation with one parameter and no output schema, the description is minimally adequate. It lacks information about return values, errors, or confirmation of deletion.
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% (the 'token' parameter has a description). The tool description does not add meaning beyond the schema, so baseline score 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?
The description clearly states the action and resource ('Remove a line from the shopping note'), but does not explicitly differentiate from sibling tools like 'change_shopping_note_line' or 'clear_shopping_note'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives such as 'add_shopping_note_line' or 'change_shopping_note_line'. The usage context is implied but not stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get paginated product listing for a category (48 per page)
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number (default: 1) | |
| slug | Yes | Category slug |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description mentions pagination (48 per page), which is a behavioral trait. Without annotations, it carries the burden but fails to disclose other behaviors such as authentication requirements or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. However, it could include more context without sacrificing conciseness.
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 listing tool with no output schema, the description does not explain return structure, sorting, or filtering, leaving the agent with insufficient context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for both parameters (slug and page), so the description adds no extra meaning. Baseline 3 as per guidelines.
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 specific verb 'Get' and resource 'paginated product listing for a category', clearly distinguishing from sibling tools like search_products or get_product.
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 for listing products in a category, but does not explicitly state when to use over alternative tools like search_products or get_product, nor when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the active smart checkout (auto-creates if none exists)
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses a key behavioral trait: auto-creation if none exists. With no annotations provided, this side-effect disclosure is crucial. However, it does not mention other behaviors like idempotency, error handling, or potential state changes.
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 sentence that fully conveys the purpose and key behavior. No unnecessary words; every part 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?
The description is adequate for a zero-parameter, no-output-schema tool. It explains the primary action and the unexpected auto-create side effect. However, it could hint at return type or error scenarios to be 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?
The input schema has zero parameters, so schema coverage is 100%. The description adds no parameter information, but none is needed. Per rubric with high coverage, baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies the action ('Get') and resource ('active smart checkout'), and distinguishes itself by noting the auto-creation behavior, which differentiates it from other getters among siblings like 'get_me'.
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?
While the description implies this is for retrieving the active checkout before performing operations (e.g., adding lines via 'add_checkout_lines'), it lacks explicit when-to-use or when-not-to-use guidance, and does not mention alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the current authenticated identity (user or customer group)
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description should disclose behavioral traits. It merely states it 'gets' identity, implying a read, but does not mention authentication requirements, side effects, idempotency, or any constraints.
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?
Single sentence, no wasted words. Front-loaded with verb and object. Perfectly concise.
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?
Description is minimal but covers core purpose. With no output schema, it partially explains the return value (user or customer group). However, it could elaborate on the structure of the response to be 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?
Input schema has zero parameters and 100% coverage. The description adds no parameter details (none needed). Baseline score of 4 applies per instructions for no-parameter tools.
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?
Description clearly specifies the action ('get'), the resource ('current authenticated identity'), and the scope ('user or customer group'). It is unambiguous and distinguishes from 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?
No sibling tool serves the same purpose, so usage guidelines are not critical. The description implies use when needing current identity information, but lacks explicit when-to-use or when-not-to-use context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get full order details including lines with product thumbnails
| Name | Required | Description | Default |
|---|---|---|---|
| token | Yes | Order token |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full responsibility for behavioral disclosure. It does not state whether the tool is read-only, requires authentication, or has any side effects. It only describes the return content, not behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that immediately conveys the tool's purpose. No extraneous 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?
Without an output schema, the description should fully specify the return structure. It mentions lines and product thumbnails but omits other possible fields. It also lacks context on permissions or typical use cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with one parameter described as 'Order token'. The description adds no additional meaning beyond the schema, so baseline 3 is appropriate. It does not explain what a token is or how to obtain it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Get' and clearly identifies the resource 'full order details', including lines and product thumbnails. This differentiates it from sibling tools like 'list_orders' which list orders but don't retrieve full details.
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 explicit guidance on when to use this tool versus alternatives like 'list_orders' or modification tools. The description does not mention prerequisites or context for use, leaving the agent without decision support.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get full product details including price, discounts, tags, availability
| Name | Required | Description | Default |
|---|---|---|---|
| sku | Yes | Product SKU |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavioral traits. It states 'Get' implying read-only, but does not mention auth requirements, error handling, or response format. This is minimal disclosure for a read operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is front-loaded with the purpose and includes specific product fields. No unnecessary words, earning 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 simple retrieval tool with one required parameter and no output schema, the description provides adequate context: it lists the fields returned. However, it could mention what happens if SKU is invalid or missing, though the schema covers validation. Slightly incomplete but still good.
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% (only one parameter 'sku' with description 'Product SKU'). The description adds no additional meaning to the parameter, as it focuses on output fields. Baseline score 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?
The description clearly states the verb 'Get' and the resource 'full product details', listing specific fields like price, discounts, tags, availability. This distinguishes it from sibling tools such as get_category_products (by category) and search_products (by query).
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 when a product SKU is known, but provides no explicit guidance on when to use this tool vs alternatives like search_products or get_category_products. No exclusion or prerequisite information is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a product list with all items including product details and pricing
| Name | Required | Description | Default |
|---|---|---|---|
| token | Yes | Product list UUID token |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so description must disclose behavioral traits. It only states the action and result, omitting read-only nature, authentication needs, or any side effects. Lacks depth beyond the obvious.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with the verb and resource upfront. No wasted words, though it lacks structured sections.
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 retrieval tool with one parameter and no output schema, the description adequately states what it returns. However, it could clarify the scope (e.g., 'specific product list').
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a description for the token parameter. The tool description adds no additional meaning beyond the schema, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves a product list with items, details, and pricing. It distinguishes from sibling 'list_product_lists' by implying a specific list via the token parameter, but does not explicitly differentiate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this vs siblings like list_product_lists or get_product. The token parameter hints at specificity, but no explicit context or alternatives are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the shopping note (auto-creates if none exists)
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries full burden. It discloses the auto-create side effect, an important behavioral trait, but does not mention other aspects like return format or permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single, focused sentence with no wasted words. Perfectly concise.
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 no output schema, the description should mention return value information, which is missing. The auto-create behavior is covered, but the response format is not specified, making it incomplete.
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?
No parameters exist, so baseline is 4. The description adds no parameter info, which is appropriate given the empty 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 clearly states the verb 'Get' and the resource 'shopping note', and the auto-create behavior distinguishes it from sibling tools that modify or delete the note.
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 use when needing to retrieve the note, but lacks explicit guidance on when not to use or alternatives like add_shopping_note_line.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List previously completed and archived shopping note lines
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but only says 'List', implying a read operation without disclosing details like pagination, ordering, or authentication 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?
A single sentence that is front-loaded with the verb and resource, containing no extraneous words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description should explain return values or format but does not; it minimally states what is returned (lines) without further detail.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, satisfying the baseline of 4; the description adds context about the resource being 'previously completed and archived', which clarifies the scope beyond the empty 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 clearly states the verb 'List' and the resource 'previously completed and archived shopping note lines', making the tool's purpose specific and unambiguous despite no 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?
No guidance on when to use this tool versus alternatives like delete_archived_line; the description only states what it does without context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the full 3-level category tree
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden for behavioral disclosure. It states output is a '3-level category tree' but does not mention side effects, permissions required, rate limits, or whether it is read-only. Basic behavior is implied but incomplete.
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?
Single sentence with 7 words, directly states the tool's purpose with no wasted words. Information is front-loaded and every word 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?
Tool has no parameters, no output schema, and no annotations. The description provides minimal context: it returns a 3-level category tree. For such a simple tool, this may suffice, but it lacks details on the structure, usage, or constraints, leaving gaps in completeness.
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?
Input schema has zero parameters, and schema coverage is 100% (trivially). The description adds meaning by specifying the output structure (full 3-level tree), which aids understanding of what the tool returns, even though there are no parameters to document.
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?
Description states 'Get the full 3-level category tree', which clearly indicates the verb (Get), resource (category tree), and scope (full 3-level). It distinguishes from sibling tools like get_category_products (which retrieves products for a category) and get_me (user info).
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 explicit guidance on when to use this tool versus alternatives. The description does not mention prerequisites, exclusions, or context for usage. Implied usage is that it is for retrieving the entire category hierarchy, but no explicit when-not-to-use or alternative suggestions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List orders, most recent first
| Name | Required | Description | Default |
|---|---|---|---|
| type | No | Filter by order type | |
| limit | No | Results per page | |
| offset | No | Starting index |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description only states the basic listing behavior with sort order. It does not disclose pagination mechanics, rate limits, authentication requirements, or effects on data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that is front-loaded with the core action and sort order. However, it is somewhat terse and could include more detail without becoming verbose.
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 list tool with three parameters and no output schema, the description does not explain return value structure or pagination defaults. It is adequate but not fully complete given the complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents all parameters. The description adds no extra meaning beyond the sort order, but baseline is 3 due to high 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?
The description specifies the verb 'list' and resource 'orders' with a sort order 'most recent first', clearly distinguishing it from the sibling tool 'get_order' which retrieves a single order.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like 'get_order' or other order-related tools, nor any indication of prerequisites or limitations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List saved product lists
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Results per page | |
| offset | No | Starting index |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description must carry the full burden. It only states the action (list) and resource (saved product lists), without disclosing pagination behavior, user scope, or any side effects. This is minimal disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise at three words, with no waste. However, it is almost too brief, lacking context that could be added without sacrificing conciseness.
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 no output schema and no annotations, the description should provide more context such as the scope of lists returned (e.g., user-specific) and the default ordering. It falls short of being complete for a listing tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers both parameters (limit and offset) with descriptions, achieving 100% coverage. The description adds no additional meaning beyond what the schema provides, meeting the baseline.
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 'List saved product lists' clearly states the verb and resource, distinguishing it from siblings like 'get_product_list' (single) and 'create_product_list'. However, it could be more specific by adding 'all' to emphasize the plural nature.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as 'get_product_list' or 'search_products'. The agent is left to infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List previously purchased products with frequency data, ordered by most recent purchase
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Results per page | |
| offset | No | Starting index | |
| includeIgnored | No | Include ignored products |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses ordering by most recent purchase and the inclusion of frequency data, but it does not specify whether the operation is read-only, any authentication needs, or pagination behavior beyond the schema's limit/offset. Without annotations, the description carries a partial burden but adds only basic context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that conveys the essential purpose and output ordering without any extraneous words. It is appropriately efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the description states the output, it lacks details on the structure of frequency data, pagination behavior, and the meaning of the includeIgnored parameter. Given the presence of sibling tools like set_purchase_stat_ignored, more context on ignored products would be helpful. The description is minimally adequate for a list endpoint but incomplete.
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 input schema has 100% coverage for all three parameters (limit, offset, includeIgnored), so the description does not need to add much. It adds context about frequency data and ordering, but this is not tied to specific parameter semantics beyond the schema's documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists previously purchased products with frequency data, ordered by most recent purchase. However, it does not differentiate from sibling tools like set_purchase_stat_ignored, which suggests related functionality but not the same purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, such as search_products or get_product_list. No exclusions or prerequisites are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reduce the quantity of specific order lines. Quantity can only be lowered. Set to 0 to remove.
| Name | Required | Description | Default |
|---|---|---|---|
| token | Yes | Order token | |
| lineIds | Yes | IDs of lines to modify | |
| quantity | Yes | New total quantity (must be lower than current) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses the key behavioral constraint (only lowering) and the zero-removal effect, but lacks details on side effects, permissions, error conditions, or idempotency. Adequate but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no unnecessary words. Every part adds value: the action, the constraint, and the edge case. Front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations or output schema, the description covers the core purpose and constraints. It addresses the main behavioral nuance (only lowering). Missing: prerequisites or error handling, but sufficient for basic tool selection among many siblings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds value by explaining the quantity constraint ('can only be lowered') and the special case of setting to 0 to remove, which the schema only mentions 'must be lower than current' without the removal hint.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it reduces the quantity of order lines, using specific verb 'reduce' and resource 'specific order lines'. It distinguishes from siblings like 'delete_order_lines' by implying quantity reduction rather than line removal, and the 'set to 0 to remove' clarifies an edge case.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage constraints: quantity can only be lowered, and setting to 0 removes the line. It does not explicitly compare to alternatives like 'update_product_list_item', but the constraints are clearly stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reorder shopping note lines by passing their tokens in desired order
| Name | Required | Description | Default |
|---|---|---|---|
| linesTokens | Yes | Line tokens in desired display order |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and the description fails to disclose behavioral traits such as whether it's destructive, if permissions are needed, or what happens with invalid tokens. It only states the basic action.
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?
Single, direct sentence with no unnecessary words. Perfectly concise and 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 tool with no output schema and no annotations, the description is too sparse. It doesn't clarify behavior on error, return value, or any side effects, leaving significant 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 coverage is 100%, and the description adds minimal extra meaning beyond the schema's description of 'linesTokens'. It essentially paraphrases 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 clearly states the action (reorder), the resource (shopping note lines), and the method (by token order). It distinguishes from siblings like sort_product_list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like sort_product_list or when not to use it. The description lacks context about prerequisites or limitations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for products in the smart store selection. Returns products available for home delivery.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number | |
| query | Yes | Search query (max 64 chars) | |
| sortBy | No | Sort field | |
| pageSize | No | Results per page (max 100) | |
| withDetail | No | Include discounted price, discount percent, and tags (slower) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses a key behavioral trait (returns only home delivery products), but does not cover pagination, rate limits, or error behavior. Annotations absent, so description partially carries the burden.
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, no fluff, front-loaded with purpose. Efficient and readable.
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, so description should clarify return format or behavior. It does not explain result structure, pagination behavior beyond schema, or error scenarios. Adequate but not 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?
100% schema coverage with descriptions for all 5 parameters. The tool description adds no extra parameter-level detail; 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?
Clear verb ('Search'), resource ('products'), and scope ('in the smart store selection, for home delivery'). Distinguishes from siblings like get_product (single) or get_category_products (categorized).
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?
Implied usage for searching delivery-eligible products, but no explicit when-to-use vs alternatives (e.g., get_category_products). Lacks mentions of prerequisites or when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Mark a shopping note line as completed or uncompleted. Uses a toggle endpoint: fetches current state and only toggles if needed. WARNING: Not idempotent due to toggle semantics. Do NOT retry on timeout — check current state first.
| Name | Required | Description | Default |
|---|---|---|---|
| token | Yes | Line UUID token | |
| completed | Yes | Desired completion state |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully discloses behavioral traits: the toggle mechanism (fetches current state, toggles only if needed), non-idempotence, and retry warning. This gives the agent crucial safety information.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with three sentences: purpose, mechanism, and critical warning. Every sentence adds value, and the most important information (purpose) 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?
Given the tool's simplicity (boolean toggle, no output schema), the description is mostly complete, covering purpose, behavior, and a key warning. It lacks return value info, but that is a minor gap for this type of tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (both parameters have descriptions: 'Line UUID token' and 'Desired completion state'). The description adds no extra parameter detail beyond what is in the schema, making the baseline score of 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?
The description clearly states that the tool marks a shopping note line as completed or uncompleted, using a specific verb ('Mark') and resource ('shopping note line'). It distinguishes itself from sibling tools (add/change/delete line) by focusing on completion state toggling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides important usage guidance: it explains the toggle endpoint behavior and explicitly warns against retrying on timeout due to non-idempotence, instructing to check current state first. It does not explicitly state when not to use or list alternatives, but the guidance is clear and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set whether substitution is allowed for specific order lines. Uses a toggle endpoint: fetches current state and only toggles lines that differ. WARNING: Not idempotent due to toggle semantics. Do NOT retry on timeout — check current state first.
| Name | Required | Description | Default |
|---|---|---|---|
| token | Yes | Order token | |
| lineIds | Yes | IDs of lines to update | |
| substitution | Yes | Desired substitution state (true = allow, false = disallow) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description fully carries the burden. It reveals the toggle endpoint behavior, non-idempotence, and the need to check state before retrying, which are critical for safe invocation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences and a warning. Every sentence adds value, and the purpose is front-loaded. No redundant 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 tool with no output schema, the description covers critical behavioral aspects (toggle, non-idempotence) and usage warnings. It lacks return value details, but the core information is sufficient for correct use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds context about toggle semantics but does not provide additional parameter-specific info beyond the schema. It is adequate but not enhanced.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool sets substitution for order lines, using a specific verb and resource. It distinguishes itself from sibling tools like get_order and delete_order_lines by focusing on substitution state.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use (setting substitution) and warns against retrying on timeout, advising to check current state first. This is comprehensive for safe usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Hide or unhide a product from purchase history
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Purchase stat ID | |
| isIgnored | Yes | Whether to ignore this product |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It states 'hide or unhide' but does not disclose side effects (e.g., reversibility, permission requirements, or impact on other tools like list_purchase_stats).
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 sentence conveys the core action without any superfluous words. It is front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with two scalar parameters and no output schema, the description covers the basic functionality. However, missing behavioral information (e.g., idempotency, confirmation) makes it barely adequate.
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 schema already defines parameters clearly. The description adds no extra meaning beyond the schema's 'Purchase stat ID' and 'Whether to ignore this product'.
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 ('hide or unhide') and clearly identifies the resource ('product from purchase history'). It distinguishes this tool from siblings like list_purchase_stats, which only lists items.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives, nor any prerequisites or exclusions. For example, it doesn't mention that the product must exist in purchase history or that hide/unhide affects future views.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Sort items in the product list by store departments
| Name | Required | Description | Default |
|---|---|---|---|
| token | Yes | Product list UUID token |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Only states basic action; does not disclose if sorting is permanent, modifies the list, or returns output. Lacks behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no fluff. Extremely concise, but under-specification could be seen as too minimal.
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 tool with one parameter and no output schema, the description is adequate but lacks details on side effects or return behavior. Marginally complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with the token parameter described as 'Product list UUID token'. Description adds no additional meaning beyond schema, meeting baseline but not enhancing.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool sorts items in a product list by store departments, using a specific verb and resource. It distinguishes from sibling tools like get_product_list or update_product_list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. No context on prerequisites or when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update the name or description of a product list
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | New name | |
| token | Yes | Product list UUID token | |
| description | No | New description |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It only states the tool updates name or description but does not mention any side effects, authentication requirements, or what happens to other fields. For a mutation tool, more transparency is needed.
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?
Single sentence, direct, and front-loaded. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple update tool with no output schema and 3 parameters, the description minimally covers what it does. However, it lacks information about return value or success/failure indicators, which would be helpful for an agent.
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 baseline is 3. The description adds no extra meaning beyond the schema: it repeats 'name or description' but does not clarify constraints (e.g., maxLength for name is documented in schema). No additional value.
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 explicitly states 'Update the name or description of a product list', clearly specifying the verb (update), resource (product list), and the specific attributes that can be modified. It distinguishes from sibling tools like create_product_list or delete_product_list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like create_product_list or sort_product_list. It does not mention prerequisites, exclusions, or context for use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add a product by SKU or update its quantity in a product list. Set quantity to 0 to remove.
| Name | Required | Description | Default |
|---|---|---|---|
| sku | Yes | Product SKU | |
| token | Yes | Product list UUID token | |
| quantity | Yes | Quantity (0 to remove) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses key behaviors: adding or updating a product by SKU, and using quantity=0 to remove. However, it does not mention idempotency, error cases, or any side effects like order preservation.
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 concise sentences with zero wasted words. The critical information (add, update, remove) is front-loaded and efficiently communicated.
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 no output schema and no annotations, the description is sufficiently complete for a simple mutation tool. It covers all three operations. Could optionally mention the expected response (e.g., success indication) but not required.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds value by summarizing the combined actions (add, update, remove) beyond the individual parameter descriptions. It clarifies the usage pattern for all three parameters together.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (add/update/remove) and resource (product list item by SKU). It distinguishes from sibling tools like 'update_product_list' which modifies list metadata, and 'clear_product_list' which removes all items.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for modifying items within a product list but does not explicitly state when to use this tool versus alternatives like 'clear_product_list' or 'delete_product_list'. No when-not or alternative guidance is provided.
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.
v1.0.1add_checkout_linesadd_shopping_note_lineapply_store_product_orderchange_shopping_note_linecheck_store_order_eligibilityclear_product_listclear_shopping_notecreate_product_listdelete_archived_linedelete_order_linesdelete_product_listdelete_shopping_note_lineget_category_productsget_checkoutget_meget_orderget_productget_product_listget_shopping_notelist_archived_lineslist_categorieslist_orderslist_product_listslist_purchase_statslower_order_quantityreorder_shopping_note_linessearch_productsset_line_completionset_order_substitutionset_purchase_stat_ignoredsort_product_listupdate_product_listupdate_product_list_itemScored across 33 tools
Each tool targets a specific resource and action (e.g., product lists vs. shopping notes vs. orders vs. checkout), with clear boundaries. Even though there are many tools, their purposes do not overlap.
All tools follow a consistent `verb_noun` pattern in snake_case (e.g., `create_product_list`, `add_checkout_lines`), making it easy to predict tool behavior from its name.
With 33 tools, the server is over-scoped. While each tool serves a distinct purpose, the count exceeds the recommended 3–15 range and makes the surface cumbersome for an agent to navigate.
The tool set covers the full lifecycle of a grocery shopping workflow: browsing products, managing lists and notes, placing orders, handling checkout, and tracking purchase stats. No obvious gaps for the intended domain.
MCP server for Product Management
MCP server for Codat — companies, connections, invoices, bills and financial statements.
MCP server for Lemon Squeezy — stores, products, orders, subscriptions, license keys.