Zenfulfillment MCP by usefulapi

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

Annotations already flag destructiveHint=true and idempotentHint=true, but the description adds crucial context beyond them: the operation cannot be undone, partially-ineligible orders fail per-item and surface in `errors`, and user confirmation is required. This is exactly the behavioral detail an agent needs before invoking a destructive 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?

Front-loads the critical 'WRITE, cannot be undone' warning, then the action, the eligibility caveat, the confirmation instruction, and the endpoint. Every clause carries information; nothing 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?

For a single-parameter destructive tool with no output schema, the description covers safety, eligibility, partial-failure return behavior (`errors`), and the endpoint. Nothing essential for correct invocation 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% and the `references` parameter is well documented in the schema itself. The description restates the 50-item cap (already in maxItems) and the reference format, adding little 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 and resource ('cancel orders by reference') with a scope limit (up to 50) and a clear warning that this is a write operation. An agent can distinguish this from sibling read tools like list_orders or get_order without consulting 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?

Clearly sets the precondition for use ('only orders that can still be cancelled, before the warehouse has packed or shipped them') and instructs the agent to confirm references with the user first. It does not name a sibling alternative for inspection, but the usage context is 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 structurally. The description adds genuine value by enumerating what the response contains (SKU lines, announced vs arrived quantities, note) in the absence of an output schema, but says nothing about failure modes (e.g. unknown reference) or upstream auth/rate constraints.

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

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

A single front-loaded sentence that leads with the resource and scope before the example and return fields. The trailing HTTP endpoint string adds little for an agent choosing a tool, making it slightly less than optimal but not wasteful enough to penalize heavily.

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 one required string parameter and no output schema, the description covers identity, input example, and returned fields, which is nearly everything an agent needs. The remaining gap is behavior on a missing/invalid reference, which would round it out fully.

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

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

Schema description coverage is 100% and the single parameter is already documented as 'Inventory shipment ZF reference, e.g. ZF01123700' with length bounds. The description only repeats the same example and adds no format, case-sensitivity, or lookup semantics 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: fetches exactly one inbound inventory shipment identified by a ZF reference, and declares the returned content (SKU lines with announced/arrived quantities and note). The word 'one' plus 'by its ZF reference' implicitly distinguishes it from the sibling list_inventory_shipments, so an agent can route correctly without opening a schema.

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

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

Usage is implied rather than stated: you call it when you already have a single ZF reference. It never explicitly says to use list_inventory_shipments when you lack a reference, nor does it mention any prerequisites or error behavior for unknown references.

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 read-only, non-destructive, open-world behavior. The description adds useful behavioral context by listing the response contents (addresses, products with ordered/shipped/returned/refunded quantities, shipments with tracking numbers) and the underlying GET endpoint.

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, with the core distinction and return contents front-loaded. There is no filler or repetition of annotation data.

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 provides sufficient context: exact reference type, example, exclusion of ZF references, response contents, and endpoint. An agent can call it correctly without additional description.

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 defines the reference as an external order reference. The description adds meaningful disambiguation by giving an example value and explicitly warning that this is not the ZF reference.

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: retrieving one order by its EXTERNAL reference. It immediately distinguishes the external shop/import reference from the ZF internal reference and names the sibling tool to use for the other case.

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 says this tool is for the external reference, gives an example format, and states that for the ZF reference the agent should instead use zenfulfillment_list_orders with query. That is a clear when-to-use and when-not-to-use routing instruction.

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 and idempotentHint; the description reinforces this usefully by explaining the upsert semantics ('a reference that already exists UPDATES that order') and that fulfillment/shipping fees apply. It does not disclose what an update overwrites on the existing order (address, items, date), which is the key gap for 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 WRITE marker and the core action, with operational notes stacked after in priority order. The semicolon-delimited column list is somewhat long and partly redundant with the schema, but the rest is dense and 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 13-parameter mutation with full schema coverage, no output schema, and rich annotations, the description covers action, side effects, fee implications, test mode, and data-source guidance. The one missing piece an agent would want is the overwrite semantics when an existing reference updates an order.

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 in detail. The description adds the CSV column ordering and the point that each item becomes one row, but that largely restates the schema's fields rather than adding new meaning, so the baseline 3 applies.

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

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

