Shipday MCP by usefulapi

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

Adds real context beyond the annotations: the driver is notified in the Shipday driver app, which is a user-visible side effect an agent should know about, and it reinforces the idempotentHint with "re-assigning to the same driver changes nothing". It does not say what happens if the order is already assigned to a different driver (overwrite vs. error), which is the main remaining behavioral 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?

Three short sentences, led by "WRITE:" so the mutation nature is front-loaded, then side effect, then idempotency, then endpoint. No wasted text.

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 mutation with full schema coverage and annotations, this is nearly complete. The only missing piece an agent might need is behavior on conflict (reassignment to a different driver) and error conditions.

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 both parameter descriptions clearly explain order_id vs. order number and where carrier_id comes from, so the schema carries the weight. The description's URL template mirrors the parameter order but adds no semantics of its own.

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 ("assign a delivery order to one of the account's own carriers") and scopes it to the account's own drivers, which separates it from the on-demand siblings. The PUT endpoint mapping removes any ambiguity about what operation is performed.

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?

"one of the account's own carriers (drivers)" implicitly excludes the on-demand service tools and points to shipday_list_carriers via the schema. "Re-assigning to the same driver changes nothing" gives a clear precondition, but no explicit alternative is named (e.g. shipday_unassign_order for removing an assignment).

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 declare readOnlyHint=true, and the description reinforces this with a meaningful clarification: the call is a POST but "nothing is booked," which resolves the natural POST-is-a-write assumption. It also discloses what the response contains, though it omits auth/rate-limit or no-availability 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 with an embedded list, followed by the read-only reassurance and the underlying endpoint. The purpose and return-shape are front-loaded with essentially no filler, though the trailing endpoint note is of marginal value to 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?

There is no output schema, so the description correctly compensates by spelling out what the quote returns (available services, fee, timing). The remaining gap is edge-case behavior when no service can deliver, which is minor for a read-only quote tool.

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

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

Schema description coverage is 100%, so every parameter is already documented with a description and, for the time fields, a precise ISO 8601 pattern. The description adds no format or constraint detail beyond naming pickup and delivery addresses, 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 (quote) and resource (third-party on-demand delivery availability) and enumerates the payload contents (services, fee, pickup/delivery times). It stops short of differentiating itself from close siblings like shipday_get_on_demand_estimate and shipday_get_on_demand_details, which an agent could easily confuse with this tool.

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?

"Before creating an order" gives a clear lifecycle position, implying usage over shipday_create_order. However, it never names or excludes the near-identical siblings (get_on_demand_estimate, get_on_demand_details), leaving the agent to infer which quoting tool to pick.

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 this as a non-read-only, destructive write operation. The description adds useful behavioral context by stating the order appears on the dispatch board, is unassigned, returns a new orderId, uses UTC times, and maps to POST /orders.

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 compact and front-loaded: write action, dispatch-board effect, unassigned state, return value, timezone, and endpoint. Every clause adds relevant information without unnecessary prose.

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 26-parameter creation tool with no output schema, the description usefully identifies the return value as the new orderId and clarifies the order's initial unassigned state. The full parameter documentation is handled by the schema, though richer notes on irreversible creation behavior could add value.

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 26 parameters and 100% schema description coverage, the schema already explains the parameters in detail. The description adds that times are UTC, but the schema itself already documents UTC formats for the relevant time fields, so this remains baseline-level parameter guidance.

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: insert/create a new delivery order in Shipday. It also distinguishes the action from sibling assignment tools by noting that the created order appears on the dispatch board and is not assigned to a driver.

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 makes clear this is the creation action and implies assignment is separate, but it does not explicitly say when to use this versus querying, listing, or assigning orders. The usage context is present but mostly implied by the create semantics.

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, the description discloses the return payload shape, plan gating, per-tracking-id rate limits, and the underlying GET endpoint. This gives the agent meaningful operational context about safe invocation and 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?

The description is tightly front-loaded: core purpose first, then return details, prerequisites, rate limit, and endpoint. Every sentence adds useful information with no filler.

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

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

