Read Cin7 Core products, stock by location, sales, purchases, customers, suppliers and transfers.
Scored across 17 tools
Every tool maps to a distinct resource and action: get_* retrieves a single entity by id, list_* enumerates a collection, and the stock tools split cleanly into availability, adjustments and transfers. No two tools overlap in purpose, and descriptions reinforce the boundaries (e.g. get_product vs list_products).
All 17 tools use the identical cin7core_ prefix followed by a snake_case verb_noun pattern (get_customer, list_sales, get_stock_availability). The get/list verb split is applied uniformly across every resource.
17 tools is slightly on the heavy side but each one earns its place by covering a distinct entity (customers, suppliers, products, sales, purchases, stock operations, company, locations). It is a defensible, well-scoped set for an ERP surface rather than redundant padding.
The surface is entirely read-only: every resource has list/get but there are no create, update or delete operations for customers, products, sales, purchases or suppliers. For an ERP domain this is a notable functional gap, though the read coverage itself is thorough.
The Cin7 Core company these credentials belong to: company name, base currency, time zone, default weight/dimension units, lock date and tax calculation method. Good first call. GET /me.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the returned field set and the endpoint (GET /me), which is useful, but says nothing about auth prerequisites, rate limits, or caching — with annotations carrying most of the burden, a 3 fits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences: the resource and its returned fields are front-loaded, followed by the 'Good first call' routing hint and the endpoint. Nothing is padded and every clause carries information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description must describe returns, and it does so by enumerating company name, base currency, time zone, default units, lock date and tax method. That is enough for an agent to know what it gets back, though it makes no claim about whether the field list is exhaustive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so per the rubric the baseline is 4. The description correctly adds no parameter guidance because none is needed, and instead spends its text on return contents.
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 identifies a specific resource (the Cin7 Core company tied to the current credentials) and enumerates the data it returns, so an agent can tell it apart from the entity-oriented siblings (get_customer, get_product, list_sales). The verb is implied by the name rather than stated, but the scope is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Good first call' gives explicit positioning relative to the rest of the toolset — it tells the agent to establish account context up front. There are no exclusions or conflicting alternatives to name, so this is adequate context without being a full when/when-not guide.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One customer by id (including deprecated ones), optionally with its customer-specific product prices. GET /customer?ID=…
| Name | Required | Description | Default |
|---|---|---|---|
| customer_id | Yes | Customer id (GUID). | |
| include_product_prices | No | Include customer-specific product prices. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful context beyond them: that deprecated customers are still returned, that prices are opt-in, and the underlying GET route.
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 compact sentence with the key facts (scope, deprecated records, optional expansion) front-loaded. The trailing 'GET /customer?ID=…' route fragment is arguably dead weight for an agent choosing a tool, but it is short and harmless.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter lookup with no output schema, the description conveys what is fetched and which optional expansion exists, and annotations cover the read-only safety profile. Return field details are omitted, but a single-entity GET is low risk.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both parameters are already documented in the schema; baseline is 3. The description restates include_product_prices in prose ('optionally with its customer-specific product prices') but adds no format, syntax, or edge-case detail beyond it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('One customer by id') and clarifies scope ('including deprecated ones') plus the optional payload ('customer-specific product prices'). It is clearly distinguishable from list-style siblings, though it never names cin7core_list_customers explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied by the singular framing ('one customer by id'), which suggests lookup-by-known-id rather than listing. There is no explicit statement of when to prefer this over cin7core_list_customers or any prerequisite/permission guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One product by id (including deprecated ones) with its full detail; optionally its bill of materials, suppliers, stock movements, attachments, reorder levels and customer-specific prices. GET /product?ID=…
| Name | Required | Description | Default |
|---|---|---|---|
| product_id | Yes | Product id (GUID, from cin7core_list_products). | |
| include_bom | No | Include the bill of materials. | |
| include_movements | No | Include stock movements. | |
| include_suppliers | No | Include suppliers and supplier prices. | |
| include_attachments | No | Include attachments (file names and download links). | |
| include_custom_prices | No | Include customer-specific prices. | |
| include_reorder_levels | No | Include reorder levels per location. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds real value beyond them: it discloses that deprecated products are returned, shows the raw endpoint, and enumerates the six optional data expansions the payload can carry.
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 dense sentence with the endpoint appended, and the primary purpose plus the id-based scope is front-loaded. It is slightly packed with the list of includes, but nothing is redundant or padded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description correctly carries the burden of describing the return payload ('full detail' plus optional expansions) and flags the deprecated-inclusion behavior. It stops short of describing the base product fields or error behavior, but it is otherwise sufficient for a read-by-id 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 100%, so the baseline is 3. The description restates the include-flag families (BOM, suppliers, movements, attachments, reorder levels, custom prices) that the schema already documents individually, adding little new meaning about formats 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?
States a specific verb (get/fetch), resource (one product), and lookup key (id), and adds scoping detail that no sibling shares: deprecated products are included and the optional expansions are enumerated. An agent can separate this from cin7core_list_products on the basis of id vs. list without opening a schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the 'one product by id' phrasing and the 'ID=' query endpoint, which points the agent away from the bulk list tool. However, there is no explicit when-to-use/when-not statement and no guidance on when the optional include flags are worth requesting.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One purchase by id (simple, advanced or service purchase): supplier, contact, addresses, terms, location, required-by date, note, order lines, stock received, put away, invoices, credit notes, payments and attachments. GET /advanced-purchase?ID=… (the vendor endpoint that serves every purchase type).
| Name | Required | Description | Default |
|---|---|---|---|
| purchase_id | Yes | Purchase id (GUID, the ID from cin7core_list_purchases). | |
| combine_additional_charges | No | Show additional charges inside the line arrays. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds genuinely useful context beyond that: it names the underlying GET /advanced-purchase?ID= endpoint and clarifies that this single vendor endpoint serves every purchase type, which an agent could not infer from the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core action ('One purchase by id'), followed by a dense but relevant field list and a parenthetical on the backing endpoint. The long enumeration earns its place by previewing the return payload, though it is slightly heavy in one sentence.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description usefully compensates by listing the returned fields (supplier, addresses, order lines, payments, attachments, etc.). Combined with annotations covering the read-only profile, an agent has enough to call it correctly, though auth/permission expectations are unstated.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and both parameters are documented in the schema itself, so the schema carries the load. The description adds no syntax or format detail for purchase_id or combine_additional_charges, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (get) and resource (purchase) scoped to a single record by id, and explicitly enumerates the covered subtypes (simple, advanced, service purchase). This cleanly separates it from cin7core_list_purchases, which returns collections.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'by id' framing and the note that this endpoint 'serves every purchase type' imply when to reach for it versus list_purchases, but no explicit when-to-use or when-not guidance is given. Usage is inferable rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One sale by id with everything on it: customer, contact, addresses, terms, location, notes, quote, order lines, fulfilments (pick/pack/ship and tracking), invoices, credit notes, payments, attachments and inventory movements. GET /sale?ID=…
| Name | Required | Description | Default |
|---|---|---|---|
| sale_id | Yes | Sale id (GUID, the SaleID from cin7core_list_sales). | |
| include_transactions | No | Include the related accounting transactions. | |
| hide_inventory_movements | No | Leave out inventory movements (smaller reply). | |
| combine_additional_charges | No | Show additional charges inside the line arrays. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful context by exposing the GET endpoint (idempotent read) and warning that the reply is heavy ('everything on it'), which explains why the smaller-reply flags exist. Auth, rate limits and pagination remain undisclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence; the long item list is dense but each entry informs the agent about the return shape, which matters because there is no output schema. No filler text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description correctly carries the burden of describing return content, and it does so thoroughly; parameters are fully documented in the schema and the safety profile in annotations. The one missing piece is routing guidance against cin7core_list_sales.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, including the GUID pattern and the origin of sale_id, so the schema already does the heavy lifting. The description adds nothing about include_transactions, hide_inventory_movements or combine_additional_charges, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb+resource ('One sale by id') with an explicit enumeration of what the record contains, which is enough to separate it from the list_* siblings. It stops short of naming cin7core_list_sales as the alternative, so the differentiation is implicit rather than stated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description never states when to use this tool versus cin7core_list_sales or when a single-sale fetch is inappropriate. The only hint ('by id') is embedded in a phrase that mostly describes payload, not usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One stock adjustment by task id with its lines (product, location, batch, quantity, unit cost) and transactions. GET /stockadjustment?TaskID=…
| Name | Required | Description | Default |
|---|---|---|---|
| task_id | Yes | Stock adjustment task id (GUID, from cin7core_list_stock_adjustments). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: the response shape (lines and transactions) and the underlying endpoint, which matters because there is no output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One dense sentence that front-loads the resource and scope, then lists the returned fields, then gives the endpoint. No filler and nothing repeated from the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter read tool with annotations covering safety, the description supplies the missing return-value information that the absent output schema would otherwise provide. Only the error case (unknown task id) and pagination/volume expectations are unaddressed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%: the single task_id parameter is documented with its GUID pattern and a pointer back to cin7core_list_stock_adjustments. The description adds nothing beyond that baseline, which is the expected 3 when the schema carries the parameter burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ('One stock adjustment by task id') and enumerates what the payload contains (lines with product, location, batch, quantity, unit cost, plus transactions). The 'One ... by task id' phrasing implicitly distinguishes it from cin7core_list_stock_adjustments, though the sibling is never named explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied: fetch a single adjustment when you already have a task id. There is no explicit statement of when to prefer this over cin7core_list_stock_adjustments or what to do if the id is unknown, so the agent must infer the routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Stock levels per product, location, bin and batch: on hand, allocated, available, on order, in transit, stock on hand value and next delivery date. Filter by product id, name (starts with), exact SKU, location name, batch/serial number or category. GET /ref/productavailability.
| Name | Required | Description | Default |
|---|---|---|---|
| sku | No | Only the product with exactly this SKU. | |
| name | No | Only products whose name starts with this. | |
| page | No | Page number (default 1). | |
| batch | No | Only this batch or serial number. | |
| limit | No | Records per page, 1-100 (default 50). | |
| category | No | Only products in this category (name). | |
| location | No | Only stock in this location (exact location name, see cin7core_list_locations). | |
| product_id | No | Only this product (GUID). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description earns credit for disclosing the returned data fields and the underlying endpoint (GET /ref/productavailability), which matters because there is no output schema to convey the response shape.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the return payload before the filtering options, and closing with the endpoint reference. Density is high but every clause carries information; no filler or restated title.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 8 optional parameters, no output schema and no enums, the description does the necessary work of naming the returned metrics and the available filter axes. It omits ordering and pagination caveats, though page/limit are defined in the schema, so the remaining gap is minor.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so every one of the 8 filters is already documented in the schema, including the 'starts with' semantics for name and the GUID pattern for product_id. The description's filter list largely restates those definitions without adding format or syntax detail, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('stock levels per product, location, bin and batch') and enumerates exactly what fields come back (on hand, allocated, available, on order, in transit, value, next delivery date). This distinguishes it from get_product/list_products siblings, which return catalog data rather than per-location stock positions.
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 enumerates the filter dimensions, which implies how the tool is used, and cross-references cin7core_list_locations for obtaining a valid location name. However, it never states when to reach for this tool versus get_product or list_products, nor any exclusions or prerequisites, leaving routing to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One stock transfer by task id with its lines (product, quantity, from/to bin, batch) and status. GET /stockTransfer?TaskID=…
| Name | Required | Description | Default |
|---|---|---|---|
| task_id | Yes | Stock transfer task id (GUID, from cin7core_list_stock_transfers). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful behavioral detail beyond the annotations by disclosing the endpoint shape and, importantly, the contents of the returned payload. It omits error/pagination/auth behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences: the identity/scope first, then the payload contents and the raw endpoint. No filler, and the most decision-relevant information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description usefully compensates by enumerating the returned fields, and the read-only annotations cover the rest. Minor gaps remain around error behavior and what happens when the task id is unknown, but nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With one parameter at 100% schema coverage, the schema already documents the GUID pattern and even notes the id originates from cin7core_list_stock_transfers. The description adds no syntax or sourcing detail beyond the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('One stock transfer by task id') and enumerates the shape of the returned data (lines with product, quantity, from/to bin, batch, status). It is clear, but it never explicitly contrasts itself with the sibling cin7core_list_stock_transfers or the other get_* 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?
Usage is only implied: an agent infers this is the single-record lookup when it already holds a task id. There is no explicit when-to-use/when-not statement or pointer to the list endpoint as the way to obtain the id (that pointer lives in the schema, not the description).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One supplier by id (including deprecated ones). GET /supplier?ID=…
| Name | Required | Description | Default |
|---|---|---|---|
| supplier_id | Yes | Supplier id (GUID). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds one genuinely useful behavioral fact — deprecated suppliers are returned — but says nothing about error behavior for unknown ids or the return shape.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two terse fragments with zero waste, and the key scoping fact (single supplier, deprecated included) is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter read tool with full schema coverage and annotations, the description is nearly complete; only the absence of any return-shape hint (no output schema exists) keeps it from being fully self-sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the sole parameter is fully documented as a GUID with a pattern, so the schema does the heavy lifting. The description adds only the endpoint form (GET /supplier?ID=…), which is marginal value over the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ('One supplier by id') and notes the deprecated-inclusion scope, which distinguishes it from cin7core_list_suppliers. It stops short of explicitly contrasting itself with the sibling list tool or naming when to prefer one over the other.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'by id' framing implies single-record lookup versus the list siblings, but there is no explicit when-to-use/when-not statement, no prerequisite guidance, and no named alternative. Usage is only inferable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List customers (active by default): id, name, display name, currency, payment term, tax rule, price tier, sales rep, location, credit limit and hold, status, addresses and contacts. Filter by name (starts with), contact name/email, or modification date. GET /customer.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Only customers whose name starts with this. | |
| page | No | Page number (default 1). | |
| limit | No | Records per page, 1-100 (default 50). | |
| contact | No | Only customers with a contact whose name starts with this or whose email equals this. | |
| modified_since | No | Only customers changed since this time. YYYY-MM-DD (UTC) or ISO 8601 date-time with zone. | |
| include_deprecated | No | true = include deprecated customers. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds value by disclosing which customer fields are returned and that deprecated records are excluded unless include_deprecated is set, but it says nothing about pagination behavior 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?
Front-loaded with the operation and default scope, then filters, then endpoint. The long field enumeration is verbose but earns its place as the only record of return fields, since no output schema exists.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the returned-field list and the deprecated-record behavior are the key additions an agent needs, and both are present alongside the filter set. The main remaining gap is pagination guidance, though page/limit are documented in the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all six parameters are already documented in the schema, which sets the baseline at 3. The description restates the filter semantics (starts-with name, contact name/email) consistently but adds no syntax or format detail 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?
Clear verb+resource ('List customers') with the default scope ('active by default') and an explicit field inventory, plus the underlying GET /customer endpoint. It does not explicitly contrast itself with the sibling get_customer, so it stops short of full sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The parenthetical '(active by default)' and the enumerated filter conditions (name starts-with, contact name/email, modified date) give implied guidance on how to scope a query. However, there is no explicit when-to-use statement and no mention of the alternative get_customer for a single record.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List stock locations (warehouses) with their id, name, default flag, address, bins and pick zones. Location names are what the stock-availability and sale/purchase tools use. GET /ref/location.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Only locations whose name starts with this. | |
| page | No | Page number (default 1). | |
| limit | No | Records per page, 1-100 (default 100). | |
| deprecated_only | No | true = only deprecated locations. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds beyond that by disclosing the returned field set and the underlying endpoint (GET /ref/location), though it says nothing about pagination behavior, ordering, or auth/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?
Three short sentences, front-loaded with the resource and payload, then the cross-tool usage note, then the endpoint. No filler or restated boilerplate.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description usefully enumerates the returned fields, and with no required parameters the tool is simple to invoke. It is nearly complete; only pagination guidance and the meaning of 'deprecated' locations are left to inference.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and all four parameters (name prefix, page, limit, deprecated_only) are documented in the schema itself, so the baseline is 3. The description adds only indirect meaning about location names; it does not clarify the prefix filter, paging, or the deprecated_only flag.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('List stock locations (warehouses)') and enumerates the returned fields (id, name, default flag, address, bins, pick zones), which distinguishes it from the get_* and other list_* siblings that target different resources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Location names are what the stock-availability and sale/purchase tools use' tells the agent why it would call this list first, giving real usage context rather than none. It stops short of explicit when-not or alternative routing, but there is no competing location lookup tool among the siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List products (active by default): id, SKU, name, category, brand, type (Stock/Service), costing method, unit of measure, barcode, price tiers, average cost, reorder settings, status and description. Filter by name or SKU (contains) or by modification date. GET /product.
| Name | Required | Description | Default |
|---|---|---|---|
| sku | No | Only products whose SKU contains this. | |
| name | No | Only products whose name contains this. | |
| page | No | Page number (default 1). | |
| limit | No | Records per page, 1-100 (default 25). | |
| modified_since | No | Only products changed since this time. YYYY-MM-DD (UTC) or ISO 8601 date-time with zone. | |
| include_suppliers | No | Include each product's suppliers and supplier prices. | |
| include_deprecated | No | true = include deprecated products. | |
| include_reorder_levels | No | Include reorder levels per location. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=true, so the safety profile is covered. The description adds real behavioral context beyond that: the default scope is active-only products, with deprecated ones gated behind a flag, which shapes what the agent gets back. Pagination behavior is left to the schema, keeping this short of a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single dense sentence plus the endpoint line, with the returned-field list and the default scope front-loaded. The field enumeration is long but earns its place given there is no output schema to describe the payload.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description usefully enumerates the returned fields and discloses the default active-only scope plus the filter modes. Pagination defaults and response envelope are not covered, but those live in the schema, so the description is adequate for this list 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 100%, so all eight parameters (sku, name, page, limit, modified_since, include_suppliers, include_deprecated, include_reorder_levels) are already fully documented. The description restates the two contains-filters and the date filter but adds no syntax or format detail beyond the schema, which is the expected baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (List) and resource (products), enumerates the returned fields, and pins the endpoint (GET /product). An agent can distinguish it from cin7core_get_product (single product) and from the other list_* siblings without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives clear context: products are active by default, and filtering is by name/SKU (contains) or modification date, implying include_deprecated toggles the default. No explicit when-not-to-use guidance or named alternative, but the retrieval context is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List purchases (purchase orders) with order number, status, supplier, order/invoice/required-by dates, invoice and paid amounts, currencies, type (simple/advanced/service) and the order/receiving/invoice/payment statuses. GET /purchaseList.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number (default 1). | |
| limit | No | Records per page, 1-100 (default 50). | |
| search | No | Text contained in the order number, status, supplier, invoice number or credit note number. | |
| status | No | Overall purchase status. | |
| required_by | No | Only purchases with a Required By date on or before this. | |
| order_status | No | Purchase order status. | |
| updated_since | No | Only purchases changed after this time. | |
| updated_until | No | Only purchases changed before this time. | |
| invoice_status | No | Invoice status. | |
| unstock_status | No | Unstock status. | |
| drop_ship_sale_id | No | Only drop-ship purchases created by this sale (GUID). | |
| credit_note_status | No | Credit note status. | |
| stock_received_status | No | Stock received (put away) status. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds real value beyond that by disclosing the returned field set (order/invoice/payment statuses, currencies, amounts) and the underlying endpoint GET /purchaseList, which compensates for the absent output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One dense sentence that front-loads the verb and resource, then the payload contents, then the endpoint. Nothing is wasted, though the long mid-sentence field enumeration slightly hurts scannability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description's enumeration of returned fields is the main cue for what comes back, and annotations cover the safety profile. All 13 parameters are schema-documented, so the only real gap is the missing list-vs-get routing guidance.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with all 13 parameters and 6 enums documented in the schema, so the baseline is 3. The description's mention of 'status', 'supplier' and date fields loosely maps to filter parameters but adds no filtering syntax, date format, or pagination semantics 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?
States a specific verb and resource ('List purchases (purchase orders)') and enumerates the fields returned, so an agent knows exactly what the tool yields. It does not, however, differentiate itself from the sibling cin7core_get_purchase (single-record fetch) or say when a list is preferred over a lookup.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as cin7core_get_purchase. The agent must infer from the name alone that this is the bulk-listing counterpart to the single-get tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List sales (sale orders) with order number, status, customer, order/invoice dates, invoice and paid amounts, currencies, and the quote/order/pick/pack/ship/invoice/payment statuses. Search by order number, customer, invoice number or customer reference; filter by dates and statuses. GET /saleList.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number (default 1). | |
| limit | No | Records per page, 1-100 (default 50). | |
| search | No | Text contained in the order number, status, customer, invoice number, customer reference or credit note number. | |
| status | No | Overall sale status. | |
| ship_by | No | Only sales with a Ship By date on or before this, not yet shipped. | |
| external_id | No | Only sales with this External ID. | |
| pack_status | No | Combined pack status. | |
| pick_status | No | Combined pick status. | |
| order_status | No | Order status. | |
| quote_status | No | Quote status. | |
| created_since | No | Only sales created after this time. | |
| updated_since | No | Only sales changed after this time. | |
| updated_until | No | Only sales changed before this time. | |
| invoice_status | No | Combined invoice status. | |
| shipping_status | No | Combined shipping status. | |
| order_location_id | No | Only sales from this order location (GUID). | |
| credit_note_status | No | Credit note status. | |
| ready_for_shipping | No | true = only sales packed but not yet shipped. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered and the bar is lower. The description only adds the endpoint reference; it says nothing about pagination behavior, result caps, or that unpaginated listing returns a default page (limit default 50), leaving those traits to the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences: what is listed first, then how to search, then how to filter, with the endpoint tacked on. No filler, though the long enumeration of status fields is somewhat dense and could be compressed since the schema lists those statuses anyway.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description usefully enumerates the shape of a returned sale record (order number, status, customer, dates, amounts, currencies, stage statuses), which compensates well for the missing return schema. Combined with 100% schema coverage on the query side, an agent has enough to call and interpret it; only pagination/output-envelope behavior is unstated.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% across all 18 parameters, including enum values and their meanings, so the schema already does the heavy lifting. The description's summary of searchable keywords and filter dimensions maps loosely onto those params but adds no format, default, or range detail beyond them.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('List sales (sale orders)') and goes further by enumerating the returned fields and the searchable/filterable dimensions, plus the backing endpoint GET /saleList. The list-vs-get split from siblings like cin7core_get_sale is inferable from the name, but the description never explicitly routes an agent between listing and fetching a single sale.
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?
'Search by order number, customer, invoice number or customer reference; filter by dates and statuses' gives practical guidance on how to narrow results, which is genuine usage context. However there is no when-to-use/when-not guidance and no explicit alternative named (e.g., use cin7core_get_sale for a single order), so usage is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List stock adjustments: task id, number, effective date, status, expense account, reference and comment. GET /stockadjustmentList.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number (default 1). | |
| limit | No | Records per page, 1-100 (default 50). | |
| status | No | Only adjustments with this status. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds the endpoint (GET /stockadjustmentList) and field list, but says nothing about pagination behavior or result volume despite page/limit params existing. Some added context but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single compact sentence plus endpoint. Front-loaded with the action and field list. No wasted words, though the field enumeration arguably duplicates what a response schema would show (none exists here, so it 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?
No output schema, so listing returned fields is useful, but the description omits pagination semantics and any hint of what happens with an empty filter. Annotations cover safety; remaining gaps are modest, making this adequate but not complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so page, limit, and status are fully documented in the schema with defaults and ranges. The description adds no parameter-level meaning beyond listing output fields. Baseline 3 applies when schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ('List stock adjustments') and enumerates the returned fields. The sibling name cin7core_get_stock_adjustment implies a singular fetch, and 'List' distinguishes it, though the description never explicitly contrasts the two.
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 indication of when to use list vs the get_stock_adjustment sibling, no pagination guidance, no mention of filtering workflow. The agent must infer usage entirely.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List stock transfers between locations: task id, number, from/to location, status, departure and completion dates, reference. GET /stockTransferList.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number (default 1). | |
| limit | No | Records per page, 1-100 (default 50). | |
| search | No | Text contained in the from/to location, status, reference or number. | |
| status | No | Only transfers with this status. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the field set returned by the endpoint, which is useful, but says nothing about pagination defaults or result volume beyond what the schema states.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One front-loaded sentence with no redundancy; every listed field adds informational value. The trailing 'GET /stockTransferList' is developer-oriented plumbing that an agent does not need, a minor waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the field enumeration in the description usefully summarizes the return payload, and pagination is covered by the parameter schema. A note on ordering or default sort would round it out, but nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so page, limit, search and status are all documented in the schema, including the status enum. The description does not add syntax or format meaning beyond that, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (List) and resource (stock transfers between locations) and enumerates the fields returned, so the agent knows exactly what it retrieves. It does not explicitly name the sibling cin7core_get_stock_transfer, but the singular/plural distinction is discoverable from the sibling name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to use this list endpoint versus cin7core_get_stock_transfer for a single record, nor any prerequisite/context for filtering. Usage is only implied by the word 'List'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List suppliers (active by default): id, name, currency, payment term, tax rule, discount, status, addresses and contacts. Filter by name (starts with) or modification date. GET /supplier.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Only suppliers whose name starts with this. | |
| page | No | Page number (default 1). | |
| limit | No | Records per page, 1-100 (default 50). | |
| modified_since | No | Only suppliers changed since this time. YYYY-MM-DD (UTC) or ISO 8601 date-time with zone. | |
| include_deprecated | No | true = include deprecated suppliers. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuinely new behavioral context beyond the annotations: suppliers are active-only by default, and the underlying endpoint is GET /supplier. That default-filtering behavior is not derivable from the annotations or schema alone.
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 dense sentence plus a short endpoint note — the returned fields and filters are front-loaded, and every clause carries information. No filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description compensates by enumerating the main returned fields and noting default filtering, and pagination/defaults are covered by the schema. An agent has enough to call it correctly; only pagination behavior and the response envelope shape remain undocumented anywhere.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all five parameters are already documented in the schema with formats and ranges. The description's filter mention ('name starts with', 'modification date') restates what the schema says and adds no syntax or default detail beyond it, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description gives a specific verb+resource ('List suppliers') and enumerates the returned fields (id, name, currency, payment term, status, addresses, contacts), which tells an agent exactly what this returns versus the single-record cin7core_get_supplier. It does not explicitly name a sibling to route against, but the list-vs-get distinction is clear from the verb.
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 the filters available ('Filter by name (starts with) or modification date') and the default scoping ('active by default'), which implies when this tool is appropriate. However, there is no explicit guidance about when to prefer this over cin7core_list_customers-adjacent tools or when include_deprecated should be toggled.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read Lightspeed X-Series products, stock, sales, customers, stock orders; one-call sales reports.
Read Homebase locations, employees, shifts, timecards, labor costs and time clock status.
Read SaldeoSMART companies, contractors, documents, invoices, bank statements and employees.
Read Nookal locations, practitioners, availability, appointments, clients, cases and invoices.
Add one secure layer between your agents and this server.