Channable MCP by usefulapi

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

Annotations already flag destructive/non-idempotent/open-world, but the description adds genuinely new behavioral facts: the change is propagated to the marketplace, it cannot be undone through the API, the call is never retried, and a timeout requires manually checking Channable before retrying. That retry/timeout guidance is exactly what an agent needs for a non-idempotent destructive call.

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

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

Front-loaded with the key decision (partial vs full), then constraints, then safety caveats — a sensible priority order with no filler sentences. The raw endpoint path (POST /v1/companies/...) is arguably redundant operational detail, but it is one clause and does not disrupt scanning.

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 three-parameter destructive mutation with no output schema, the description covers scope, per-marketplace limitations, irreversibility, retry/verification behavior, and the buyer-side escape hatch. Nothing an agent needs to invoke this correctly 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%, so the baseline is 3, but the description goes further by explaining the semantic consequence of order_item_ids — that partial cancellation flips the order into a 'partial' state — which the schema does not convey. Minor gap: no mention of how project_id defaults interact with login context beyond what the schema already says.

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 precise framing ('Seller-side cancellation: set an order to cancelled') that names the verb, resource, and actor scope, and immediately distinguishes partial from whole-order cancellation. An agent can tell exactly what this does and how it differs from siblings like channable_get_order or channable_update_return_status.

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 states when to pass order_item_ids versus omit it, names three marketplaces (Amazon, Cdiscount, Spartoo) that reject partial cancellation, and routes buyer-side cancellations to the marketplace seller account instead. That is when-to-use, when-not-to-use, and alternatives in one paragraph.

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 destructive=true, idempotent=false and openWorld=true; the description goes well beyond by stating that Channable forwards the change to the marketplace, that it cannot be undone through this API, that the call is never retried, and what to do after a timeout. That is exactly the retry-safety context an agent needs for a non-idempotent mutation.

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 compact sentences, front-loaded with purpose then constraints, with the endpoint appended rather than leading. Slightly dense, but every sentence carries distinct information and nothing is redundant.

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

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

For a destructive, non-idempotent mutation with no output schema, the description covers marketplace support, data shape, irreversibility, retry semantics, and timeout recovery. Nothing an agent needs to invoke it safely 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% so the baseline is 3, but the description adds real meaning: it clarifies that 'products' holds the order item ids (not catalogue SKUs) and that the status field is optional. This resolves the main ambiguity an agent would have when populating the nested array.

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 ('Manually create a return on the marketplace for products of an order') and scopes it to four marketplaces, which distinguishes it from sibling tools like channable_update_return_status and channable_get_return. An agent can identify exactly 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?

The phrase 'Manually create a return' and the explicit marketplace allowlist (Fruugo, Otto, Veepee, Zalando) give clear conditions for when this tool applies and when it will not. It does not explicitly contrast against channable_update_return_status, but the manual-vs-status distinction is 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?

readOnlyHint=true already declares the safety profile, so the description's job is to add context — and it does, by enumerating the returned sub-resources (addresses, items, fulfillments, event log) and giving the underlying endpoint. What it does not cover is failure behavior (nonexistent order_id) or project scoping effects. Given the annotation coverage, this is solid added value rather than a gap.

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

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

Two sentences, front-loaded with the payload contents, then the id provenance. Nothing is wasted, though the raw endpoint path is the least load-bearing element for an agent that never calls HTTP directly.

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 telling the agent what a call returns, and it does so by listing the embedded entities. Two parameters, both documented, one required. The only omissions are error semantics and whether the event log is truncated.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns an extra point by telling the agent where order_id comes from ('the id field from channable_list_orders'), which is cross-tool semantics the schema cannot express. project_id is left entirely to the schema, which does document its default, so nothing critical is missing.

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 a specific resource (one order) and enumerates exactly what comes back — customer, addresses, items, status, fulfillments, event log — so the agent knows this is a single-record fetch, not a list. It also anchors order_id to channable_list_orders, which separates it from the sibling list tool. The retrieval verb itself is only implicit in the fragment, relying on the title 'Get an order' to carry 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?

Usage is only implied: the note that order_id is 'the id field from channable_list_orders' sketches the list-then-get workflow. There is no explicit statement of when to prefer this over channable_list_orders or what happens if the id is unknown. An agent can infer the path, but it is inference rather than 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?

