Linnworks MCP by usefulapi

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly=false, idempotent=false, and destructive=true. The description adds meaningful context beyond those: internal notes stay inside Linnworks while external notes may reach the sales channel, and it clarifies that each call appends a new note rather than updating one. It does not explain permission requirements or why destructiveHint is true, 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?

One tightly packed sentence front-loads the WRITE nature, then covers scope, note visibility, idempotency behavior, and the HTTP endpoint without any wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple three-parameter write tool with full schema coverage, annotations covering safety, and no output schema, the description supplies everything an agent needs: purpose, scope, side effects, idempotency, and endpoint. No critical behavioral detail 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 the schema documents all three parameters including the order_id UUID pattern and note length limits. The description adds semantic meaning for the 'internal' parameter by explaining that internal notes are visible only inside Linnworks while external notes may be passed to the sales channel.

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 ('add a note to an order') with scope ('open or processed') and distinguishes itself from the sibling retrieval tool get_order_notes. An agent can identify the operation without opening the 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?

Provides clear context for when the tool applies (open or processed orders) and explains the internal vs external note distinction, but does not name alternatives or state when not to use it. No sibling add-note alternative exists, so routing guidance is not needed.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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 behavior beyond that: 'Returns an empty order when none matches' tells the agent a miss is a non-error result rather than a 404 or exception, and the endpoint path confirms it is a direct single-record lookup.

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, front-loaded with the action and scope, then the edge-case return behavior, then the endpoint. Every clause carries information; nothing is 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?

For a one-parameter read tool with no output schema, the description covers the key ambiguity (empty result on miss) and the identifier source. It does not describe the shape of a returned order, but sibling order tools and the API contract make that low-risk for a lookup by ID.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with a single parameter, so the baseline is 3; the description earns slightly more by explaining where the value comes from ('the integer shown in the order book'), which helps an agent source the argument rather than just type it. It does not add format or validation detail beyond the schema's exclusiveMinimum/maximum constraints.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (find) and resource (one order) with the identifier type made explicit ('Linnworks order number'), and the scope phrase 'open or processed' separates it from the open-only siblings like linnworks_list_open_orders and linnworks_get_open_orders_details. It stops short of naming the closest alternative, linnworks_find_orders_by_reference, which is the main ambiguity an agent faces.

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 '(the integer shown in the order book)' implies the precondition that the caller already holds a numeric order number, and the 'open or processed' scope hints at coverage. However, there is no explicit when-not statement and no pointer to linnworks_find_orders_by_reference for reference-based lookups, so routing between the two find-tools is left to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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 a real behavioral fact beyond that ('Returns at most 50 orders') plus the REST endpoint, but says nothing about what is returned when no match exists or about pagination/result shape.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sentences, front-loaded with the lookup semantics, then the result cap, then the endpoint. Nothing redundant and 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 single-parameter read tool with no output schema, the description covers purpose, identifier semantics, the 50-result cap, and the underlying endpoint. Only minor gaps remain (behavior on no match, whether matching is exact or partial), which are not critical 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 coverage is 100% and the single parameter is already documented as 'The reference number or secondary reference to look for.' The description adds the example reference formats (Amazon/eBay), which is mildly useful but does not extend beyond what the schema conveys. 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 ('Find orders by their channel reference number') and clarifies the identifier type with concrete examples (Amazon/eBay order number, secondary reference). It implicitly distinguishes itself from linnworks_find_order_by_number by scoping to channel references, 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 description makes clear when the tool is applicable (you have a channel/secondary reference), which is implied usage guidance. It gives no explicit when-not or alternative routing, even though siblings like find_order_by_number and search_processed_orders cover adjacent lookup scenarios.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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), so the description is not obligated to restate that this is a safe read. It adds value by naming the backing endpoint (GET /api/Inventory/GetInventoryItemById) and by listing the returned fields, but says nothing about not-found behavior, authorization, or rate limits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight clauses with zero waste, and the retrieval purpose is front-loaded before the field enumeration and endpoint reference. Nothing is padded or repeated from structured fields.

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 enumerating the product attributes (SKU, barcode, quantities, prices, tax rate, category, dimensions, weight) is genuinely useful context. The only real gap is error/empty-result behavior for an unknown stock item id, which the agent would have to discover at call time.

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 documents the UUID pattern and tells the agent to source the id from linnworks_search_inventory. The description's 'by its stock item id' adds no 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 and resource ('One product by its stock item id') and enumerates the returned attributes, making clear it is a single-item fetch rather than a search. An agent can distinguish it from linnworks_search_inventory on scope alone, since the singular 'one product by id' contrasts directly with a search that returns a list.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is only implied: fetch an item when you already hold a StockItemId. The description never states when to prefer this over linnworks_search_inventory or linnworks_get_stock_levels, and no exclusions are given. The pointer to search_inventory lives in the schema parameter description, not the tool description itself.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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 real operational constraints: a hard cap of 50 ids, the open-orders-only restriction, that 'include' trims optional sections, and the underlying POST endpoint. It stops short of describing pagination or response size 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 with the payload contents front-loaded, followed by the 'include' optimization and the open-order constraint. Every clause carries information; nothing is padding.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the enumeration of returned sections (shipping, customer, totals, items, folders, notes, identifiers, extended properties, bin racks) usefully tells the agent what it gets back, and the open-order and 50-id limits are stated. Only a note on pagination or response size is missing for a tool of this complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so both parameters are already documented, including that 'include' defaults to all optional parts and that order_ids are GUIDs from linnworks_list_open_orders. The description only restates the 50-id cap and the partial-load behavior, adding no new 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?

