Order Desk MCP by usefulapi

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

The annotations already disclose that this is a write, destructive, non-idempotent, open-world operation. The description adds useful context that Order Desk recalculates totals after adding the item, but it does not explain response behavior, permissions, or duplicate handling.

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

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

The description is a single tightly structured sentence that front-loads the write nature and core action. It contains no filler and includes the relevant 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?

Given the rich annotations, full schema coverage, and lack of an output schema, the description is nearly complete for selecting and invoking the tool. It could be improved by noting what the response contains or how duplicate line items are handled.

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 the parameters thoroughly. The description only reiterates the order_id path and the fact that one item is added, without adding format or constraint details beyond the schema.

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

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

The description states a specific verb and resource: add one line item to an existing order. It clearly distinguishes this from creating an order or adding other order-related entities such as notes or shipments.

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 'add one line item to an existing order,' but there is no explicit guidance on when to choose this tool versus alternatives like update_order or list_order_items. No exclusions or prerequisites are mentioned.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true and idempotentHint=false, but the description adds genuinely new behavioral facts: history is append-only, entries can never be edited or removed, and an order caps at 250 entries. That capacity limit and immutability constraint are not recoverable from the annotations or 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 the write semantics front-loaded before the constraints, and no filler. The trailing REST path is mildly redundant implementation detail but small enough not to hurt readability.

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 mutating tool with full annotation coverage and no output schema, the description supplies the key constraints an agent needs before calling it: immutability and the 250-entry ceiling. It does not say what the call returns or whether existing note content matters, leaving a small 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%, so order_id, note and source_name are already documented in the schema with their constraints (maxLength 1800, default 'API'). The description adds no syntax, formatting, or source_name guidance beyond what the schema provides, 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 ('append an entry') and resource ('an order's history') up front, prefixed with 'WRITE:' so the operation class is unambiguous. It is plainly distinguishable from sibling writes like orderdesk_add_order_item or orderdesk_add_shipment, which target different resources.

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

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

Provides explicit when-not guidance: 'do not use it for routine polling,' which steers the agent away from a misuse pattern. However, it never names an alternative tool (e.g., orderdesk_get_order) for reading history, so the routing guidance is incomplete rather than exhaustive.

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=false, idempotentHint=false, and destructiveHint=true, so the write/destructive profile is covered. The description adds non-obvious behavior the annotations lack: the partial-fulfillment semantics and that Order Desk derives tracking_url when omitted. It leaves the odd destructiveHint=true on an additive operation unexplained.

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?

Four short sentences, all load-bearing, with the operation type and target front-loaded before the modeling rules and the endpoint. 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 7-param mutation with no output schema, it covers what the agent most needs: write semantics, partial-fulfillment modeling, and optional-field derivation. It omits response/return behavior and any error or duplicate-shipment considerations, which would have made it fully self-contained.

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 already 86%, so the schema carries most param meaning (baseline 3). The description still adds value by explaining the optional tracking_url derivation and reiterating the 'n/a' convention for tracking_number, but says nothing about cost, weight, or shipment_method.

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 ('record a shipment... against an order') and tags it 'WRITE', which immediately separates it from read siblings like orderdesk_list_order_shipments and the other add_* 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 real modeling guidance: one shipment per parcel, multiple shipments = partial fulfillment, and the 'n/a' fallback for missing tracking numbers. It does not, however, name when to prefer a sibling (e.g., list vs add) or note any preconditions on order state.

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=false, destructiveHint=true, idempotentHint=false and openWorldHint=true, so the 'WRITE:' label is largely redundant. The SKU-matching constraint is genuinely useful domain context, but the description says nothing about duplicate-SKU failure behavior, permissions, or side effects — a notable gap given idempotentHint=false.

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, front-loaded with the WRITE marker and the most important constraint. 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 10-parameter, destructive, non-idempotent mutation with nested metadata/variation_list objects and no output schema, the description is far too thin. It never explains what the nested objects are for or what happens on a duplicate SKU.

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 60%, with price, metadata, variation_list and manufacturer_sku carrying no descriptions. The description adds real meaning for 'code' ('must match the code your orders arrive with') beyond the schema's 'Unique SKU.', but leaves the other undocumented parameters unexplained.

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+resource ('add an inventory item') and prefixes it with 'WRITE:', which cleanly separates it from the read siblings (get_inventory_item, list_inventory_items). It does not explicitly name create-vs-update alternatives, but the intent is unmistakable.

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 usage-like statement is the SKU constraint, not when-to-use guidance. There is no mention of when to call this versus orderdesk_update_inventory_item, nor what to do if the SKU already exists.

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 this as a non-read-only, destructive, non-idempotent, open-world write. The description adds genuinely new behavior: duplicate orders are rejected with the existing order id returned, and a single supplied address is copied into the other. It omits auth/permission requirements and any failure modes beyond duplicates.

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?

Five tightly packed sentences, front-loaded with 'WRITE:' and the operation, with each clause carrying a distinct rule (required items, address fallback, folder default, duplicate handling, endpoint). 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 15-parameter nested-object write with no output schema, this covers the essentials: what is required, key defaults, an automatic side effect, and duplicate/error behavior including the id returned. An agent could call it correctly without further documentation.

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

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

With 73% schema coverage and 15 parameters, the description adds real meaning the schema does not: folder_id omission defaults to the first folder, the address-copy fallback, and the name/company requirement. It still does not touch several money/status fields (tax_total, shipping_total, checkout_data), leaving them to the schema text.

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 new order to the store') and labels the operation type up front with 'WRITE:'. This clearly distinguishes it from siblings like orderdesk_update_order and orderdesk_move_orders.

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

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

Gives concrete preconditions (at least one item; a name or company in one of the addresses) and the folder_id omission rule, so an agent knows what a valid call requires. It stops short of naming alternatives such as update_order for existing orders, so routing guidance is 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.

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 underlying GET path; it discloses nothing about error behavior, auth needs, 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 terse sentences with no wasted words, and the key resource scope is front-loaded. It is efficient, though arguably so terse that it borders on under-specification rather than optimal conciseness.

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

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

For a single-parameter read tool, the schema and annotations carry most of the burden and the description identifies the resource and lookup key. It is largely complete, with only failure/return-format behavior left unspecified (acceptable since no output schema exists).

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 inventory_item_id parameter is already documented in the schema, including the cross-reference to orderdesk_list_inventory_items. The description adds no syntax, 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+resource (retrieve one inventory item) scoped by Order Desk's internal id. The singular "One inventory item" implicitly distinguishes it from sibling orderdesk_list_inventory_items, though the sibling is not named in the description itself.

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 or when-not-to-use guidance is given. The description only implies the retrieval context; it never says to use this rather than the list tool or what to do when the id is unknown.

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 real context beyond that: the id must be Order Desk's internal id and not the cart's order number, and it lists what the response contains. No pagination or rate-limit notes, but a single-resource GET needs little of 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?

Three tight segments: what you get, the disambiguating alternative, and the underlying endpoint. Front-loaded with the payload so an agent knows the value immediately; 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?

There is no output schema, so the enumeration of return fields carries that burden and does it well, and the id-type caveat closes the main misuse risk. For a one-parameter read with annotations covering safety, nothing material 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 coverage is 100% and the order_id property already documents 'not the cart's order number', so the description largely restates the schema. It adds no extra syntax, format, or bounds beyond what the property definition provides, making 3 the correct baseline.

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

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

Specific verb+resource (get one order) with the scope explicitly bounded to 'Order Desk's internal id', and the payload is enumerated (addresses, items, totals, payment, notes, discounts, checkout data, shipments). This clearly separates it from orderdesk_list_orders and the other order-mutating 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?

It names the alternative (orderdesk_list_orders) and the exact condition that selects it: when the agent only has 'your own id', pass source_id. That is clear routing, though it doesn't cover any other selection context (e.g. needing shipments or items in bulk).

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 non-obvious behavior: the API key and mail credentials are never returned, and orders live in exactly one folder — a domain constraint the agent cannot infer from the schema.

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

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

A single dense sentence front-loads the most important item (folders and their role in filtering/moving orders), followed by settings and the credential exclusion. The trailing 'GET /store' is marginally redundant but 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?

With no output schema, the description carries the full burden of describing return values and does so: identity fields, folder mapping, and named settings categories, plus an explicit statement of what is withheld. Nothing needed to call it and interpret the result is missing.

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

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

The tool takes zero parameters, so the baseline is 4; there is no parameter semantics to add and nothing is misrepresented. The description spends its words on the return shape instead, which is the right tradeoff.

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 exactly what the tool retrieves — store name/id, folders (id -> name), and key settings (timezone, locale, stock behavior, shipping methods) — with a concrete endpoint anchor ('GET /store'). No sibling tool reads store-level configuration, so an agent can place it 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?

Explains the operational reason to call it: folder ids 'are needed to filter and move orders,' which implicitly routes the agent here before orderdesk_list_orders/orderdesk_move_orders. It stops short of an explicit when-to-use statement or an alternative to weigh against, so it is strong context rather than full routing guidance.

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 a genuinely non-obvious behavioral fact: Order Desk returns every match with no server-side paging, so limit/offset must be applied client-side. It does not mention auth or rate limits, which keeps 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 tight sentences: the resource and returned fields come first, then the pagination caveat and a compact endpoint reference. Every clause carries information an agent needs.

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

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

With 8 optional parameters and no output schema, the description usefully lists the record fields an agent will receive, compensating for the missing output schema, and explains the paging model. It skips updated_from/manufacturer_sku semantics, but the schema covers those.

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 88%, so the schema already documents every parameter and the baseline is 3. The description adds a little framing on which filters narrow results and how limit/offset relate to the unpaged response, but no syntax or format detail beyond the schema.

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

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

Names a specific verb (search/list) and resource (store inventory) and even enumerates the fields present in a record. It is clearly distinct from get_inventory_item and create/update_inventory_item, though it never names a 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 sentence 'narrow with search/code/name; limit and offset slice the result here' tells the agent how to use the filters, which implicitly distinguishes this search tool from the single-item getter. However it never states when to prefer get_inventory_item or when not to use this tool, so guidance is implied rather than explicit.

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 concrete HTTP endpoint and enumerates returned fields, which is useful but modest; it says nothing about pagination, ordering, or 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?

One compact sentence plus the endpoint, with the resource scope and returned fields front-loaded. Every element earns its place and 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 simple read-only tool with one fully documented parameter and no output schema, the description is largely sufficient: the field enumeration partially substitutes for a missing return-value schema. It falls slightly short on pagination and result-ordering behavior, but nothing essential 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 coverage is 100% and the single order_id parameter is fully documented in the schema as Order Desk's internal order id. The description only restates that one order is targeted and adds a path template, so it adds no meaning beyond the structured fields. Baseline 3 is appropriate for a fully documented single-parameter tool.

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 specific resource (the line items of one order) and enumerates the returned fields (name, SKU, price, quantity, weight, delivery type, variations), which distinguishes it from orderdesk_list_orders and orderdesk_list_order_shipments. It lacks an explicit verb, but the GET endpoint resolves it as a read/list operation.

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 scopes the call to a single order via order_id, which implicitly rules out the all-orders query, but there is no explicit when-to-use, prerequisite, or alternative guidance for siblings like orderdesk_get_order or orderdesk_list_order_shipments. The agent must infer routing on its own.

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?

The annotations already declare readOnlyHint=true, openWorldHint=true and destructiveHint=false, so safety is covered. The description then adds genuinely useful behavior beyond that: newest-first default ordering, AND semantics for combined filters, and the pagination loop via limit/offset/next_offset. It does not cover rate limits or result-size expectations for a 19-parameter query, so it adds value but not richly.

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 dense sentences with no filler, front-loading the core scope before the filtering and paging mechanics. The trailing 'GET /orders' endpoint anchor is compact and useful for API-aware agents rather than 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?

For a 19-parameter read with no output schema and no required fields, the description supplies the essentials an agent needs: default ordering, AND filter combination, date-range preference, and the offset/next_offset paging contract. It leaves the shape of returned records and result-size limits implicit, but the embedded-data list covers most of what a caller must know before invoking.

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 79%, essentially at the threshold where the schema carries the parameters (limit 1-100, offset/next_offset, date boundary semantics, sort defaults). The description adds only the paging loop pattern (limit, offset, next_offset) and a soft nudge toward a date range; it does not clarify the many name-matching or folder_name-vs-folder_id filters. 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 ('Search orders') and enumerates what comes back (items, addresses, totals, payment, shipments), which differentiates it from the narrow siblings list_order_items and list_order_shipments. It stops short of explicitly naming those siblings or contrasting itself with get_order, so an agent must infer the boundary between the bulk list and the single-order fetch.

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 concrete operating guidance: 'Filters combine with AND' and 'Prefer a date range: Order Desk asks clients to avoid open-ended queries.' That is real when/how guidance with a stated rationale. It never states when NOT to use this tool or points at an alternative sibling, which keeps it at 4 rather than 5.

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 returned field set and the HTTP verb, but says nothing about pagination, result ordering, or whether shipments can be empty — useful context that is absent.

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

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

A single compact sentence with the resource front-loaded, followed by a terse endpoint token. No wasted prose; the only slight redundancy is the endpoint line, which still aids routing.

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

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

With no output schema, the description usefully compensates by listing the fields returned. For a one-parameter read-only list tool with clear annotations, this is nearly complete; only pagination/empty-result behavior is left unspecified.

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 order_id is fully documented in the schema itself. The description's phrase 'against an order' restates the parameter's role but adds no format, range, or derivation detail beyond the schema. Baseline 3 is correct when the schema does the heavy lifting.

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

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

Names the exact resource (shipments recorded against an order) and enumerates the fields it exposes: carrier, tracking number, URL, method, weight, cost, dates. An agent can immediately tell this is the read-side counterpart to orderdesk_add_shipment without opening a schema.

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

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

The description implies its purpose (retrieve shipments for a given order) but gives no explicit when-to-use guidance, no prerequisites, and never names an alternative such as orderdesk_add_shipment or orderdesk_get_order. The GET endpoint string is documentational, not usage guidance.

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?

Goes well beyond the annotations by disclosing the hidden side effects: moving runs destination-folder rules that can send e-mail or call fulfillment services, and it writes a history entry. It also states the return value (each order's previous folder). This is exactly the extra context the destructiveHint/openWorldHint annotations cannot convey.

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: operation class first, side effects second, parameter constraint third, with the HTTP endpoint as a trailing tag. No filler and every sentence carries load-bearing 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?

No output schema exists, yet the description still names the return value and enumerates the consequential side effects of the destination folder's rules, which is the main risk an agent needs to weigh before invoking a destructive, non-idempotent write.

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 parameter meanings are already documented, but the description adds the non-obvious cross-parameter constraint that the two destination parameters are mutually exclusive and exactly one is required — information the JSON schema cannot express. Only the 100-item cap and id semantics are left to 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?

Opens with a specific verb+resource+scope ('WRITE: move one or more orders to another folder'), immediately distinguishing it from read/list siblings and even labeling the operation class. An agent can tell what this does 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?

States the mutual-exclusion rule ('pass exactly one of destination_folder_id or destination_folder_name') and points to orderdesk_get_store for resolving folder names, which is real routing guidance. It doesn't state when *not* to move orders or name an alternative tool for related operations, so it stops 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.

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

Although annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, the description adds genuinely non-obvious behavior: that Order Desk's PUT replaces the whole record, so the tool internally reads, applies only the passed fields, and writes the full record back, with metadata and variation keys merged rather than replaced. This merge-vs-replace nuance is exactly the kind of context annotations cannot convey.

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 definition is well front-loaded: an operation-type prefix, then purpose, then the critical merge semantics, then the endpoint. Every sentence carries weight, though the final 'PUT /inventory-items/{inventory_item_id}.' line is largely redundant with the schema's required id.

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 11-parameter mutation tool with no output schema and only 45% schema coverage, the description supplies the most decision-relevant behavior (partial-update merge semantics, whole-record replace risk). It stops short of stating permissions, reversibility guarantees, or error behavior, which would complete the picture.

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 only 45% across 11 parameters, so the description must partly compensate; it does so for the important cases by explaining that metadata and variation_list keys are merged rather than overwritten, and by exemplifying 'stock'. The remaining fields (code, cost, name, price, weight, location) get no additional meaning beyond what the schema minimally provides.

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

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

The description states a specific verb and resource ('change fields of an inventory item') with a concrete example ('stock count'), and the 'WRITE:' prefix immediately signals mutation. It implicitly separates this from the get/list/create siblings through the word 'change', but never names an alternative tool explicitly, keeping it short of 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?

Usage is implied by 'change fields of an inventory item', so an agent can infer this is the edit path rather than create/get/list. However, there is no explicit when-to-use guidance, no prerequisites, and no named alternative such as create_inventory_item for new items, leaving routing to inference.

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

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

Annotations already flag destructiveHint=true and non-idempotent, so the bar is lower; the description still adds real value by explaining that the underlying PUT replaces the whole record, that the tool reads-then-merges so only passed fields change (with the merge/replace split spelled out), and that items are sent back intact. It does not mention auth/permission requirements or failure modes, keeping 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?

Front-loads the operation type and resource, then builds outward to merge semantics, folder behavior, and endpoint. Dense but each clause carries information; the parenthetical is long but earns its place by disambiguating merge vs replace.

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 an 11-parameter destructive mutation with nested objects and no output schema, the description covers the operation model, the merge behavior, and the sibling routing. Gaps remain on permissions/auth and on the non-address scalar fields, but the critical decision-relevant context is present.

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

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

With only 45% schema coverage, the description must compensate, and it does for the important part: it clarifies that shipping/customer address fields and checkout_data/order_metadata keys are merged while other values are replaced. It leaves email, tax_total, handling_total, payment_status, shipping_total, and shipping_method semantics to the schema, which is a partial but meaningful compensation.

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

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

Opens with 'WRITE: change fields of an existing order' – a specific verb, resource, and operation type that an agent can immediately distinguish from create_order, get_order, and the item/inventory siblings. The trailing 'PUT /orders/{order_id}' anchors it to a concrete endpoint.

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 routes folder changes to orderdesk_move_orders ('use orderdesk_move_orders to move it'), which is a clear when-not/alternative signal. It also frames the merge semantics that govern usage, but never states when to prefer create_order or how this differs from bulk operations beyond the folder case.

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