readOnlyHint=true already tells the agent this is a non-mutating read, so the bar is lower. The description adds the aggregation granularity (daily revenue, per order connection and in total) and the underlying endpoint, but says nothing about default date window behavior, response size, or whether totals and per-connection figures come back together.

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

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

Front-loaded with the resource and its metrics in one dense sentence, followed by a conditional parameter note and the endpoint. The metric list is long but each item is substantive; the trailing endpoint path is only marginally useful but short.

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 spelling out the fields the response contains and the per-connection vs. total split. What's missing is the default time frame when dates are omitted — the one behavior an agent could plausibly get wrong on a call with zero required parameters.

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

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

Schema coverage is 100%, so the baseline would be 3, but the description adds meaning beyond the schema by clarifying that order_config_id is 'the order_config_id field of an order' — i.e. where to source the value — and that supplying it restricts results to a single connection. It remains silent on the effect of omitting start_date/end_date.

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 a specific verb+resource (order statistics of a project) and immediately enumerates the metrics produced — orders, ordered products, commission, shipping costs, revenue, daily revenue. This clearly separates it from the order-CRUD siblings (channable_get_order, channable_list_orders), none of which return aggregates.

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 real usage instruction is 'Pass order_config_id ... for one order connection only', which usefully signals the optional narrowing of scope. There is no statement about when to prefer this over sibling order tools, whether a date range is effectively mandatory, or what happens if the dates are omitted.

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?

readOnlyHint=true already declares the safety profile, so the description only needs to add context. It adds that related entities (item, reason, customer, status, log) come back with the return and names the underlying endpoint, but says nothing about error behavior for missing ids or pagination/expansion options.

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 return shape comes first, then the id provenance and endpoint. Zero filler and nothing important is buried.

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

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

With only two parameters and no output schema, the description's enumeration of returned fields does real work in conveying the response shape. A brief note on behavior for an invalid or unknown return_id is the only material 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 coverage is 100%, so both parameters are already documented, including the project_id default. The description reinforces return_id's provenance from channable_list_returns but adds no format or edge-case detail beyond the schema, which is the expected baseline.

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

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

States a specific verb and resource ('One return') and enumerates the embedded payload ('item, reason, customer, status and log'), which distinguishes it from channable_list_returns at a glance. The explicit note that return_id is the id field from channable_list_returns further pins down the relationship to its sibling.

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

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

The pointer to channable_list_returns as the source of return_id gives clear usage context: list first, then fetch one. It does not state exclusions (e.g., when to prefer the list endpoint or what happens with an unknown id), so it stops short of full when/when-not guidance.

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

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

Annotations only declare readOnlyHint=true, so the description carries most of the behavioral load and does so well: it discloses ordering, AND-combination of filters, UTC date interpretation, and pagination via next_offset. The caveat that 'total is the size of the page, not of all orders' is exactly the kind of non-obvious trap that prevents misuse.

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 tight clauses: purpose, filter semantics, timezone, pagination, response shape, endpoint. No filler, and the most important facts (scope, AND filters, paging) are front-loaded.

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

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

With 12 optional parameters and no output schema, the description fills the critical gaps: page size vs. total, next_offset usage, error_count meaning, and the response envelope keys. It stops short of explaining the distinction between created/retrieved_at/last_modified date families, which the agent must infer from parameter names alone.

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 baseline is 3, but the description adds genuine cross-parameter meaning the schema lacks: filters are conjunctive and all dates are read as UTC (the end_date/retrieved_at/last_modified schema entries do not repeat the UTC note). It also correctly frames offset as 'pass next_offset from the previous reply', reinforcing the schema's own hint.

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 marketplace orders of a project') plus an ordering guarantee ('newest first') and the underlying endpoint. It clearly separates this from get_order/ship_order style siblings by being a collection listing, 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?

Provides useful operational rules ('Filters combine with AND; dates are read as UTC') and pagination mechanics, which tell the agent how to call it. It gives no guidance on when to prefer this over channable_get_order or channable_get_order_statistics, so selection guidance is only implied by the collection-vs-single shape.

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?

Beyond the readOnlyHint annotation, it discloses sort order (newest first), timezone handling (dates read as UTC), pagination mechanics, and the exact response envelope keys. It does not mention the default project fallback or rate/error behavior, but the safety profile is already covered by annotations.

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

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