States a specific verb and resource (fetch full details of open orders by ids) and enumerates exactly what comes back: general info, shipping, customer, totals, items, folders, notes, identifiers, extended properties, bin racks. The phrase 'Only works for open orders' differentiates it from the sibling linnworks_get_order, though that sibling is never named.

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 'Only works for open orders' constraint plus the hint to pass 'include' for partial loads gives implied usage context. However, it never states when to prefer this over linnworks_get_order or linnworks_list_open_orders, and no exclusions or prerequisites are spelled out beyond the open-order restriction.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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 beyond that by enumerating the returned content (general info, shipping, customer, totals, items, notes) and noting that both open and processed orders are reachable, which matters 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?

A single sentence with no filler, front-loading the resource and the identifier constraint, followed by the returned field categories. 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?

For a one-parameter read tool with no output schema, the description adequately covers what is returned and what identifier form is needed. It could be slightly stronger by noting behavior on a missing/invalid id, but nothing essential to calling it correctly 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 description coverage is 100% for the single order_id parameter, and its GUID pattern is already encoded in the schema. The description's '(a GUID)' and 'OrderId / pkOrderId' alignment add only marginal clarification, so the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (get) and resource (one order), and scopes it precisely: retrievable by order id GUID, covering both open and processed orders. This implicitly separates it from siblings like linnworks_find_order_by_number and linnworks_search_processed_orders, though no sibling is 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?

The 'by its order id (a GUID)' phrasing implies when this tool is the right choice (you already hold the id), but it never says when NOT to use it or names the alternative lookup tools (find_order_by_number, find_orders_by_reference). 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.

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 useful content-level context about what a note record contains (text, visibility scope, author, timestamp), but says nothing about ordering, result limits, or empty-note 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 short sentences: the return content first, then the backing endpoint. Nothing is wasted and the payload description 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 carrying the safety profile, the definition is largely sufficient. It does not address result ordering or whether an order with no notes returns an empty list, which is a minor 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 order_id parameter whose UUID pattern and OrderId/pkOrderId mapping are fully documented in the schema. The description adds no parameter detail beyond that, 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 names the resource (order notes) and enumerates the fields returned (text, internal/external, author, timestamp), which is more specific than the tool name alone. It implies read semantics and is distinguishable from the sibling linnworks_add_order_note, though that 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?

There is no guidance on when to call this versus alternatives — notably linnworks_add_order_note for writing notes, or linnworks_get_order for a broader order view. The agent must infer the retrieval use case entirely from the name.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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 that: the newest-first ordering ('as Linnworks returns it') and the exact fields returned. Pagination mechanics are left 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?

One dense sentence with the core purpose front-loaded and no filler. It is information-rich but readable; the trailing API path is minor overhead.

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, but the description compensates by naming the returned fields and ordering, and the schema fully covers pagination and filters. An agent has enough to call and interpret the result, though no detail on empty-history or error behavior.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so every parameter (page, per_page, location_id, stock_item_id) is already documented in the schema. The description restates the location scoping and adds no syntax, format, or constraint detail beyond the schema. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('stock-level change history of one product') and enumerates the returned fields (date, new level, change quantity, value, note). This clearly distinguishes it from the sibling get_stock_levels, which reports current levels rather than history.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description notes the optional single-location scoping versus combined results, which implies when the location_id path is relevant. However, it never explicitly contrasts with get_stock_levels or set_stock_level, so selection guidance is only implied.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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 value by enumerating exactly what data is returned per location (and the underlying GET endpoint), but says nothing about permissions, result volume, or how locations are represented.

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 sentence, front-loaded with the resource and scope, followed by the field list; the endpoint reference is compact and no sentence is wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description carries the return-value burden and does so by listing the returned fields, which is the most useful thing it could add. Missing only location-level formatting and any guidance on multiple locations being returned.

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?