With no output schema, the description carries the burden of explaining return values and does so clearly. It also covers the required tracking id, plan restriction, rate limit, and endpoint, leaving no critical gap 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 already 100%, so the baseline is 3, but the description adds that the tracking id is the last part of the order's trackingLink. It does not elaborate on include_static_data, though the schema already documents that 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?

The description states a specific verb and resource—real-time delivery progress of an order by tracking id—and enumerates what is returned: status, timestamps, driver location, and ETA. It does not explicitly distinguish this from the sibling shipday_get_order, but the tracking-id framing makes the intended use clear.

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

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

Usage is implied by the real-time progress framing and the tracking-id requirement, and the description adds important prerequisites: Business Advanced plan only and a 3-requests-per-minute-per-tracking-id limit. It does not state when to prefer this over shipday_get_order or other order-related siblings.

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, so safety is covered. The description adds genuine value by listing the exact data points returned (provider, reference id, third-party fee, Shipday charge, billable total, tracking URL) and by mapping it to the underlying GET /on-demand/details/{orderId} endpoint. It omits edge behavior such as what happens when no on-demand delivery is booked.

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

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

Two tight sentences with zero waste. Returned fields are front-loaded ahead of the endpoint reference, exactly the order 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 no output schema, the description's field list is essential and covers the return shape well; the single required parameter is fully documented in the schema. Only gap is that error/empty-case behavior (no on-demand booking present) is 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%, and the schema already clarifies that order_id is Shipday's internal numeric id, not the order number. The description adds nothing about the parameter beyond the endpoint template, 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 ('Details of the third-party on-demand delivery booked for an order') and enumerates the concrete fields returned (provider, reference id, fee, charge, billable total, tracking URL). An agent can distinguish it from shipday_get_on_demand_estimate or shipday_check_on_demand_availability because it describes already-booked delivery details, not a quote or availability probe.

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 word 'booked' suggests it applies after a delivery exists, versus estimate/availability siblings. No explicit when-to-use, when-not-to-use, or named alternative is given, so the agent must infer routing from sibling names.

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 the description reinforces it with 'Read only: nothing is booked', removing any doubt that this is a quote rather than a booking. It also discloses the response shape (fee, pickup/delivery time, durations, per-service errors) and that the data comes from third-party services, adding real context beyond the annotation.

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 capability and return contents first, then the read-only reassurance and endpoint. Every clause earns its place with no redundancy.

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

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

For a single-param read tool with no output schema, the description supplies both the prerequisite (existing order) and the returned fields, including per-service errors. Nothing an agent needs to invoke or interpret it 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?

With 100% schema description coverage on the single order_id parameter, the schema already carries the semantics, including the important distinction from the order number. The description adds nothing about the parameter, 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 ('Get fee and time estimates ... for an existing order') and enumerates the returned fields, which cleanly separates it from siblings like shipday_get_on_demand_details and shipday_check_on_demand_availability. 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 prerequisite is explicit – it requires an 'existing order' and reads Shipday's GET /on-demand/estimate/{orderId}. It gives clear context for use but names no exclusions or alternative tools (e.g., when to prefer check_on_demand_availability).

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 the description discloses the non-obvious fact that the response is an array because several orders can share one order number, and it names the key fields returned (orderId, carrier, tracking link, status). It omits auth requirements, rate limits, and not-found behavior, keeping it out of the top band.

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: purpose first, then the array-return caveat, then the useful payload fields, ending with the raw endpoint. Nothing is redundant and the scoping caveat 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?

With no output schema, the description carries the return-shape burden and does so adequately by naming the array semantics and the important fields. It stops short of describing empty-result or error behavior for an unknown order number, which is the one remaining gap for a lookup 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, but the description adds real meaning by identifying the parameter as the merchant's `orderNumber` reference and contrasting it with the numeric orderId returned in the payload. That distinction is the main failure mode for this call and it is explicitly addressed.

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 ('Get the details of a delivery order by its order number') and clarifies the identifier is the merchant reference, not the internal ID. It does not explicitly distinguish itself from siblings like shipday_get_pickup_order or shipday_query_orders, so it falls short of the top band.

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 mention that the response carries the numeric orderId 'needed by the write tools' hints at its role in a lookup-then-act workflow. There is no explicit guidance on when to prefer shipday_query_orders or shipday_list_active_orders instead of a direct order-number lookup.

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, so the safety profile is covered; the description adds real value by enumerating the returned payload (restaurant, customer, items, costs, expected pickup date/time, status), which matters since there is no output schema. It does not cover failure behavior for a nonexistent id, 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?

