Read Veeqo orders, products, stock, warehouses, customers and POs; add notes, tag, set stock.
Scored across 22 tools
Each tool targets a distinct resource+action: list/get pairs are clearly separated (e.g. list_orders vs get_order), and the three write tools (add_order_note, set_stock_level, tag_orders) have unambiguous, non-overlapping purposes. The read/write stock pair (get_stock_entry vs set_stock_level) is clearly distinguished by action and description.
Every tool follows the same veeqo_ prefix plus verb_noun snake_case pattern (list_orders, get_product, add_order_note, set_stock_level, tag_orders). No camelCase or verb-style deviations anywhere.
22 tools is on the heavier side, but the domain genuinely spans many resources (orders, products, customers, suppliers, warehouses, POs, stock, tags, stores), and the list/get pairing means each tool covers a specific resource. Nothing feels redundant or padded.
Read coverage is broad and coherent, but the surface is almost entirely read-only: there are no tools to create or update orders, products, or customers, and no delete operations (notes explicitly cannot be deleted). Notable lifecycle gaps for an order-management domain.
WRITE: add an internal (employee) note to an order, e.g. 'Customer asked for gift wrap'. It is visible to your Veeqo team on the order; it is not emailed to the customer. Notes cannot be deleted through the API. POST /orders/{order_id}/notes.
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes | The note text. | |
| order_id | Yes | Veeqo order id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, destructiveHint=true and idempotentHint=false, so mutation semantics are known. The description adds genuinely useful non-annotation context: visibility scope (team-only, not customer-facing) and the fact that notes cannot be deleted through the API, which signals permanence. It does not contradict the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the WRITE marker, then use case, visibility, immutability and endpoint in four tight clauses with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter mutation with annotations covering safety, the description supplies the missing context an agent needs: audience, permanence, and endpoint. No output schema exists, but a note-add returns little that must be described.
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 only two documented parameters, so the schema carries the semantics (including the 1-2000 maxLength constraint). The description adds no parameter-level 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?
Opens with a specific verb+resource and an explicit 'WRITE:' prefix, immediately distinguishing it from the read-only get_/list_ siblings. The example note content makes the operation's nature 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 makes the use case concrete ('internal (employee) note ... e.g. Customer asked for gift wrap') and clarifies what it is NOT for (not emailed to the customer), which is the key selection-relevant distinction. It does not name alternatives, but no sibling in this list performs a comparable action.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The Veeqo company this API key belongs to: id, name, product (e.g. veeqo-shipping), paying/trial state, address and company settings (currency, weight/dimension units, timezone). The employee list and billing internals are not returned. GET /current_company.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description goes further by disclosing scope boundaries (employee list and billing internals are NOT returned) and the underlying GET /current_company endpoint, which meaningfully sets expectations for the agent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two compact sentences; the returned-field summary is front-loaded and the exclusions plus endpoint trail as useful tail detail. No filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and no parameters, the description correctly carries the burden of describing return contents and explicitly names what is omitted. An agent has everything it needs to call and interpret 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 tool takes zero parameters, which is the baseline-4 case. The schema is empty, so there is nothing for the description to clarify or compensate for.
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 resource (the Veeqo company tied to the API key) and enumerates the notable fields returned (id, name, product, paying/trial state, address, settings). No sibling tool returns company data, so it is trivially distinguishable from the list/get 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?
Usage is implied rather than stated: an agent can infer this is for fetching account/company context, and there is no competing company tool to disambiguate against. However, the description never says when to reach for it or what task it enables, so it stays at minimum viable.
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 with billing and shipping addresses and notes. GET /customers/{id}.
| Name | Required | Description | Default |
|---|---|---|---|
| customer_id | Yes | Veeqo customer id. |
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 real value by disclosing what the response contains (billing address, shipping address, notes), which partially compensates for the absent output schema, but says nothing about error behavior for unknown ids.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, content-bearing first, with only the redundant 'GET /customers/{id}' endpoint restatement padding the tail. Nothing else wastes space.
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 is nearly sufficient, and listing returned fields helps offset the missing output schema. It only falls short on usage routing versus veeqo_list_customers.
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?
Only one parameter and schema description coverage is 100%, so the schema already documents customer_id as the Veeqo customer id. The description's 'by id' adds no format or constraint detail beyond that, so this is the baseline case.
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 (customer) with scope ('one customer by id'), and enumerates the returned fields (billing/shipping addresses, notes). The singular 'one ... by id' implicitly separates it from veeqo_list_customers, but it never names that sibling, so the differentiation is inferential rather than explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No when-to-use statement, no prerequisites, and no mention of the obvious alternative veeqo_list_customers for multi-customer retrieval. The agent must infer that this tool is for looking up a single known id.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One order by id: status, totals, line items (sellable ids, SKUs, quantities), customer and delivery address, store, notes, tags, allocations and shipments with tracking numbers. GET /orders/{id}.
| Name | Required | Description | Default |
|---|---|---|---|
| order_id | Yes | Veeqo order id (not the store's order number — find it with veeqo_list_orders query). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false), so the bar is lower; the description still adds value by disclosing exactly what data comes back (line items, allocations, shipments with tracking numbers) and the underlying endpoint. That return-content detail matters because no output schema exists, though error behavior for a missing id is not covered.
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 resource and return fields front-loaded, followed by the endpoint path. Nothing is wasted, though 'GET /orders/{id}' is marginally redundant for an agent that only needs to call the 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?
For a one-parameter read with no output schema, the description is appropriately thorough about returned fields, which is exactly what an agent lacks otherwise. Only edge-case behavior (nonexistent id, permissions) is unstated, which is a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the schema description already explains that order_id is the Veeqo id rather than the store's order number. The description only restates 'by id' and adds no format or constraint detail beyond the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('One order by id') and enumerates the returned content fields, so an agent immediately knows this is a single-record fetch. It does not explicitly name veeqo_list_orders as the alternative, relying on the schema's own note for that differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by 'one order by id' contrasted with a list tool, but there is no explicit when-to-use or when-not-to-use guidance in the description itself. The routing hint ('not the store's order number — find it with veeqo_list_orders') 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.
Returns (RMAs) recorded on an order for one of its sellables: return number, status, reason, returned line items and received quantities. Veeqo's reference requires the sellable id (an order line item's sellable.id). GET /orders/{id}/returns?sellable_id=.
| Name | Required | Description | Default |
|---|---|---|---|
| order_id | Yes | Veeqo order id. | |
| sellable_id | Yes | Sellable (variant) id of the returned item — veeqo_get_order → line_items[].sellable.id. |
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. With no output schema, the description usefully adds the shape of the payload (fields and received quantities) rather than repeating the annotation, though it omits pagination and empty-result 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 dense, front-loaded sentences with no filler; the return-field list leads. The trailing 'GET /orders/{id}/returns?sellable_id=.' is a slightly awkward way to convey the reference endpoint, but costs little.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter read with full schema coverage and annotation-declared safety, the description covers the resource, the required identifier's provenance and the return contents. Only pagination/empty-return behavior is left unstated, which is a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the schema already spells out both order_id and sellable_id, including the veeqo_get_order → line_items[].sellable.id lookup path. The description restates that requirement rather than adding new meaning, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ('Get order returns' / 'Returns (RMAs) recorded on an order for one of its sellables') and enumerates exactly what is returned: return number, status, reason, line items, received quantities. No sibling tool covers returns, so no differentiation is needed and 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?
It supplies a prerequisite — the sellable id must come from an order line item's sellable.id, sourced via veeqo_get_order — which is genuine usage guidance. However, it never states when to prefer this call over veeqo_get_order or any other sibling, and gives no when-not condition.
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 with all sellables (variants), prices, weights, customs data and stock entries per warehouse. GET /products/{id}.
| Name | Required | Description | Default |
|---|---|---|---|
| product_id | Yes | Veeqo product id. |
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 real value beyond that by disclosing exactly what the response contains (variants, prices, weights, customs data, per-warehouse stock entries), which for a tool with no output schema is meaningful behavioral context. It omits error/not-found behavior, keeping it from 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?
Two tightly written sentences with the resource and return scope front-loaded. The trailing 'GET /products/{id}' is mildly redundant with the tool name but is a short, harmless anchor.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and one parameter, the description carries the burden of describing return contents, and it does so thoroughly. What is missing is only edge-case behavior (invalid or non-existent product id) and whether the full payload is always returned or truncated.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the single parameter (product_id, integer > 0) is fully documented in the schema itself. The description only restates 'by id', adding no format, range 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 with explicit scope: 'One product by id'. It also enumerates the returned payload (sellables, prices, weights, customs data, stock entries per warehouse), which cleanly distinguishes it from the sibling veeqo_list_products without the agent needing to open either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'by id' implies this is the single-record lookup versus a list operation, but the description never explicitly says when to use this over veeqo_list_products or what happens on an unknown id. Usage is inferable but not stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One purchase order by id with supplier, destination warehouse and every line item. Paid Veeqo plans only. GET /purchase_orders/{id}.
| Name | Required | Description | Default |
|---|---|---|---|
| purchase_order_id | Yes | Veeqo purchase order id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds a meaningful behavioral constraint the annotations do not carry – that the endpoint is gated to paid Veeqo plans – plus a preview of what the payload contains, which helps the agent anticipate a potentially large line-item set.
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 fragments with zero boilerplate: payload contents front-loaded, then the plan restriction, then the raw endpoint for API mapping. Nothing is wasted or buried.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-id reader with full schema coverage and annotations covering the safety profile, the description is nearly complete: it names the returned entities and the plan gate. It does not mention error behavior for an unknown id or the potential size of the line-item payload, which is the only meaningful remaining gap.
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 a single parameter ('Veeqo purchase order id' with type and range constraints documented in the schema). The description only restates 'by id' and adds no syntax, format, or boundary detail beyond the schema, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description gives a specific verb and resource ('One purchase order by id'), states exactly what is bundled into the response ('supplier, destination warehouse and every line item'), and implicitly but clearly distinguishes itself from the sibling list_purchase_orders by restricting to a single 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?
The 'Paid Veeqo plans only' eligibility note is useful context, and 'by id' implies use when a specific purchase order id is known. However, there is no explicit when-to-use/when-not guidance and no mention of the list_purchase_orders alternative for when an id is unknown.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tracking events (timestamp, status, description, location) for a shipment. Available when the label was bought in Veeqo. The shipment id is in an order's allocations[].shipment. GET /shipping/tracking_events/{shipment_id}.
| Name | Required | Description | Default |
|---|---|---|---|
| shipment_id | Yes | Veeqo shipment id (from veeqo_get_order → allocations[].shipment.id). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, non-destructive, openWorld), so the bar is lower. The description adds real behavioral context beyond them: the availability constraint tied to where the label was purchased, plus where the shipment id originates. It does not discuss empty/paginated results 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?
Three compact sentences: return payload first, then availability precondition, then the raw endpoint. Front-loaded and waste-free, though the trailing GET path is marginally redundant with the tool name and 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?
With no output schema, the description compensates by enumerating the returned event fields and the id's origin, so an agent knows what it will get back. The only gap is what happens when no tracking exists (empty list vs. error), which is minor for a single-parameter read tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the single parameter is fully documented in the schema, including its provenance (veeqo_get_order → allocations[].shipment.id). The description merely repeats the same sourcing hint for the id, adding no syntax or format detail beyond the structured field.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states exactly what is returned — tracking events (timestamp, status, description, location) for a shipment — which is more specific than a generic 'get shipment' phrasing. It is unmistakably distinct from the sibling getters (order, product, supplier, warehouse), though it does not explicitly name a sibling it conflicts with.
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?
'Available when the label was bought in Veeqo' gives a genuine precondition that tells the agent when this call is applicable and when it will yield nothing. It also routes the agent to the id source (an order's allocations[].shipment). No explicit when-not or alternative tool is named, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Stock of one sellable (variant) in one warehouse: physical, allocated, available, incoming (purchase orders) and in-transit levels, bin location and the low-stock flag. GET /sellables/{sellable_id}/warehouses/{warehouse_id}/stock_entry.
| Name | Required | Description | Default |
|---|---|---|---|
| sellable_id | Yes | Sellable (variant) id — product.sellables[].id, not the product id. | |
| warehouse_id | Yes | Warehouse id. |
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 specifying exactly which stock dimensions come back and confirming it is a scoped GET, but says nothing about auth requirements, error cases for invalid ids, or freshness of the levels. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two compact sentences: the field list comes first, the endpoint path second, with no filler. The raw path is mildly redundant given the tool name and schema, 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?
With no output schema, the description usefully enumerates the return fields, which is exactly the compensating detail needed. For a read-only two-parameter tool with 100% schema coverage and full annotations, little else is missing; only edge behavior (errors, stale data) is absent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so both parameters are already documented, including the important 'sellable is the variant id, not the product id' caveat. The description echoes the variant/warehouse scoping but adds no new syntax or format 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 (get) and resource (stock level of one sellable in one warehouse) and enumerates the returned fields — physical, allocated, available, incoming, in-transit, bin location, low-stock flag. An agent can distinguish it from other getters, though it never names the obvious sibling veeqo_set_stock_level as the read/write counterpart.
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 tight scoping ('one sellable in one warehouse'), which tells the agent this is a point lookup rather than a listing, and the endpoint path reinforces the required pair. However there is no explicit when-to-use statement, no exclusions, and no routing to siblings such as veeqo_get_product or veeqo_set_stock_level.
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 (bank details are not returned). Paid Veeqo plans only. GET /suppliers/{id}.
| Name | Required | Description | Default |
|---|---|---|---|
| supplier_id | Yes | Veeqo supplier id. |
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 structurally. The description still adds value beyond them: it discloses the plan/entitlement requirement and that bank details are omitted from the response, both of which an agent cannot infer from the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three compact clauses with zero padding; the core purpose leads, and the caveats (bank details excluded, plan gating) follow. Every fragment carries distinct 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 usefully warns that bank details are not returned and that the endpoint is GET /suppliers/{id}. Minor gaps remain — no error/not-found behavior and no sense of the other fields returned — but for a one-parameter getter this is close to complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for the single supplier_id parameter, so the schema carries the semantics and baseline 3 applies. The description's 'by id' phrasing adds nothing about format or constraints beyond what the schema already states (positive integer, max safe integer).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific retrieval verb and resource with scope qualifier ('One supplier by id'), which inherently distinguishes it from the plural sibling veeqo_list_suppliers. It does not explicitly name that sibling, but the singular/'by id' framing makes the distinction clear without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Paid Veeqo plans only' is a real eligibility constraint that affects whether an agent should call this at all, so it is more than implied usage. However, there is no explicit guidance on when to reach for this versus veeqo_list_suppliers or how to react if the plan gate fails.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One warehouse by id. GET /warehouses/{id}.
| Name | Required | Description | Default |
|---|---|---|---|
| warehouse_id | Yes | Veeqo warehouse id. |
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 only the raw REST path (GET /warehouses/{id}), with no mention of error behavior for missing ids, rate limits, or response characteristics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short fragments with zero padding and the essential detail front-loaded. It is efficient, though arguably under-specified rather than genuinely concise for a tool with no output 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 trivial single-resource getter with one fully documented parameter and annotations covering the safety profile, this is minimally adequate. With no output schema present, the description could reasonably say what the warehouse object contains or what happens when the id is not found.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the single parameter (warehouse_id, a positive integer) is fully documented in the schema. The description adds no syntax or format detail beyond 'by id', 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 with scope ('One warehouse by id'), which implicitly distinguishes it from the sibling veeqo_list_warehouses. It is clear but does not explicitly name or contrast with that sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this versus veeqo_list_warehouses, no prerequisites stated, and no conditions or exclusions given. The agent must infer selection purely from the tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List or search customers with email, phone, billing address and shipping addresses. GET /customers.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number, from 1 (default 1). Pass the previous reply's next_page. | |
| query | No | Free-text search, e.g. an email address or name. | |
| page_size | No | Results per page, 1-100 (default 25). | |
| customer_type | No | Customer type. |
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 underlying endpoint (GET /customers) and hints at the returned fields, but says nothing about pagination behavior, rate limits, or result ordering beyond what the schema's page/next_page note implies.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with zero filler; the capability statement is front-loaded and the endpoint reference is a compact trailing detail. Nothing in the text is redundant.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple, read-only, fully documented list endpoint with no output schema, the description is adequate: the agent knows what it returns and how to page via the schema. The only gap is the absence of explicit routing guidance against the singular get_customer sibling.
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, page_size, query and customer_type are already fully documented in the schema. The description's mention of email/phone/addresses loosely maps to the free-text query parameter but adds no new syntax or constraint information, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb pair (list or search) and the resource (customers), and enumerates the data involved (email, phone, billing and shipping addresses). It implicitly separates itself from the singular sibling veeqo_get_customer, but never names or contrasts that sibling explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'List or search' implies browsing/querying rather than fetching one known customer, which gives an agent some routing signal. However, there is no explicit statement of when to use this instead of veeqo_get_customer, nor any note about pagination workflow or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the delivery methods orders can use (id, name, cost). GET /delivery_methods.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number, from 1 (default 1). Pass the previous reply's next_page. | |
| page_size | No | Results per page, 1-100 (default 25). |
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 and the fact that paginated list results are returned, but says nothing about rate limits, ordering of results, or total counts.
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 covering resource, scope, return fields, and endpoint with zero filler. Nothing could be removed without losing information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter read-only list tool with no output schema, the definition is sufficient: purpose, endpoint, and returned fields are stated, and annotations plus schema cover safety and pagination semantics.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the schema itself documents page and page_size including the 'pass the previous reply's next_page' guidance. The description adds no parameter detail, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb (List) and resource (delivery methods), plus the endpoint GET /delivery_methods and returned fields (id, name, cost). It is unambiguous, though it does not explicitly contrast with any sibling, which is less of an issue since no other tool covers delivery methods.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'delivery methods orders can use' implies the context (populating order delivery choices), but there is no explicit when-to-use, prerequisite, or alternative mentioned. Usage is inferable but not stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List or search orders, newest first, with line items, customer, delivery address, store, allocations and shipments (tracking numbers). Filter by status, store, tag, free text, created/due date or update time. GET /orders.
| Name | Required | Description | Default |
|---|---|---|---|
| tag | No | Only orders carrying the tag with this exact name. | |
| page | No | Page number, from 1 (default 1). Pass the previous reply's next_page. | |
| query | No | Free-text search (order number, customer name, email, SKU...). | |
| status | No | Order status. | |
| since_id | No | Only orders with an id greater than this. | |
| due_after | No | Only orders due on or after this date (yyyy-mm-dd). | |
| page_size | No | Results per page, 1-100 (default 25). | |
| due_before | No | Only orders due on or before this date, whole day included (yyyy-mm-dd). | |
| channel_ids | No | Only orders from these store (channel) ids — see veeqo_list_stores. | |
| created_after | No | Only orders created on or after this date (yyyy-mm-dd). | |
| updated_since | No | Only orders updated at or after this ISO 8601 date-time with timezone (sent in UTC). | |
| created_before | No | Only orders created on or before this date, whole day included (yyyy-mm-dd). | |
| allocated_at_warehouse_id | No | Only orders allocated at this warehouse id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint/openWorldHint/destructiveHint, so safety is covered. The description adds real behavioral value: results are 'newest first', the response includes nested line items, customer, allocations and shipments, and it maps to GET /orders. It omits pagination caveats, but the page/page_size schema fields cover those.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tightly packed sentences: the first front-loads what the tool returns and ordering, the second summarizes filtering. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only list tool with full schema coverage and no output schema, the description is complete enough: it discloses ordering, returned entities, and the endpoint. Slightly short on pagination guidance, but the schema handles page/page_size.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all 13 parameters in detail. The description only summarizes the filter categories and adds no syntax, format or cross-parameter semantics beyond what the schema provides. 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 pair ('List or search') and resource ('orders'), and enumerates the fields returned (line items, customer, delivery address, store, allocations, shipments). This is clearly distinguishable from the single-order sibling veeqo_get_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 enumerates the available filter dimensions (status, store, tag, free text, dates, update time), which implies when each filter applies, but it never states when to use this tool versus alternatives such as veeqo_get_order for a single order. Usage is inferred rather than directed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List or search products with their sellables (variants): SKU, UPC, price, cost, and per-warehouse stock entries (physical, allocated, available). GET /products.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number, from 1 (default 1). Pass the previous reply's next_page. | |
| query | No | Search by product name or SKU. | |
| since_id | No | Only products with an id greater than this. | |
| page_size | No | Results per page, 1-100 (default 25). | |
| warehouse_id | No | Only products with stock in this warehouse. | |
| created_since | No | Only products created at or after this ISO 8601 date-time with timezone. | |
| updated_since | No | Only products updated at or after this ISO 8601 date-time with timezone. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description goes beyond that by naming the underlying endpoint (GET /products) and describing the shape of returned objects — sellables and per-warehouse stock — which is genuinely useful given 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?
Two sentences, front-loaded with the core verb and resource, then the payload contents, then the endpoint. No filler or restatement of the title.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 7 optional params, no output schema, and no required inputs, the description does the important extra work of sketching return contents. It stops short of explaining pagination/cursor flow or result limits, though the schema's page description partially compensates.
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?
All 7 parameters have rich schema descriptions (100% coverage), including pagination semantics via 'Pass the previous reply's next_page'. The description adds only the general notion of search and per-warehouse stock, which maps loosely to the existing 'query' and 'warehouse_id' schema text, 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 pair (list/search) on a specific resource (products) and immediately enumerates the returned payload — sellables with SKU, UPC, price, cost, and per-warehouse stock entries. This is clearly distinguishable from the singular veeqo_get_product sibling without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies both browsing and searching ('List or search'), and the presence of a 'query' param supports that, but it never states when to prefer this over veeqo_get_product or veeqo_get_stock_entry, nor any when-not conditions. Usage is inferable but not guided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List or search purchase orders with supplier, destination warehouse and line items (ordered/received quantities, cost). Search-index backed, so a just-changed PO may be stale here — confirm with veeqo_get_purchase_order. Paid Veeqo plans only. GET /purchase_orders.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number, from 1 (default 1). Pass the previous reply's next_page. | |
| order | No | Sort direction, used with sort_by. | |
| query | No | Search supplier name/post code, PO number, reference, SKU, UPC or item title. | |
| state | No | Lifecycle state (draft/active/completed) or a received-status filter (not_received, partially_received, fully_received, past_due, all). Default: all states including drafts. | |
| sort_by | No | Sort field (default created_at, newest first). | |
| page_size | No | Results per page, 1-100 (default 25). | |
| sellable_id | No | Only active POs containing this sellable (variant) id. | |
| supplier_id | No | Only POs for this supplier. | |
| created_after | No | Created on or after this date (yyyy-mm-dd). | |
| updated_since | No | Updated at or after this ISO 8601 date-time with timezone. | |
| created_before | No | Created on or before this date, whole day included (yyyy-mm-dd). | |
| reference_number | No | Exact PO reference number. | |
| destination_warehouse_id | No | Only POs delivering to this warehouse. |
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 goes further with two facts annotations cannot express: the search index means recently modified POs may be stale, and the endpoint is gated to paid plans. Both materially change how an agent should trust and call the 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?
Three short clauses, front-loaded with purpose and scoping, followed by the staleness caveat with the routing alternative, then the access constraint and raw path. Nothing is redundant and nothing is buried.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 13-parameter, zero-required, read-only search tool with no output schema, the description covers purpose, filtering dimensions, staleness, plan gating and the corrective sibling. It stops short of describing the response envelope or pagination flow, though the schema's page/next_page text partly compensates.
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 13 parameters (including enum semantics for state, sort_by and order) is already documented in the schema. The description mentions supplier, warehouse and line-item data but adds no filter syntax, date-format or pagination 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+resource ('List or search purchase orders') and immediately scopes the payload (supplier, destination warehouse, line items with ordered/received quantities and cost). It also implicitly separates itself from the single-PO sibling by using list/search language.
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 names the alternative tool and the condition that selects it: if a PO was just changed and reads stale, confirm with veeqo_get_purchase_order. It also states the access prerequisite ('Paid Veeqo plans only'), which is exactly the kind of when-you-can-use-this guidance agents need.
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 (stores) connected to Veeqo — Amazon, eBay, Shopify, POS, etc. — with id, name, type and state. Use the ids to filter orders by store. Marketplace credentials and integration settings are never returned. GET /channels.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number, from 1 (default 1). Pass the previous reply's next_page. | |
| page_size | No | Results per page, 1-100 (default 25). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavioral context: 'Marketplace credentials and integration settings are never returned' discloses a security-relevant exclusion, and 'GET /channels' names the underlying endpoint. It does not mention pagination behavior, but the schema's next_page hint covers that.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two compact sentences with zero filler: the first front-loads what the tool returns, the second gives the follow-up action, and the exclusions/endpoint are appended without padding. Every clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description correctly compensates by naming the returned fields (id, name, type, state) and the excluded data. For a simple two-param read-only list tool this is nearly complete; only pagination response shape is left to 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% and both parameters (page, page_size) carry their own defaults and limits, so the schema does the heavy lifting. The description adds nothing about parameter syntax or defaults, which matches the baseline 3 when coverage is complete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('List the sales channels (stores) connected to Veeqo') and enumerates the concrete values an agent will see (Amazon, eBay, Shopify, POS), plus the returned fields (id, name, type, state). This is immediately distinguishable from sibling list tools like veeqo_list_warehouses or veeqo_list_suppliers.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Use the ids to filter orders by store' gives the downstream purpose and hints at why an agent would call this before veeqo_list_orders, which is useful implied usage. However, it never states when to prefer this over alternatives or any prerequisites, so guidance remains implicit rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List suppliers with address, sales/accounting contacts, currency, credit limit and open/completed purchase-order counts (bank details are not returned). Paid Veeqo plans only. GET /suppliers.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number, from 1 (default 1). Pass the previous reply's next_page. | |
| page_size | No | Results per page, 1-100 (default 25). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, destructiveHint=false and openWorldHint, so safety is covered. The description adds real value beyond them: the exact field set returned, the explicit negative 'bank details are not returned', and the paid-plan gating. It stops short of 5 because no response shape or pagination semantics are described.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short, front-loaded sentences with no filler: what is returned, what is excluded, the plan gate, and the endpoint. Every clause earns its place and the most important content (the field list and exclusion) leads.
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 present, the description carries the return-value burden and does so by naming the fields and the omitted bank details, while annotations cover the safety profile and the schema covers pagination. Only minor gaps remain (no ordering/filtering behavior), so it is nearly complete for a simple paginated 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% and both parameters (page, page_size) are fully documented in the schema, including the 'pass the previous reply's next_page' hint. The description adds nothing about parameters, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('List suppliers') and enumerates the fields surfaced (address, contacts, currency, credit limit, PO counts), which is much more informative than a restated title. It never names the sibling it is contrasted with (veeqo_get_supplier for a single supplier), so it falls short of the top band for 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?
'Paid Veeqo plans only' is a genuine availability prerequisite, and the schema's next_page note implies the pagination loop. However, there is no explicit when-to-use vs when-to-use-something-else guidance (e.g., list vs. veeqo_get_supplier), 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.
All tags in the account (id, name, colour, how many records use it). Use the ids with veeqo_tag_orders. GET /tags.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false), so the description only needs to add context. It does: account-wide scope and the shape of what is returned. It omits pagination/rate-limit behavior, but for a trivial GET this is a minor gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two compact sentences plus the endpoint; the scope and returned fields are front-loaded and the routing hint follows. No filler whatsoever.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so the description carries the return-value burden and does so by naming the exact fields returned. Combined with the routing hint to veeqo_tag_orders, an agent has everything needed to call and 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 tool takes zero parameters, so per the rubric the baseline is 4. Schema coverage is 100% and there is nothing further for the description to disambiguate.
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 the resource (all tags in the account) and enumerates the returned fields (id, name, colour, usage count), so the agent knows exactly what this produces. It is distinguishable from veeqo_tag_orders, which it explicitly points to as the consumer of these ids.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
"Use the ids with veeqo_tag_orders" gives clear downstream routing, telling the agent why it would call this first. There is no explicit when-not or alternative-list guidance, but with no comparable sibling list-tags tool the context is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List warehouses with address, phone and dispatch cut-off times. Use the ids for stock levels and warehouse filters. GET /warehouses.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number, from 1 (default 1). Pass the previous reply's next_page. | |
| page_size | No | Results per page, 1-100 (default 25). | |
| external_id | No | Only the warehouse with this external id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=true). The description adds useful context about returned fields and the GET endpoint, but does not disclose authentication needs, rate limits, or pagination behavior beyond what the schema already documents.
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 three short, front-loaded sentences with no filler. Each sentence contributes practical information: purpose, downstream usage, and endpoint.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list tool with no output schema, the description identifies the returned fields and indicates how the resulting ids are used. Combined with the schema, annotations, and endpoint, an agent has enough to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all three parameters are already well documented. The description adds no syntax or format details beyond saying to use the returned ids for stock levels and warehouse filters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'List warehouses'. It also identifies the returned fields (address, phone, dispatch cut-off times) and implicitly distinguishes this list operation from the singular sibling get_warehouse.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives a clear use case: 'Use the ids for stock levels and warehouse filters.' However, it does not state when not to use this tool or name an alternative list/get tool, so it falls short of explicit when/when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
WRITE: set the physical stock level of ONE sellable in ONE warehouse (a stock count correction), optionally its bin location. This overwrites the current on-hand quantity, and Veeqo may push the new available stock to the connected sales channels. The entry's infinite-stock setting is read first and kept as it is (this tool never changes it). Veeqo marks this endpoint 'Paid plan only'. GET then PUT /sellables/{sellable_id}/warehouses/{warehouse_id}/stock_entry.
| Name | Required | Description | Default |
|---|---|---|---|
| location | No | Bin/shelf location in the warehouse, e.g. 'Shelf 2B'. | |
| sellable_id | Yes | Sellable (variant) id. | |
| warehouse_id | Yes | Warehouse id. | |
| physical_stock_level | Yes | New physical (on-hand) quantity. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations: it warns the call overwrites the current on-hand quantity, that Veeqo may propagate the new available stock to connected sales channels (an external side effect matching openWorldHint), that infinite-stock is read first and never modified, and that the endpoint requires a paid plan. That is exactly the kind of destruction/scope detail an agent needs on a destructive write.
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 'WRITE:' and the core action, then layers risk and preconditions efficiently. The trailing 'GET then PUT /sellables/{sellable_id}/warehouses/{warehouse_id}/stock_entry' is implementation detail that is somewhat expendable, but the four sentences otherwise earn their 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 destructive, no-output-schema mutation tool, the description supplies the overwrite behavior, channel propagation risk, plan gating, and the untouched infinite-stock setting. Nothing material is missing for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all four parameters are already documented. The description adds only marginal meaning beyond the schema ('optionally its bin location', overwrite semantics for physical_stock_level), so the baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('set'), resource ('physical stock level'), and scope ('ONE sellable in ONE warehouse'), plus parenthetical disambiguation as a 'stock count correction'. An agent can distinguish this from the read-only sibling veeqo_get_stock_entry immediately.
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 'a stock count correction' frames the intended scenario, and 'Paid plan only' gives a real precondition. It does not, however, explicitly name veeqo_get_stock_entry as the read counterpart or state when not to use this write path.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
WRITE: apply existing tags (ids from veeqo_list_tags) to up to 50 orders. Tags can drive Veeqo automation rules and filters. Tagging an order that already has the tag changes nothing. POST /bulk_tagging.
| Name | Required | Description | Default |
|---|---|---|---|
| tag_ids | Yes | Tag ids to apply (1-10). | |
| order_ids | Yes | Veeqo order ids to tag (1-50). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare write, idempotent and destructive hints; the description reinforces idempotency explicitly ('Tagging an order that already has the tag changes nothing') and adds a non-obvious side effect (triggering Veeqo automation rules and filters). It omits auth requirements, rate limits, and why the operation is marked destructive, so it is helpful 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?
Three tight sentences with the operation type and target front-loaded, followed by side effects and the idempotency caveat. 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?
For a two-parameter bulk write with no output schema, the description covers scope, id source, side effects and idempotency. It lacks any indication of the response shape or partial-failure behavior when some order ids are invalid, which an agent might need for a batch call.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with both arrays documented including count ranges, so the baseline is 3. The description adds value by specifying provenance for tag_ids (must be existing tags from veeqo_list_tags) and restating the 50-order batch ceiling, which the schema alone states only as maxItems.
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 ('apply existing tags ... to up to 50 orders'), plus the name of the sibling that supplies tag ids, so it is distinguishable from veeqo_list_tags without reading schemas. The 'WRITE:' prefix and POST /bulk_tagging endpoint pin the operation down precisely.
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?
Points the agent at veeqo_list_tags as the required source of tag ids and explains the effect ('can drive Veeqo automation rules and filters'), giving clear context on why and when to call it. It does not state exclusions or what to do instead when orders already carry tags beyond noting the no-op case.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read Megaventory products, stock, orders and partners; create clients, sales and purchase orders.
Read Linnworks inventory, stock and orders; set stock levels and add order notes.
Read Ordoro orders, products, shipments, suppliers and purchase orders; tag and comment on orders.
Read Sapo store products, orders, customers and stock levels; edit order notes and stock.
Add one secure layer between your agents and this server.