Single required parameter with 100% schema description coverage, and the schema already explains the UUID format and its provenance from linnworks_search_inventory. The description adds no additional meaning about the parameter, 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+resource and enumerates the returned measurements (in stock, open orders, due on POs, available, minimum level, unit cost, last-changed), which distinguishes it from siblings like get_stock_history or list_stock_locations. It never names a sibling tool explicitly, so routing is inferred rather than stated.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No when-to-use, when-not, or alternative guidance is given. The 'one product' scoping hints it is per-item rather than bulk, but an agent gets no signal about when to prefer this over get_stock_history or linnworks_get_inventory_item.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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 beyond that by naming the underlying endpoint (GET /api/Inventory/GetCategories) and disclosing the shape of the returned records (id and name). It does not discuss volume or rate limits, which keeps it 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?

Two short sentences, purpose front-loaded, with the endpoint reference trailing as secondary detail. Every clause earns its place and there is 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 parameters and no output schema, the description carries the whole burden and does so: it states what is listed, what the records contain, and which API call backs it. An agent has everything needed to call and interpret this tool 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?

The tool takes no parameters at all, so the 0-param baseline of 4 applies. The description appropriately spends no words on arguments and instead documents the response fields.

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 product categories') and even names the returned fields (id and name). The resource noun cleanly separates it from same-verb siblings like linnworks_list_suppliers, linnworks_list_stock_locations, and linnworks_list_postal_services.

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 verb 'List' and the resource: there is no explicit when-to-use statement, no prerequisite, and no named alternative. For a zero-parameter read tool the implied usage is unambiguous, but nothing in the text actively guides selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description usefully enumerates what the response contains (status, reference, source, received date, shipping, customer, totals, items), but adds nothing about pagination semantics, rate limits, or how the default location is resolved beyond a pointer 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?

Two tight sentences with no filler, front-loaded with the core verb+resource and the scoping constraint. The field enumeration in sentence one is dense but earns its place by previewing the response shape; nothing is 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 compensates by listing the returned data groups, and the pagination contract (page/per_page, next_page) is fully carried by the schema. Only the routing question — this tool vs. the several sibling order-retrieval tools — is left unanswered.

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%: every parameter, the text-filter enum set, the match modes and the date formats are already documented in the schema. The description only restates that filters cover 'reference, customer, SKU ...' and a received-date range, 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 (page through/list), a specific resource (open, not-yet-processed orders) and a scope qualifier (a fulfilment location). The parenthetical '(not yet processed)' and the endpoint POST /api/Orders/GetOpenOrders make it trivially distinguishable from siblings like linnworks_search_processed_orders or linnworks_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?

It gives implied usage ('narrow with text filters and a received-date range') and notes that location_id defaults to the account default, but never says when to choose this tool over search_processed_orders, get_order, find_order_by_number, or get_open_orders_details. The agent must infer the selection criteria from names alone.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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 the HTTP GET endpoint and names the returned data domains, but it omits pagination, rate limits, auth requirements, and 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?

The description is a single front-loaded sentence followed by the endpoint path. Every clause earns its place by naming the resource and the returned fields, 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 zero-parameter, read-only list tool whose annotations cover safety, the description is largely sufficient and even enumerates returned data domains. It stops short of describing pagination, ordering, or full return format, but no output schema exists and the operation is simple.

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 there are no parameter semantics to explain; the schema is an empty object. The baseline for zero parameters is 4, and the description correctly avoids inventing parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource ('List the postal (shipping) services') and adds the exact data domains returned (courier vendor, tracking and weight requirements, linked channels). This cleanly distinguishes it from all sibling tools, which cover orders, inventory, stock, suppliers, and categories.

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 when-to-use guidance, prerequisites, or alternatives. It simply states what the tool lists, leaving the agent to infer that it should be called whenever postal services are needed.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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), so the bar is lower. The description adds real value beyond them: it lists the returned attributes (compensating for the missing output schema) and supplies the underlying endpoint GET /api/Inventory/GetStockLocations, plus the id-linking contract. It does not mention pagination, auth requirements, or whether inactive locations are included.

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 compact sentence front-loads the purpose, followed by the field enumeration and the id-reuse note; the endpoint reference is the only mildly technical extra and it aids API mapping. Nothing is padded or restated from 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 no output schema, the description carries the burden of describing return content, and it does so by naming id, name, address and fulfilment-centre status. It is complete enough to invoke and consume correctly, though it is silent on result ordering, pagination, and whether disabled locations appear.

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 indicates a non-parameterized call and adds the meaningful clarification that returned ids are consumed as location_id elsewhere.

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 stock locations') and immediately disambiguates the domain term with parenthetical synonyms ('warehouses, fulfilment centres'). It also enumerates the returned fields (id, name, address, fulfilment-centre flag), so an agent knows exactly what this call yields, and no sibling is close enough to be confused with it.

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 explicit downstream usage guidance: 'Use the ids as location_id in other tools,' which tells the agent why and when to call this relative to the rest of the surface. There is no true alternative tool to exclude, so the absence of when-not guidance is a minor gap rather than a real omission.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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 returned field list, which is useful, but does not add other behavioral context such as ordering, pagination, 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?