States a specific verb and resource ('send ONE order to the Zenfulfillment warehouse for picking, packing and shipping') and labels it 'WRITE', which immediately separates it from the read/cancel siblings. It also clarifies the create-vs-update behavior via the reference, so an agent knows exactly which operation this performs.

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 zenfulfillment_list_stock for SKUs and gives a precondition ('Check the address with the user first'), plus notes that test mode ships nothing. It stops short of naming when NOT to use it (e.g. cancel_orders for removals) or stating prerequisites like a configured contract, so not quite 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?

Annotations already declare readOnlyHint, destructiveHint=false, and openWorldHint, so the safety profile is covered. The description adds that rows are grouped per shipment and exposes the underlying endpoint (GET /inventory_shipments/export), which hints at bulk export semantics, but it says nothing about result volume, rate limits, or what happens when status and time filters combine.

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, front-loaded with what the tool returns before moving to filters and paging. No filler, though the telegraphic phrasing ('reference, SKU lines, announced quantity, quantity arrived and note') packs a lot into one clause.

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?

Eight optional parameters with no output schema, but the description compensates by naming the returned fields and how rows are grouped per shipment. Paging defaults and per_page bounds live in the schema, so nothing critical for a correct call is missing; the combination rules across filters remain unaddressed.

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

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

Schema description coverage is 100%, so all eight parameters are already documented, including the single-status constraint and free-text targets. The description restates the same facts (one status only, free text covering ZF number/tracking/type) and adds only the pointer that paging mirrors list_orders, so it delivers marginal value beyond the schema.

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

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

States a specific verb and resource ('List inbound inventory shipments') and immediately clarifies the domain concept as 'goods you sent to the warehouse', plus enumerates the returned columns (reference, SKU lines, announced vs arrived quantity, note). It is clearly distinguishable from zenfulfillment_get_inventory_shipment by being a list, though it never names 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?

Provides a constraint ('Filter by ONE status') and cross-references a sibling for paging behavior ('Paging as in list_orders'), which is genuinely useful. However, it never states when to use this versus get_inventory_shipment for a single shipment, nor any prerequisites or exclusions.

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 read-only, non-destructive, open-world profile, so the description correctly spends its budget on what annotations cannot express: the export is one row per product line with rows grouped into orders (a critical shape gotcha), pagination terminates on an empty page, and only one status filter may be applied at a time. It does not mention rate limits or export size 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?

Three information-dense sentences, front-loaded with the resource and its payload, then filter constraints, then paging. Nothing is wasted, though the first sentence is long enough that the paging rule could be scanned past — a small structural cost.

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

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

With no output schema and eight optional parameters, the description carries its weight: it explains the return shape (rows per product line grouped into orders, with addresses and shipment tracking), how to page to completion, and the endpoint. An agent has everything needed to call it correctly and interpret the result.

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 including the status enum and per_page bounds is already documented; baseline 3 applies. The description echoes the 'one status at a time' limit and the page/next_page contract but adds no syntax or format detail (e.g. timestamp format for created_after/updated_before) beyond what the schema 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 gives a specific verb and resource ('List or search the fulfillment orders of this Zenfulfillment account') and then enumerates exactly what each order carries (status, reference, shop order number, totals, addresses, product lines, shipments with tracking). That field inventory makes it unmistakably distinct from siblings like zenfulfillment_get_order (single record) or zenfulfillment_list_returns, 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?