One front-loaded sentence covering verb, resource, key, return contents, and semantics, followed by a terse endpoint mapping. No filler or redundancy.

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

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

For a single-item read with a fully documented one-parameter schema, the description supplies the field-level return context that the absent output schema would otherwise provide. The only gap is no mention of shipday_get_order as the delivery-order counterpart.

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, including positivity and max constraints. The description adds only the word 'numeric', which is already implied by the integer type, so baseline 3 applies.

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

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

States a specific verb (Get), a specific resource (a pickup order), the lookup key (numeric id), and even clarifies what 'pickup' means (customer collects it). It is distinguishable from the sibling shipday_get_order by the pickup scope, and the GET /pickup-orders/{orderId} mapping removes any 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?

The description makes clear this only applies to pickup orders (not delivery orders), which implies when it should be chosen, but it never explicitly says to use shipday_get_order for delivery orders or what to do when the id type is unknown. Usage is inferable but not stated.

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

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

Annotations already provide readOnlyHint=true, so the safety profile is covered. The description adds useful context about active-only scope and returned fields, but it does not mention pagination, result limits, authentication requirements, or other behavioral details beyond what the annotations and schema imply.

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 front-loaded with the core action and scope, then efficiently lists returned fields and adds a short usage cue and endpoint. Every sentence contributes without repetition or 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?

Given the absence of an output schema, the description compensates by naming the main returned fields and clarifying that only active orders are listed. It is nearly complete for a simple no-parameter list tool, though it could mention pagination or result-size 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?

The tool takes zero parameters, and the rule specifies baseline 4 for 0-param tools. The description does not need to explain parameter semantics, so this is appropriately handled.

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 uses a specific verb and resource: 'List the account's active (not yet completed) delivery orders.' It clearly scopes the tool to active, not-yet-completed orders and lists the fields returned, which distinguishes it from singular get_order and broader query_orders 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?

The description gives clear context with 'Good first call' and specifies the active-order scope. It does not explicitly name alternatives such as query_orders or state when not to use this tool, so it falls short of full when/when-not/alternatives 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?

The readOnlyHint annotation already establishes this is a safe read, and the description adds substantive value by naming the exact fields returned and the backing endpoint (GET /carriers). It does not discuss ordering, pagination, or empty-result behavior, but with annotations covering the safety profile this is solid context.

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

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

Two compact sentences: the first front-loads verb, resource, and return fields; the second gives the follow-up handoff. Nothing is padded and no sentence repeats structured data verbatim.

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

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

With no output schema, the description compensates by enumerating the returned fields, which is exactly what an agent needs to plan a downstream assignment. For a zero-parameter read tool with a readOnlyHint, 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?

The tool takes zero parameters, which is the baseline-4 case; the schema is empty and needs no explanation. The description correctly frames the tool as account-wide with no filtering arguments.

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 account's carriers (drivers)') and enumerates the returned fields (id, name, phone, email, isOnShift, isActive, location). No sibling tool lists carriers, so an agent can distinguish it immediately from the order-oriented 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?