Five short sentences, each carrying distinct information: scope+ordering, timezone, paging, response shape, endpoint. Nothing is wasted and the core purpose 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 an 11-param list tool with no output schema, the description usefully enumerates the reply fields and paging contract, and the schema covers all filter semantics. Minor gaps: the default-project behavior and whether any filter is required are left to the schema.

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

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

Schema description coverage is 100%, so the schema already explains every one of the 11 parameters, including the next_offset→offset handoff and date formats. The description only restates UTC date reading and the paging convention, adding little beyond structured data — baseline 3.

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 returns of a project') plus the ordering, which clearly separates it from the singular channable_get_return sibling by implication. It stops short of explicitly naming the alternatives, but the operation scope is unambiguous.

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

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

Usage is implied by 'newest first' and the paging instruction, and the schema documents filtering params. However, there is no explicit guidance on when to prefer this over channable_get_return or how to combine the many date filters, so the agent must infer.

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?

readOnlyHint=true already establishes the safety profile, so the bar is lower. The description adds real behavioral detail beyond annotations: result ordering, the exact reply envelope (offers, count, next_offset), and the underlying endpoint, making the read+pagination contract transparent. It does not mention auth scoping beyond the path template or rate limits.

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

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

Three short sentences, no filler: what it lists first, pagination second, reply shape and endpoint last. Front-loaded with the action and result ordering.

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 params, no output schema, and no nested objects, the description covers the return envelope and the pagination loop, which is the main thing an agent needs that the schema cannot express. Minor gap: it doesn't frame what the date/search filters are for, though the schema documents each one.

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 every parameter carries its own description, including the next_offset pagination hint, which the description merely echoes. Baseline 3 applies since the schema does the heavy lifting and the description adds no parameter detail beyond it (the seven filter/date params are untouched).

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 plus resource ('List the offers') with a parenthetical that disambiguates offers as product stock updates, and it names the ordering ('newest first') and returned fields. Among siblings this is clearly the read path counterpart to channable_update_stock, so an agent can select it 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 only usage instruction is the pagination loop ('pass next_offset as offset'), which is genuinely actionable. There is no statement of when to prefer this over channable_update_stock or other list tools, and no exclusions or prerequisites (e.g. project scope requirements).

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 readOnlyHint already establishes this as a safe read operation. The description adds valuable behavioral detail about mode-specific results, mutual exclusivity, and the underlying GET endpoints, but it does not mention pagination, empty results, or error behavior.

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

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

The description is dense and front-loaded, covering all three modes, the mutual-exclusivity rule, and endpoint mapping without wasted prose. Sentence fragments are used efficiently rather than being vague.

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

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

For a two-optional-parameter read tool with no output schema, the description provides enough context to call it correctly in every mode. Annotations cover safety, and the description covers parameter interaction, returned content, and endpoint 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 both parameters are already documented. The description adds useful semantics by explaining what each parameter changes in the response and by noting that transporter_code is the value channable_ship_order expects.

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 resource and explains exactly what is returned in each of three modes: no argument, transporter_code, and channel. It also connects the tool to channable_ship_order, making its role distinguishable from sibling order and return 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?

It explicitly documents all three usage modes and gives a clear constraint: 'Give at most one of the two.' The reference to channable_ship_order further clarifies why an agent would fetch transporter codes.

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 destructive/non-idempotent/openWorld, and the description goes well beyond them: no marketplace status updates, the effect is propagated to the marketplace, irreversibility via this API, no automatic retry, plus explicit advice to verify state in Channable after a timeout. That is exactly the context an agent needs before a destructive write.

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

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

Front-loaded with the primary effect, then endpoint, then caveats — dense and mostly waste-free. However, 'Channable takes no further action on it (no status updates to the marketplace)' followed by 'Channable passes this change on to the marketplace' reads as mildly self-contradictory and costs a re-read.

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 2-parameter destructive mutation with no output schema, the description covers consequences, irreversibility, retry behavior and timeout recovery. It omits preconditions such as required order state or permissions, a minor gap given the otherwise thorough behavioral coverage.

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

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

Schema coverage is 100% and the schema already documents order_id and the optional project_id with a default. The description embeds them in the REST path but adds no semantics 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?