It states operational constraints — 'Filter by ONE status, created/updated time or free text' and the paging loop ('pass next_page back as page; an empty page is the end') — which is genuinely useful invocation guidance. But it never says when to prefer this over zenfulfillment_get_order or zenfulfillment_list_returns, so routing between siblings is left implicit.

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 real value beyond that with the status semantics, the single-filter-type constraint, and the GET /returns/export endpoint context. It stops short of disclosing pagination limits or whether results are capped/sorted.

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?

Content is front-loaded with purpose and status semantics, and every clause carries information. The single dense sentence is somewhat packed with parentheticals, which slightly hurts scanability, but nothing 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 correctly enumerates the returned fields (id, reference, note, products, reason, condition, original order), which is the right compensation. The 'paging as in list_orders' shorthand requires cross-referencing a sibling's docs, a minor completeness gap for an 8-parameter tool.

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

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

Schema coverage is 100%, so the baseline is 3, and the description legitimately adds meaning the schema cannot: it explains that only one of status/time/free-text filtering applies, and it explains why `_id` matters downstream. It does not clarify the format of created_after/updated_before beyond the schema's own 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?

The description opens with a specific verb+resource ('List returns processed by the warehouse') and immediately disambiguates the two status values with their business meaning (PROCESSED = received, DONE = marked refunded). It also enumerates the returned fields and ties the tool to its sibling zenfulfillment_mark_return_done, so an agent can distinguish it from list_orders without opening any schema.

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

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

It states the filtering model explicitly ('Filter by ONE status, time or free text') and points to list_orders for paging conventions, plus surfaces the downstream consumer (mark_return_done needs the `_id`). There is no explicit when-not-to-use guidance, e.g. no note on when to prefer query over the time bounds, which keeps it 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?

Annotations already cover read-only, non-destructive, open-world. The description adds genuine behavioral detail beyond them: results are sorted lowest-first when max_quantity is used, plus the underlying endpoint. Pagination/limit behavior is 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?

Three short sentences: return shape first, filtering/sorting second, endpoint last. Nothing redundant and the most decision-relevant information is front-loaded.

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

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

For a simple read-only list tool with no output schema, the description supplies the return fields, the filter semantics and the sort behavior. Only minor gaps remain, such as what happens when limit truncates results.

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 tying max_quantity to a sorting side effect (lowest first) that the schema does not state, clarifying what the filter actually changes.

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 pair ('stock on hand in the Zenfulfillment warehouse per SKU') and even names the returned fields (sku, quantity_on_stock). No sibling tool lists stock levels, so an agent can route here without ambiguity.

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 usage context: filter by SKU text and/or max quantity 'to find low stock'. It doesn't name an alternative or an explicit when-not condition, but no sibling overlaps enough to need one.

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=true, and the description adds context annotations cannot convey: the status change is one-way ("Cannot be set back through the API") and Zenfulfillment only records status while the money movement is external. That is exactly the irreversibility and side-effect disclosure an agent needs before a 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?

Four short sentences, front-loaded with the operation class (WRITE) and the outcome, followed by the prerequisite and the irreversibility warning. Nothing is redundant or buried.

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

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

For a one-parameter mutation with no output schema and full annotation coverage, the description supplies everything remaining: identifier source, external-refund caveat, one-way behavior, and the underlying endpoint. No gap an agent would hit 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 coverage is 100%, so the baseline is 3, but the description adds a genuine disambiguation beyond the schema field text: use the `_id`, not the ZF reference. That prevents a realistic wrong-identifier error for the sole required parameter.

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 a return's status to DONE (refunded)" — and prefixes it with "WRITE:" so the mutation nature is unmistakable. This is clearly distinguishable from read siblings like zenfulfillment_list_returns or zenfulfillment_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?

Explicitly routes the agent to zenfulfillment_list_returns as the source of the `_id` and warns against using the ZF reference. It also sets the correct expectation that the actual refund happens in the shop, not here, which prevents an agent from believing this tool completes the refund workflow.

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