Click on "Install 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., "@mintsoft-mcp look up stock levels for product SKU-1000"
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.
A Model Context Protocol server for the Mintsoft warehouse management system, so Claude and any other MCP-capable LLM client can look up orders, products, stock, inbound, returns and reports — and, if you deliberately enable it, make guarded changes.
Unofficial. Not affiliated with or endorsed by Mintsoft / Access Group.
Mintsoft has no sandbox — every API key points at a live WMS. This server is built around that fact:
Read-only by default. 37 read tools (GETs only). The 8 write tools are not
registered at all unless MINTSOFT_ENABLE_WRITES=1 — when off, there is zero write
surface for a model to misuse.
Client allowlist. Even with writes on, every write is refused unless the target
record belongs to a ClientId in MINTSOFT_WRITE_CLIENT_ALLOWLIST (default: empty =
refuse everything). Point it at a dedicated test client account, not your real brands.
Destructive ops double-gated. delete_product also requires confirm=True;
amend_bundle refuses if the bundle has alt codes or recent stock activity unless
force=True, and rolls back if the recreate fails.
Everything audit-logged. Every API call (reads included) is appended to a local
JSONL audit log (~/.mintsoft-mcp/mintsoft_api_audit.jsonl) — timestamp, method,
path, body, status, affected id. The API key is never logged. Readable in-session via
the get_api_audit_log tool for tracing or recovering from changes.
Related MCP server: Odoo MCP Server
From source (PyPI release coming):
uv tool install git+https://github.com/AhamadFalah/mintsoft-mcp
# or: pip install git+https://github.com/AhamadFalah/mintsoft-mcpYou need a Mintsoft API key (Mintsoft → Settings → API).
Claude Code
claude mcp add mintsoft -e MINTSOFT_API_KEY=your-key -- mintsoft-mcpClaude Desktop / Cursor / Windsurf / VS Code — add to the client's MCP config
(claude_desktop_config.json, .cursor/mcp.json, etc.):
{
"mcpServers": {
"mintsoft": {
"command": "mintsoft-mcp",
"env": { "MINTSOFT_API_KEY": "your-key" }
}
}
}To enable writes (against a test client only — see safety model above):
"env": {
"MINTSOFT_API_KEY": "your-key",
"MINTSOFT_ENABLE_WRITES": "1",
"MINTSOFT_WRITE_CLIENT_ALLOWLIST": "3"
}Area | Tools |
Orders |
|
Products & stock |
|
Inbound & returns |
|
Warehouse |
|
Account & reference |
|
Meta |
|
add_order_comment, add_order_tag, create_product, update_product,
add_alt_code, delete_product (needs confirm=True), amend_bundle,
discontinue_sku (footprint pre-check → rename [Discontinued] … + DisCont flag,
same ProductId so history survives).
Things this server handles that the official docs don't tell you:
Cloudflare blocks default user-agents (error 1010) — a browser UA is sent.
Validation failures come back HTTP 200 with Success: false — surfaced as
errors, not silently swallowed.
Product.CommodityCode must be a nested object {"Code": "..."}; a plain
string is silently dropped. The client coerces strings automatically.
AltCodes POST takes query params, not a JSON body, and ConnectMappingType
is a channel name string ("Amazon", "Shopify", "API"…) despite Swagger
saying integer.
Bundles are hidden from Product/Search — find them via Product/List or by id.
There is no in-place bundle edit — amend_bundle does delete + recreate (new
ProductId) with guards and rollback.
Env var | Default | Purpose |
| — | Required. Your Mintsoft API key. |
|
| Register the write tools. |
| (empty) | Comma-separated ClientIds writes may touch. Empty = all writes refused. |
|
| Audit-log every API call. |
|
| Log only PUT/POST/DELETE. |
|
| Audit log path. |
| (unset) | Optional: fetch the key from GCP Secret Manager via |
scripts/smoke_test.py verifies the full 187-endpoint surface: read-only tiers run
live; the guarded --write pass runs a create→read→delete cycle only against a
client whose name contains "test" (or MINTSOFT_TEST_CLIENT_ID) and skips writes
entirely if none exists.
python scripts/smoke_test.py # read-only
python scripts/smoke_test.py --write # + guarded write demomcp-name: io.github.ahamadfalah/mintsoft-mcp
List the alternative SKUs / barcodes (AltCodes) mapped to a product.
| Name | Required | Description | Default |
|---|---|---|---|
| product_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description implies a read operation (list) but does not explicitly state it is non-destructive or idempotent. With no annotations, more clarity would be beneficial, but the description is adequate for a simple read 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, no wasted words, and front-loaded with the core action.
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 list tool with an output schema, the description covers the essential purpose. However, it lacks usage guidelines and behavioral details that could 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 description coverage is 0%, and the description does not mention the 'product_id' parameter at all, providing no additional meaning 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?
Description clearly states the verb 'List' and the resource 'alternative SKUs / barcodes (AltCodes) mapped to a product', distinguishing it from sibling tools like get_product or search_products.
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 (e.g., get_product), nor any exclusions or prerequisites mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read the most recent entries from the Mintsoft API audit log — the append-only history of EVERY call this tooling/server makes (ts, method, write flag, path, body, status, success, affected_id). Use to trace or recover from changes. writes_only=True → only PUT/POST/DELETE; contains → only lines whose path/body matches the substring (e.g. a SKU or 'Bundle').
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| contains | No | ||
| writes_only | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description fully discloses behavior: the log is append-only, and it explains parameter effects (writes_only filters by HTTP method, contains matches substring). It does not mention auth or rate limits, but covers core behavior well.
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 efficiently convey purpose, scope, and parameter behavior without redundancy. Every sentence adds value.
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 3 optional parameters and an existing output schema, the description covers purpose, parameter usage, and log nature completely. No gaps for an agent to misuse the 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 has 0% description coverage; the description compensates by explaining each parameter: limit has a default, writes_only filters to write operations, contains performs substring matching with a concrete example ('a SKU or 'Bundle'').
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 'Read the most recent entries from the Mintsoft API audit log' with specific verb and resource. It lists the fields included, making it distinct from sibling tools that retrieve other data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage context: 'Use to trace or recover from changes.' It explains the two filtering parameters (writes_only, contains) with examples, but does not mention when not to use or alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get one ASN (inbound) by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| asn_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It only states the action; no mention of error handling, authentication, rate limits, or response format.
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 with the key information. 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 one-parameter getter with no output schema or annotations, the description is minimally adequate but lacks details on return value or error conditions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, and the description does not explain the parameter 'asn_id'. The name is self-explanatory, but the description adds no 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?
Clearly states the action 'Get', the resource 'ASN (inbound)', and the method 'by ID'. It distinguishes from sibling 'list_asns' which retrieves multiple.
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, prerequisites, or alternatives among many sibling tools. The description only states the basic function.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read a bundle's make-up: SKU, Name, and Components (each with ProductId, SKU, Quantity). NB: bundles are hidden from Product/Search — find them via list_products(client_id=…) or by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| product_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full disclosure burden. It correctly indicates a read operation and outlines the return fields, but lacks details on error handling (e.g., if product_id is not a bundle) or other behavioral traits like idempotency. It is adequate but not exhaustive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences deliver all essential information: the tool's output and a critical usage hint. No unnecessary words, front-loaded with 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?
For a simple read-by-ID tool with no output schema, the description fully explains the returned fields and provides crucial context about bundle discoverability. No gaps are evident given the tool's low 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 0%, and the description does not elaborate on the single parameter product_id beyond its implicit meaning from context. While the parameter name is self-explanatory, the description adds no additional meaning, failing to compensate for the missing schema 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 reads a bundle's make-up, listing specific fields (SKU, Name, Components) and distinguishes bundles from regular products via a note about their hidden nature. It uses a specific verb and resource, differentiating it from siblings like get_product and list_products.
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 explicitly advises that bundles are hidden from product search and provides the alternative method (list_products or by ID) to find them. This gives clear context for when to use this tool, though it does not explicitly list exclusion scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get one invoice by ID (needs Accounting permission).
| Name | Required | Description | Default |
|---|---|---|---|
| invoice_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must fully disclose behavior. It mentions a behavioral trait (requires Accounting permission) but does not describe return format, error handling, or side effects. For a simple read operation, this is basic but could be richer.
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 with no extraneous words. It efficiently communicates the tool's core purpose and a key requirement.
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 (one parameter, no output schema, no annotations), the description is fairly complete in stating purpose and a permission need. However, it lacks explanation of the return value and error conditions, which would be expected without an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has one parameter with no description. The description adds no meaning beyond 'by ID', failing to explain what the invoice ID represents or its format. Schema coverage is 0%, so the description should compensate but does not.
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 verb 'Get', the resource 'one invoice', and the identification method 'by ID'. It distinguishes from sibling tools like list_invoices that retrieve multiple invoices.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It states a permission requirement ('needs Accounting permission'), which informs when the tool can be used. However, it does not explicitly contrast with alternatives or provide exclusion criteria. The context implies this is for a single invoice vs. list_invoices for multiple.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get full detail for one Mintsoft order by its numeric order ID.
| Name | Required | Description | Default |
|---|---|---|---|
| order_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description indicates a read-only retrieval but lacks disclosure of error behavior (e.g., if order not found) or any side effects. Without annotations, the description carries the full burden and is minimally adequate.
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 with action and resource, no unnecessary words. 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 get-by-ID tool with one parameter and no output schema, the description is nearly complete. Could mention return format or error handling but is adequate for its simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds context that order_id is numeric and refers to a Mintsoft order, which is not apparent from the schema alone. With 0% schema coverage, this is valuable despite being brief.
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 retrieves full details of a Mintsoft order by numeric ID, using a specific verb and resource. It distinguishes well from siblings like get_order_comments, list_orders, and search_orders.
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 such as list_orders or search_orders. The usage is implied but not clarified with exclusions or context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the comments logged against an order.
| Name | Required | Description | Default |
|---|---|---|---|
| order_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
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 indicates a read operation via 'Get' but does not disclose any other behavioral traits such as pagination, sorting, or potential limitations.
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 gets to the point. However, it is so brief that it misses opportunities to include useful details 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?
Given no annotations and 0% schema coverage, the description is too sparse. It lacks context about usage, parameter, and behavior, especially compared to the numerous sibling tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description does not explain the order_id parameter beyond mentioning 'against an order'. It adds minimal value over the schema for the single required parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and the resource 'comments logged against an order'. It distinguishes from sibling tools like get_order or get_order_items which deal with different aspects of an 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?
The description implies when to use (when you need comments on an order) but does not provide explicit context, exclusions, or alternatives among the many sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Resolve an exact order number to its internal Mintsoft order ID.
| Name | Required | Description | Default |
|---|---|---|---|
| order_number | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose behavioral traits such as whether the call is read-only, required authentication, error handling (e.g., if order not found), or the format of the returned ID. The description is minimal on 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 concise sentence that efficiently states the core purpose. It is front-loaded and contains no fluff, though it could benefit from additional 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 simple tool with one parameter and no output schema, the description explains the main purpose but omits details about return format and error conditions. It is minimally complete but not fully informative.
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 sole parameter 'order_number' has no description in the schema (0% coverage). The tool description does not add any semantics beyond the parameter name, failing to clarify format, constraints, or examples.
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: resolving an external order number to its internal Mintsoft order ID. The verb 'Resolve' and the specific resource 'order number to internal Mintsoft order ID' make the purpose distinct from sibling tools like get_order or search_orders.
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_order, search_orders, or other order-related tools. The description only states what it does without any contextual usage advice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the line items for an order.
| Name | Required | Description | Default |
|---|---|---|---|
| order_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose any behavioral traits such as authorization requirements, rate limits, or side effects. The output schema exists but is not referenced.
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 waste. It is appropriately concise for a simple retrieval tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given low complexity (1 param), the description is minimal but sufficient for basic understanding. However, it does not leverage the existing output schema or provide additional context about the return value.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description adds no information about the order_id parameter beyond the schema. No constraints, format, or context is given.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states what the tool does: retrieve line items for an order. It distinguishes itself from sibling tools like get_order and list_orders.
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 when-to-use or alternatives are provided. However, the simple single-parameter nature makes usage context clear, but lacks guidance for when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get full detail for one product by its numeric product ID.
| Name | Required | Description | Default |
|---|---|---|---|
| product_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must convey behavioral traits. It implies a read operation ('Get full detail') but does not specify whether the product must exist, error handling, authentication requirements, or the structure of the returned data. Basic transparency is achieved, but more detail would be beneficial.
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 that immediately conveys the purpose. It is front-loaded with the action and resource, with no unnecessary words. 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?
The tool has no output schema, yet the description does not explain what 'full detail' includes (e.g., all product fields). For a tool with many sibling tools and a single required parameter, the description should provide more context about the response to ensure the agent knows what to expect.
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 only parameter, product_id, is described as 'numeric product ID' in the description, aligning with its integer type in the schema. However, the schema has 0% description coverage, so the description adds minimal meaning beyond the type and name. For a simple ID parameter, this is acceptable but not exceptional.
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 resource ('full detail for one product'), clearly distinguishing it from sibling tools like list_products (which lists multiple products) and get_product_inventory (which gets inventory details only). It uniquely identifies the tool's 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 clearly states the context: use when you need full details for a single product by its numeric ID. No explicit when-not-to-use or alternative guidance is given, but the sibling tool names (e.g., list_products, search_products) implicitly provide differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get inventory (stock by location) for a product.
| Name | Required | Description | Default |
|---|---|---|---|
| product_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must disclose all behavioral traits. It only says 'Get inventory' without details on pagination, error handling, or data scope (e.g., returns inventory for all locations or limited).
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 no extraneous words. Highly 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?
Given the simplicity (1 parameter, output schema exists) and no behavior to disclose, the description is minimally adequate. However, it lacks usage guidelines and parameter elaboration, making it acceptable but not thorough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, requiring the description to compensate. The description mentions 'for a product' but does not explain the product_id parameter beyond its name, which is already in 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 gets inventory (stock by location) for a product, using a specific verb and resource. It is distinct from siblings like get_stock_levels_by_warehouse which likely returns aggregate levels, 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 tool versus alternatives. Sibling tools like get_stock_levels_by_warehouse or get_stock_levels_updated_since exist, but the description gives no context for choosing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reference data. kind = 'countries' | 'currencies' | 'picking_types' | 'price_types'.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden for behavioral disclosure. It only lists allowed values, providing no information about side effects, idempotency, authorization needs, or return characteristics. A read-only hint would help.
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?
Extremely concise single sentence that front-loads the critical information (allowed values). No unnecessary words or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has only one simple parameter and an output schema (assumed to document structure), the description covers the key input constraint (allowed kinds). It could mention that the output is static reference data, but overall it's sufficient for a low-complexity 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 schema has 0% coverage, so the description compensates by explicitly listing the four allowed string values for 'kind', which is essential for correct invocation. It does not describe what each kind returns, but the list minimizes ambiguity.
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 reference data and lists the allowed 'kind' values, distinguishing it from sibling tools that deal with orders, products, etc. However, it could be more explicit about the general purpose (e.g., 'get static lookup values').
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 vs alternatives. The description does not mention context, prerequisites, or exclusion criteria, leaving the agent to infer usage from the name and sibling list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get one return by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| return_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden for behavioral disclosure. It only states 'Get one return by ID' without mentioning permissions, side effects, return format, or error handling. This is insufficient for a tool with no annotation support.
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 with one sentence. It front-loads the essential information, though it could be slightly expanded 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?
Given the tool is simple (single required parameter, no output schema), the description is minimally adequate. However, it lacks any hint about the return data structure or potential errors that could 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 0%, and the description adds no meaning beyond the schema. The parameter 'return_id' is self-explanatory from its name, but the description does not clarify its format, range, or relationship to other entities.
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 'Get one return by ID.' clearly states the action (get), resource (return), and method (by ID). It distinguishes itself from sibling tools like list_returns which retrieves multiple returns.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as list_returns or search functions. It does not mention context, exclusion criteria, or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Stock-flow (movement) history for a product over the last N days (default 30).
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | ||
| product_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must convey behavioral traits. It only states the tool retrieves history for a product over a time range. It does not disclose whether it's read-only, if it returns raw movements or summaries, or any pagination or filtering details. The brevity leaves significant uncertainty.
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 not verbose. It front-loads the core purpose. However, it could be slightly more structured without adding length, e.g., clarifying the parameter roles.
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 is simple (2 parameters, output schema exists), the description covers the basic purpose but lacks depth. An agent would need to rely heavily on the output schema to understand return values. Without annotations, more behavioral 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 description coverage is 0%, so the description should add meaning to parameters. It implicitly references 'product' (mapped to product_id) and 'last N days' (mapped to days parameter with default 30). However, it does not explain that product_id is required or that days has a default, nor does it add any extra context like value constraints or format expectations.
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 returns 'stock-flow (movement) history for a product over the last N days', which is specific enough to distinguish it from sibling tools like 'get_stock_levels_by_warehouse' that focus on levels, not movements. However, it could be more precise about what 'movement' entails.
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 such as 'get_stock_levels_by_warehouse' or 'get_stock_levels_updated_since'. There is no context about prerequisites or scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Stock levels for a warehouse, for products updated in the last N days (default 31).
| Name | Required | Description | Default |
|---|---|---|---|
| warehouse_id | Yes | ||
| updated_since_days | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It states it returns stock levels but does not disclose read-only nature, authentication needs, or pagination. With 0% schema coverage, more behavioral context is expected.
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 of 13 words, front-loaded with key information. No fluff, but could be slightly more structured (e.g., separating warehouse filter from recency filter).
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 an output schema exists, description doesn't need return details. However, it omits comparison to similar siblings and doesn't mention scope (e.g., all products or active only). Adequate but not thorough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description must add meaning. It explains updated_since_days (recency filter with default) but does not add beyond the parameter names. warehouse_id gets no extra context. Partial compensation.
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 it retrieves stock levels filtered by warehouse and recency of update. It distinguishes from siblings like get_stock_levels_updated_since (which likely lacks warehouse filter) and other get/list tools, making the purpose specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when needing stock levels for a specific warehouse with optional recency filter, but lacks explicit guidance on when to use this tool versus alternatives (e.g., get_stock_levels_updated_since). No when-not or alternative tools mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Stock levels for products changed in the last N days (default 7). Prefer this over the full StockLevels (which can time out).
| Name | Required | Description | Default |
|---|---|---|---|
| days | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the transparency burden. It hints at performance (won't time out) but lacks details on side effects, rate limits, or data freshness. Output schema exists, so return format disclosure is not required, but additional behavioral traits would improve transparency.
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 with no redundant words. Front-loaded with the core action, then immediately adds practical advice. Every sentence adds value.
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 (one optional parameter, output schema present), the description is nearly complete. It covers purpose, parameter, and a key usage context. Minor omission: no mention of pagination or limits, but not critical for this scope.
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 only parameter 'days' is explained with its purpose ('last N days') and default value (7). Schema description coverage is 0%, so the description fully compensates by adding meaning beyond the JSON schema type.
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 returns 'Stock levels for products changed in the last N days' with a default of 7 days. It distinguishes from a potentially problematic sibling ('full StockLevels') by naming it and noting timeout issues.
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?
Directly advises to prefer this tool over 'full StockLevels' due to timeout risk, providing explicit alternative guidance. Does not cover other siblings (e.g., get_stock_levels_by_warehouse), but the context is sufficiently scoped.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List ASNs (inbound goods-in / advance shipping notices).
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | ||
| limit | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility. It only states the basic action without disclosing reading behavior, pagination details, or any side effects. Minimal behavioral insight.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise at one sentence, front-loading the acronym explanation. However, it may be too brief, sacrificing potential helpful details for brevity.
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 presence of an output schema, return values do not need description. Yet the description lacks context on pagination, filtering, or ordering, which would be useful for a list tool. Adequate but not thorough.
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 schema defines two parameters (page, limit) with defaults but no descriptions. The description adds no explanation of these parameters, leaving the agent without guidance on how to use them. Schema description coverage is 0%.
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 'ASNs', and elaborates on the acronym with 'inbound goods-in / advance shipping notices'. This distinguishes it from other list tools like list_orders or list_products.
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 one needs to list ASNs but provides no explicit guidance on when to use this tool versus alternatives. There is no mention of prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List clients (brands) in the account.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description is the sole source of behavioral info, but it only states the basic action, omitting details like authentication, pagination, or response format.
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 short sentence, which is concise but lacks additional context that could be included without verbosity.
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 an output schema, the description still falls short by not mentioning any filtering or ordering, though the output schema may cover return structure.
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?
There are zero parameters, so the description does not need to add parameter info, matching the baseline score of 4.
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 'clients (brands) in the account', which distinguishes it from sibling tools that list other entities.
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, nor any prerequisites or context for when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List courier services.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and the description offers no behavioral details (e.g., read-only, rate limits, pagination) beyond the basic listing 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?
A single, concise sentence with no superfluous words or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the tool is simple with no parameters and an output schema, the description does not indicate the nature or structure of the returned data, leaving some context missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so the schema fully defines the input; the description adds no further parameter meaning, but baseline for 0 params is 4.
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 courier services' clearly states the action (list) and the resource (courier services), directly distinguishing it from sibling list_* tools that target different entities.
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 vs alternatives; however, the resource is unique among siblings so usage context is implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List accounting invoices (needs Accounting permission on the API key).
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | ||
| limit | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
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 only discloses the permission requirement. It does not mention pagination behavior, sorting, limits, or what happens if no invoices exist. For a listing tool, more transparency is expected.
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 efficiently conveys purpose and a key prerequisite. It is front-loaded and contains no unnecessary words. However, it could include additional context 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?
The tool is simple with an output schema, but the description lacks essential context such as pagination behavior, sorting, filtering, and common usage patterns. Given the absence of annotations and low schema coverage, the description is 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 two parameters (page, limit) with defaults but no descriptions. The schema description coverage is 0%, and the tool description does not explain these parameters at all. The description adds no value beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'list', the resource 'accounting invoices', and a specific permission requirement. It distinguishes itself from sibling tools like get_invoice (single invoice) and list_orders (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?
The description mentions the required permission (Accounting), which is helpful for usage. However, it does not provide explicit guidance on when to use this tool versus alternatives like get_invoice, nor does it mention any conditions or prerequisites beyond permissions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all storage locations in a warehouse.
| Name | Required | Description | Default |
|---|---|---|---|
| warehouse_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must fully convey behavioral traits, but it only states a simple read operation without details on permissions, side effects, or response handling.
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, well-formed sentence with no redundancy, containing the essential action and 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?
Despite having an output schema, the description omits common list-tool information like pagination, filtering, or ordering, and lacks any context about typical usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description should compensate. It hints that warehouse_id identifies a warehouse, but offers no details on format, source, or constraints.
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 (list all storage locations) and context (in a warehouse), distinguishing it from other list_* tools among siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, or any prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the sales channels (Shopify, Amazon, etc.) configured in Mintsoft.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description is straightforward and implies a read-only operation, but no additional behavioral details beyond the action are provided.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single, well-structured sentence that is concise and front-loaded with the main action.
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 parameters and existence of an output schema, the description sufficiently covers the tool's purpose and behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, and schema coverage is 100%, so the description adds no parameter info beyond what's already in 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 it lists sales channels and provides examples (Shopify, Amazon), making the purpose specific and distinguishable from sibling list tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use or when not to use this tool vs alternatives, but the unique purpose implicitly differentiates it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List order rules (needs OrderRules permission on the API key).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It implies a read-only operation but does not disclose pagination, ordering, or error handling behavior. The permission requirement is a positive disclosure, but overall transparency 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?
Extremely concise single sentence that front-loads the core purpose. Every word contributes meaning, with no extraneous content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter tool with an output schema, the description covers basic purpose and a key prerequisite. However, it fails to explain what 'order rules' are or how they relate to other entities, leaving potential confusion about 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?
No parameters exist, and schema coverage is 100%. The description adds no value beyond what the schema already conveys. 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 verb 'List' and the resource 'order rules', providing specific purpose. However, it does not differentiate from sibling list_* tools (e.g., list_orders, list_order_channels), which is a minor gap.
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 mentions a required permission (OrderRules on API key), which is a useful prerequisite. Yet it offers no guidance on when to use this tool versus alternatives like list_orders or list_order_statuses, limiting decision support.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List orders by status ID (e.g. NEW=1, DESPATCHED=4, QUERYRAISED=13, AWAITINGPICKING=15, PICKED=17). limit max 100.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | ||
| limit | No | ||
| status_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description mentions a limit of 100 but does not disclose other behavioral traits such as whether it is read-only, if there are rate limits, or any side effects. Since no annotations are provided, the description carries the full burden, which is insufficient.
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 efficiently conveys the core purpose and key constraint. It is front-loaded and contains no redundant words, though it could be slightly expanded for completeness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, return values are not needed. However, the description lacks context on pagination behavior and does not mention when to use this tool over similar siblings. It is minimally complete but not thorough.
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 description adds value for the 'status_id' parameter (with examples) and the 'limit' parameter (max 100), but the 'page' parameter is not explained. Given 0% schema coverage, the description partially compensates but leaves a gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List orders') and the filtering criterion ('by status ID'), with concrete examples of status IDs. It distinguishes itself from sibling tools like 'get_order' (single order) and 'search_orders' (more flexible search).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives like 'search_orders' or 'get_order'. The description does not specify required permissions or prerequisites, nor does it mention when it should not be used.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all order status names and their IDs.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It implies a read-only operation but does not explicitly state it or disclose any side effects, permissions, or response format. Adequate for a simple list tool but lacking depth.
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 directly states the purpose without any extraneous information. 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?
Given zero parameters and an output schema exists, the description covers the essential purpose. It could clarify whether the list is paginated or exhaustive, but overall, it is sufficiently complete for a simple enumeration 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?
No parameters exist, so schema coverage is 100%. The description adds no param-specific meaning, which is acceptable since there are none. 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 tool lists all order status names and their IDs, using a specific verb ('list') and resource ('order statuses'). It distinguishes itself from sibling tools like 'list_orders' which list orders, not statuses.
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 (e.g., before creating orders or for reference purposes). There is no mention of context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List products (paged). limit max 100. client_id filters to one client (0 = all). Unlike search_products, this listing INCLUDES bundles — use it to find a bundle's product ID.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | ||
| limit | No | ||
| client_id | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries the burden. It discloses pagination, limit max 100, and client_id filter semantics, and includes bundles. Lacks mention of sorting or response details, but sufficient for basic use.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose and parameters, second sentence adds sibling distinction. 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?
Given the tool is a simple list with 3 parameters and output schema exists, the description is complete enough. Could mention sorting or total pages, 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 has 0% description coverage, but description adds meaning: limit max is 100 (schema only has default 50), and client_id=0 means all. This enriches the parameters beyond 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 explicitly states 'List products (paged)' and distinguishes from sibling 'search_products' by noting that this listing includes bundles. It provides clear verb and resource with scope.
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 directly tells when to use this tool: 'use it to find a bundle's product ID' and contrasts with 'search_products' which excludes bundles. This gives explicit guidance on alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List returns.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | ||
| limit | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, and the description fails to disclose any behavioral traits (e.g., read-only, pagination, filtering). The description does not add value beyond the schema's parameter names.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short (two words) but under-specifies the tool's behavior. It is not concise in a useful sense; it sacrifices clarity for brevity.
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 two parameters, no annotations, and an output schema that is not referenced, the description is incomplete. It fails to provide enough context for an agent to understand the tool's usage or output.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not add any meaning to the 'page' and 'limit' parameters beyond their names. No mention of pagination or defaults.
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 returns' is a tautology that merely restates the tool name. It does not differentiate from sibling tools like 'get_return' or provide any additional context about what kind of returns are listed.
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_return' or 'list_orders'. There are no exclusions, prerequisites, or contextual hints.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List product suppliers.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility for behavioral disclosure. It only states 'List' which implies a read operation, but it does not confirm read-only behavior, pagination, rate limits, or any side effects. The lack of transparency is significant for a list operation that likely returns multiple records.
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 wasted words. For a tool with no parameters and a straightforward purpose, conciseness is appropriate. However, it could benefit from additional context without being overly long.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that the tool has no parameters and an output schema exists, the description is minimally adequate. However, it lacks any mention of default behavior (e.g., all suppliers, pagination, ordering). For a list operation, agents might need to know if results are limited or sortable. The output schema may cover return fields, but context on scope is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, so schema coverage is 100% by default. The description adds the essential meaning that the tool lists 'product suppliers,' which clarifies the purpose beyond the empty schema. With no parameters, the description must convey what the tool retrieves, which it does, albeit minimally.
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 product suppliers.' clearly states the verb (list) and resource (suppliers). It distinguishes from other list tools by specifying 'product suppliers,' which is a unique entity among sibling tools. However, it does not explicitly differentiate from other list operations like 'list_products' or 'list_warehouses,' but the resource is unique.
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. There are no context signals, prerequisites, or exclusions mentioned. Users and AI agents are given no information about scenarios where this tool is appropriate or not.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List warehouses.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must convey behavioral traits. It does not disclose pagination, ordering, permissions, or any side effects. This is a critical gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
While extremely concise, the description is under-specified. Two words are not enough to convey the tool's purpose effectively.
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 but an existing output schema, the description should explain what data is returned (e.g., warehouse IDs, names). It does not, 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?
There are no parameters, and the schema coverage is 100%, so the baseline is 3. The description adds no meaning beyond the schema, but it does not need to compensate.
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 warehouses' uses a verb and resource, indicating the action and target. However, it lacks specificity and does not differentiate from sibling list tools like list_locations or list_clients, making it just adequate.
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_stock_levels_by_warehouse or list_warehouse_zones. The agent must 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.
List the zones (location-charge zones) of a warehouse.
| Name | Required | Description | Default |
|---|---|---|---|
| warehouse_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description lacks any behavioral details such as whether the operation is read-only, requires permissions, or has side effects. For a tool with zero annotation coverage, the description should compensate but 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?
The description is a single, efficient sentence with no unnecessary words. It is front-loaded with the verb 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?
Given a single parameter and an existing output schema, the description covers the basic purpose adequately. However, it lacks any behavioral or usage context that would help an agent decide when to use this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema's warehouse_id parameter has no description in the schema (0% coverage), and the tool description adds no meaning beyond the schema's type and title. The phrase 'location-charge zones' gives context for the result but not the parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' and the resource 'zones (location-charge zones) of a warehouse,' making the tool's purpose unambiguous. It distinguishes from sibling tools like list_locations and list_warehouses by specifying 'warehouse zones.'
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 list_locations or list_warehouses. There is no mention of when not to use it or any prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Resolve a primary SKU to its internal product ID.
| Name | Required | Description | Default |
|---|---|---|---|
| sku | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose behavioral traits like error handling (e.g., what happens when SKU is not found), read-only nature, or any prerequisites. The description 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?
The description is a single sentence with no unnecessary words. It is concise and front-loaded with the core action.
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 only one parameter, the description is insufficient. It does not explain the return value format, error states, or any edge cases, which is needed for a lookup tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It adds 'primary' to describe the SKU, but does not explain format, constraints, or valid values beyond what the schema shows (type string).
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 resolves a primary SKU to an internal product ID, which is a specific verb+resource. However, it does not differentiate it from sibling tools like get_product or search_products.
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, such as when to prefer it over search_products or get_product. No context for usage boundaries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generic READ-ONLY passthrough: GET any Mintsoft API path (e.g. 'Order/123/Shipments'). Path is relative to /api/. Only GETs — for safety this tool cannot perform writes.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | ||
| params | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description compensates by explicitly stating read-only nature, path relativity, and safety guarantee. Lacks details on error handling 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?
Two concise sentences, no filler, front-loaded with key information. Highly 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 generic passthrough with two parameters and no output schema, the description covers purpose, path, and safety. Could mention that 'params' represent query parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage; description clarifies 'path' is relative to /api/, but does not explain 'params' object or its usage. Some value added but incomplete.
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?
Clearly states it is a generic READ-ONLY passthrough for GET requests, with an example path. Distinguishes itself from sibling tools that target specific endpoints.
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?
Implicitly suggests use when no specific endpoint tool exists, but lacks explicit 'when to use' or 'when not to use' guidance. Could be improved by stating it is a fallback.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
READ-ONLY discontinue footprint for a SKU before retiring it: stock on hand, live-order
allocations, inbound/backorder, bundle membership, plus alt-code & replen info. Returns a
blocker list and a clear flag. Identify by sku (+client_id) or product_id. Safe on any client.
| Name | Required | Description | Default |
|---|---|---|---|
| sku | No | ||
| client_id | No | ||
| product_id | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Clearly labeled as READ-ONLY and safe on any client. Describes what data is examined and that output includes a blocker list and clear flag. With no annotations, the description provides sufficient behavioral insight without contradictions.
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 dense sentences front-load critical information: action, data, output, and identification methods. No unnecessary words or repetition. Every sentence 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?
Covers essential aspects: purpose, identification, output structure, and safety. Lacks mention of which parameters are required (all optional but at least one needed) and explicit return format details beyond blocker list and clear flag. Good but could be slightly more precise.
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?
Despite 0% schema description coverage, the description adds meaning by explaining that identification can be done via 'sku (+client_id)' or 'product_id', clarifying parameter relationships and default values serve as sentinels.
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?
Clearly states the tool's purpose: precheck discontinue footprint for a SKU before retiring it, listing specific data points (stock, allocations, bundle membership) and return values (blocker list, clear flag). Distinguishes from sibling tools by emphasizing read-only, pre-retirement context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly indicates usage 'before retiring it' and identifies via sku+client_id or product_id. Does not mention when not to use or list alternatives, but the context is clear enough for agents to infer appropriate scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run a Mintsoft report. kind = 'courier_despatch' | 'products_in_location' | 'product_usage'. Dates are YYYY-MM-DD; default to the last 7 days when omitted. warehouse_id/client_id are optional filters (0 = all).
| Name | Required | Description | Default |
|---|---|---|---|
| kind | Yes | ||
| to_date | No | ||
| client_id | No | ||
| from_date | No | ||
| warehouse_id | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description should disclose behavioral traits. It does not mention whether the report is generated synchronously, what the output format is, or any side effects. The presence of an output schema only partially compensates.
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 at three sentences, front-loads the main purpose, and efficiently conveys parameter behavior without 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?
The description covers input parameters well but lacks behavioral context such as whether the tool is read-only, if it requires special permissions, or if it supports pagination. Given the output schema exists, return values are not needed, but overall completeness is moderate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It explains the kind parameter with specific allowed values, date format and defaults for to_date and from_date, and the optional warehouse_id/client_id with default 0 meaning 'all'. This adds substantial meaning 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 runs a Mintsoft report and specifies the three allowed 'kind' values, distinguishing it from sibling tools that fetch or list individual entities.
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 such as the many get_ or list_ tools. The description does not mention prerequisites or scenarios where this is preferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search orders by order number. exact=True does an exact match (recommended).
| Name | Required | Description | Default |
|---|---|---|---|
| exact | No | ||
| order_number | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
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 conveys that the tool searches by order number and supports exact matching, but it does not disclose behavior such as whether multiple results are returned, pagination, or error handling. The output schema exists but is not detailed in the description.
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 with two sentences. Every word adds value: it names the action, resource, and key parameter behavior. No wasted content, 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?
Given the tool's simplicity (2 parameters, no nested objects, output schema exists), the description is adequate but lacks details about search behavior (e.g., multiple results, pagination). It is minimally complete for an agent to understand the core functionality, but could be improved.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains the 'exact' parameter (exact match recommended) and implies the use of 'order_number' by stating the search is by order number. This adds meaningful context beyond the schema alone, though format details for order_number are omitted.
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 'Search orders by order number.' This is a specific verb and resource, and it distinguishes from sibling tools like list_orders (which lists all) and get_order (which retrieves a single order by ID). The search is specifically by order number, not other criteria.
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 recommends using exact=True for an exact match, but it does not explicitly state when to use this tool over alternatives or when not to use it. Context is implied but not fully articulated; no exclusions or alternative tool references are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search products by SKU or name.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations and only a one-line description, behavioral details are minimal. It doesn't disclose whether the search is case-sensitive, whether it returns multiple results, or if pagination is supported. The description implies a read-only operation but lacks specifics.
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 that immediately conveys the tool's purpose. No filler or 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?
The tool is simple with one parameter, and an output schema exists to document returns. The description covers the core functionality but could add context about result cardinality (e.g., returns all matching products) or when to expect no 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 schema has 0% description coverage, so the description adds value by explaining the 'query' parameter accepts SKU or name. However, it doesn't specify expected formats (e.g., whether SKU must be exact) or constraints, leaving some ambiguity.
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 searches products by SKU or name, which distinguishes it from sibling tools like 'get_product' (by ID), 'list_products' (all), and 'lookup_product_id' (by other criteria). However, it does not specify search behavior (e.g., partial/fuzzy matching) which would strengthen clarity.
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. For example, it doesn't indicate that this should be used when a SKU or partial name is known, versus 'list_products' for browsing all products.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find an order by its courier tracking number.
| Name | Required | Description | Default |
|---|---|---|---|
| tracking_number | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description must disclose behavior. It only says 'Find,' implying a read, but omits details like return format, idempotency, 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?
Single sentence with no wasted 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?
Adequate for a simple lookup tool with one parameter, though missing return type info. Output schema absent, but tool simplicity reduces need for extensive explanation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so description must compensate. It adds 'courier' context to 'tracking number,' but minimal depth. Baseline 3 due to one parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Find an order by its courier tracking number,' specifying the verb, resource, and unique identifier. It distinguishes from siblings like get_order (likely by order ID) and get_order_id.
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 get_order or get_order_id. No prerequisites or exclusions mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Most tools have clearly distinct purposes, with descriptions clarifying differences (e.g., get_order vs search_orders vs get_order_id). However, multiple stock-related tools (get_stock_levels_by_warehouse, get_stock_levels_updated_since, get_product_inventory, get_stock_flow) could cause confusion despite descriptions.
The majority follow a verb_noun snake_case pattern (get_*, list_*, search_*). Inconsistencies include 'mintsoft_get' (prefix+verb), 'precheck_discontinue' (unclear noun), and 'track_order_by_tracking_number' (extra word). Overall pattern is recognizable but not uniform.
37 tools is on the high side for typical MCP servers, but given the breadth of entities (orders, products, inventory, ASNs, invoices, reports, etc.), the count is borderline acceptable. Some redundancy (multiple stock methods) could be consolidated.
The tool set is heavily read-focused with get/list/search operations and no create/update/delete tools for core entities. Missing write capabilities for orders, products, and other entities limit the server to monitoring rather than full lifecycle management, creating significant gaps.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Model Context Protocol server for the Apideck Unified API. Connect any MCP-compatible agent framework to 100+ accounting systems, HRIS platforms, file storage providers, and more through one integration. More information https://www.apideck.com/mcp-server
A Model Context Protocol server for Wix AI tools
API-first CRM for LLMs - contacts, companies, deals and activities over a native MCP server.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/AhamadFalah/mintsoft-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