Names a specific verb+resource (mark an order as manually handled) and states the operational consequence: Channable takes no further action and stops pushing status updates to the marketplace. That consequence distinguishes it from channable_cancel_order and channable_ship_order without either schema being opened.

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 trigger condition is clear ('you handle this order yourself'), which tells the agent when this tool applies. It does not explicitly name the alternatives (cancel, ship) or state when-not to use it, so it stops short of 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 destructiveHint=true and idempotentHint=false, and the description adds substantive context beyond them: the change propagates to the marketplace, the order becomes 'partial' and requires later repeat calls, and the operation cannot be undone via the API and is never retried. The timeout warning is exactly the operational caveat an agent needs for a non-idempotent destructive write.

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

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

Purpose is front-loaded, then the required inputs, then the partial-shipment branch and its exception, then endpoint and safety caveats. Every sentence carries information an agent would otherwise have to guess; nothing is redundant with the title or annotations.

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 8-parameter destructive, non-idempotent write with no output schema, the description covers the irreversibility, the retry hazard, marketplace propagation, and the partial-shipment lifecycle. It stops short of stating permission/auth requirements or the shape of a successful response, which are the only remaining gaps for an otherwise thorough definition.

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 is already documented at baseline 3. The description still adds real semantics: transporter must be a Channable transporter code with a pointer to the lister, and order_item_ids changes the resulting order state to 'partial' and implies a later follow-up call — consequences the schema does not state. Optional params like delivery_bill_id and return_tracking_code 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?

Opening clause states a precise verb and resource ("Set an order to shipped, with tracking data") and the endpoint confirms it is a shipment mutation. Siblings like cancel_order, create_return, and mark_order_manual are clearly distinct operations, so no ambiguity arises.

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 the agent to channable_list_transporters for transporter codes, spells out the partial-shipment condition (pass order_item_ids) versus the whole-order case (omit it), and names the exception (Spartoo and Veepee do not support partial shipments). The retry-after-timeout guidance tells the agent exactly what to do in the failure case instead of blindly re-calling.

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 description adds substantial transparency beyond the annotations: it explains marketplace propagation, irreversibility through this API, no automatic retry, and the need to verify the order in Channable after a timeout. These details materially change how an agent should safely invoke a destructive, non-idempotent tool.

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

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

The action and valid statuses are front-loaded, followed by the endpoint and critical operational caveats. It is appropriately sized, though listing all enum values is somewhat redundant with the schema's enum.

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, non-idempotent mutation with no output schema, the description covers the essential behavioral risks: marketplace propagation, irreversibility, no retries, and timeout handling. Combined with full schema coverage and annotations, an agent has enough information to call it correctly.

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

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

Schema coverage is 100%, so the schema already documents status, return_id, and project_id. The description adds meaning by explaining that status affects whether the customer gets money back and that accepted/cancelled differ from rejected, though it does not map each enum value to a specific refund outcome.

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 starts with a specific verb and resource: setting the status of a return, then enumerates all valid statuses. It clearly distinguishes this mutation tool from siblings like channable_create_return, channable_get_return, and channable_list_returns.

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

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

It clearly indicates the tool's use case and adds important operational guidance: the change is passed to the marketplace, cannot be undone via this API, and is never retried. It does not explicitly name when to use this instead of create/get/list return tools, but the purpose makes the boundary clear.

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 destructive/non-idempotent, but the description adds real substance beyond them: the change propagates to every marketplace in the project and affects what customers can buy, it cannot be undone through the API, and the call is never retried. The timeout-recovery instruction is behavior an agent cannot infer from annotations.

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

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

Front-loads the core operation and the non-delta constraint in the first two sentences. Slight redundancy: marketplace propagation is stated twice ("passes the new stock to every marketplace" then "Channable passes this change on to the marketplace") and the raw endpoint path adds little for an agent.

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, non-idempotent batch mutation with no output schema, the description covers everything needed: batch size, value semantics, blast radius, irreversibility, no-retry guarantee, and post-timeout verification. No material gap remains.

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. The description restates what the schema already documents — offer id semantics and "whole new stock value (not a delta)" — adding emphasis but no new syntax or constraints beyond the nested 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 ("Set the stock of up to 50 offers") and immediately scopes it to the offer-id + whole-value model, which distinguishes it from read-side siblings like channable_list_stock_updates. The agent knows exactly what the call 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?

Clear operating context: batch limits (up to 50), whole value vs delta, and explicit recovery guidance on timeout ("check the order in Channable before trying again"). It never names a sibling alternative (e.g., using channable_list_stock_updates to verify), so it stops short of full routing guidance.

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