The sentence 'Use an id here with shipday_assign_order_to_carrier' gives clear workflow context: this is the discovery step that feeds carrier assignment. It stops short of explicit when-not guidance or naming other alternatives, so it falls just 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 declare readOnlyHint=true, so the safety profile is covered. The description adds real value by disclosing that the response includes a per-service enabled flag, though with no output schema it could say more about the shape of the result (e.g., IDs needed for follow-up calls).

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 tight sentence plus the endpoint reference. Nothing is wasted, and the key detail (services and their enabled state) 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 zero-parameter read tool with annotations and no output schema, the description covers what the tool returns at a high level. It stops short of noting the identifiers an agent would need to chain into shipday_check_on_demand_availability or shipday_get_on_demand_estimate.

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 of 4 applies. The description correctly signals that no filtering arguments are needed, since scope is the whole account.

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 ('List') and a specific resource ('third-party on-demand delivery services') with concrete examples (DoorDash, Uber) and the account scope. It is clearly distinguishable from siblings like shipday_list_carriers and shipday_get_on_demand_details.

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 'available to the account and whether each is enabled' implies the discovery use case, but it never says when to pick this over shipday_check_on_demand_availability or shipday_get_on_demand_details, nor does it state prerequisites. Usage is inferable but not 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 declare readOnlyHint=true, and the description adds real behavioral detail on top: row-based paging with start/end cursors capped at 100 rows per call, newest-first sort order, and the shape of each returned row (timestamps, totals, driver payment, distance, carrier). That return-shape disclosure matters because there is no output schema; only rate limits and empty-result behavior are left out.

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 purpose, then paging semantics, then returned fields, plus the underlying endpoint. It is a single dense sentence carrying a lot of clauses, but nothing is redundant or 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?

All five parameters are described in the schema, no output schema exists yet the description enumerates row contents, and paging is fully explained. The remaining gap is the default scope when no filters are supplied (all-time? newest 100?), which matters given 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 the schema cannot: cursors are ROW indices (1–100, then 101–200) with a 100-row ceiling, which disambiguates against the time-based filters in the same parameter set. It does not clarify how the two time filters combine or what range applies when they are omitted.

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 and resource ('Search delivery orders') and immediately scopes it to historical/completed orders filtered by placement time and status. 'including completed ones' implicitly separates it from the sibling shipday_list_active_orders and shipday_get_delivery_progress, so an agent can pick between them 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: mentioning completed orders and time-window filtering suggests history/audit lookups, but the description never says 'use this when X, use shipday_list_active_orders when Y' and lists no exclusions or prerequisites. The guidance is inferable but not 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 carry readOnlyHint=false and idempotentHint=true, so the safety profile is covered; the description reinforces this with a front-loaded 'WRITE:' tag and clarifies that the flag can be cleared (set to false), not just set. It does not mention auth needs or what gets returned, but the added flag semantics are meaningful.

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 short, front-loaded with 'WRITE:', and every clause (flag semantics, endpoint, default) earns its place. 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?

Given a two-parameter tool with full schema coverage and safety annotations, the description is complete enough for correct invocation. The only minor gap is no hint about response behavior, but for a simple flag-setter this is negligible.

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 (order_id and ready_to_pickup) are already fully documented, including the default of true. The description's 'set or clear' wording is the only extra, so the baseline 3 is appropriate.

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

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

The description states a specific verb (set or clear) and a specific resource (an order's ready-to-pickup flag), plus the underlying Shipday endpoint. The purpose is narrow and unambiguous, and an agent can separate it from its siblings, none of which touch this flag.

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 clarifies the flag's meaning for the driver, which gives useful context on why to call it, but there is no explicit guidance about when-not to call it, prerequisites, or how this interacts with the driver assignment lifecycle. Usage is implied rather than stated.

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

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

The leading 'WRITE:' marker plus the resulting state disclosure tell the agent this is a mutating operation whose effect is to return the order to an unassigned queue. It does not say what happens if the order has no driver assigned or what errors are returned, but the core behavioral effect is covered beyond the readOnlyHint=false annotation.

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

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

Two short sentences with the write nature and effect front-loaded and the endpoint appended as reference detail. Nothing 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 single-parameter mutation with annotations present and no output schema, the definition covers the essential action, target, and end state. Minor gaps remain around failure modes (order already unassigned, invalid id) but nothing blocks 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 schema already explains that order_id is the internal numeric orderId rather than the order number. The description only echoes it via the PUT path template, adding no new semantics, so baseline 3 applies.

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

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

States a specific verb+resource ('remove the driver from a delivery order') and immediately clarifies the resulting state ('goes back to unassigned'). It is clearly distinguishable from the reverse operation shipday_assign_order_to_carrier among the siblings.

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

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

Usage is implied by the outcome ('goes back to unassigned'), so an agent can infer it is for detaching a driver, but there is no explicit when-to-use framing or named alternative (e.g., reassigning via an assign tool instead).

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