A single tightly written sentence with the purpose and returned fields front-loaded. There is 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?

For a zero-parameter, read-only list tool with annotations covering safety, the description is largely complete, and the field list compensates for the absence of an output schema. It could still mention ordering or whether all suppliers are returned, which keeps it from a 5.

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 there are no parameter semantics to document. Baseline 4 applies; the description does not need to explain inputs because none exist.

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 suppliers") and enumerates the fields returned, so the operation is unambiguous. It does not distinguish itself from sibling list tools such as list_categories or list_postal_services, which keeps it from a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The usage is implied by the name and purpose: an agent can infer it should call this when supplier records are needed. However, there is no explicit when-to-use guidance, no exclusions, and no mention of alternatives among the many sibling list/search tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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 real behavioral context beyond that: the default 'include' of StockLevels, the default search fields, and composite/variation parent inclusion defaults. It stops short of describing pagination semantics or result size limits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences with zero waste: purpose and return contents come first, the empty-keyword browse case second. The trailing endpoint reference is the only arguably optional element and costs almost nothing.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 7-parameter, no-output-schema search tool, the definition is nearly complete: it covers what is searched, what is returned, and how extraction options alter the payload. The remaining gap is pagination/volume behavior beyond the schema's next_page hint.

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 parameter is already documented in the schema, including defaults, ranges, and the next_page paging hint. The description only restates the searchable fields and optional includes, adding no syntax or format detail beyond the structured data; 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 ('search the product catalogue') plus the searchable keys (SKU, title, barcode) and the return payload (items with stock levels per location, optional pricing/suppliers/images/extended properties). An agent can distinguish this from the single-item sibling get_inventory_item and from get_stock_levels without opening the 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 sentence 'An empty keyword lists items' gives one concrete usage mode (browse all), which is implied guidance. However, it never states when to prefer this over siblings like get_inventory_item, get_stock_levels, or list_categories, and there are no exclusions or prerequisites.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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 3-month date-range ceiling, the fact that non-exact matching is silently scoped to the last 3 months, and the backing endpoint. It does not describe pagination/output 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 tight sentences plus the endpoint path; the core purpose and the searchable-field list are front-loaded. The trailing POST path is mildly extraneous but consistent with API-reference style and 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?

No output schema exists, yet the description does not explain the returned result shape or that responses are paged (the schema hints at next_page). Given 8 parameters with full schema coverage and annotations covering safety, the description is complete enough to invoke the tool correctly, with the return-format gap being the main omission.

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 enum values and defaults, so the schema carries the parameter burden. The description only restates the searchable fields and the date-range constraint, adding little beyond what the schema already documents. 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 (search processed/despatched orders) and enumerates the searchable fields, so an agent can see it is distinct from open-order or inventory tools. It does not name a sibling explicitly, but '(despatched)' disambiguates from the open-order 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?

Gives a concrete constraint — date range at most 3 months, and non-exact searches cover only the last 3 months — which is genuine usage guidance. However it never says when to prefer this over find_order_by_number, find_orders_by_reference, or list_open_orders, so alternative selection is left to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description goes beyond that by disclosing the two consequences an agent most needs: the value overwrites the existing level, and the change flows outward to the sales channels the item is listed on.

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 write classification and target scope front-loaded, followed by the prerequisite and the endpoint. No filler and nothing buried.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 3-required-param destructive write with no output schema, the description covers what it changes, its side effects, and the pre-check step. The only omission is what the call returns or how failures surface, a minor gap for a tool this simple.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds a genuinely useful semantic the schema omits: 'level' is an absolute quantity, not a delta, and the operation is scoped to a single SKU plus a single location. It still doesn't restate formats or bounds, which the schema handles.

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 an explicit WRITE marker and a precise verb+resource+scope: set the stock level of one product by SKU at one location to an absolute quantity. That scope immediately distinguishes it from the read-only siblings linnworks_get_stock_levels and linnworks_get_stock_history.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It names a concrete prerequisite and the exact sibling to call first (linnworks_get_stock_levels) to inspect the current level before overwriting. It does not, however, state when this tool should NOT be used (e.g., for relative adjustments) or what other write paths exist.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.