OptimoRoute MCP by usefulapi

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

With only destructiveHint=true in annotations, the description carries the real burden and delivers: geocoding behavior, the error condition on duplicate orderNo, and the fact that SYNC replaces all fields with what you send — a concrete data-loss disclosure consistent with the destructive annotation. It does not mention authentication/permission requirements or whether geocoding failures are recoverable beyond the storeInvalid flag.

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

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

Front-loads the operation-mode taxonomy, then the required-field and location rules, then the raw API endpoint. Dense but each sentence carries distinct information; the em-dash clauses make it slightly run-on but 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 32-parameter mutation tool with no output schema and only one required field, the description covers the operation modes, new-order prerequisites, and location representation — the parts an agent must get right. It omits any statement of what the call returns or how failures surface, which is the main remaining gap.

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

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

Schema description coverage is 100%, so the baseline is 3; the description earns above baseline by adding cross-parameter rules the schema cannot express — the three mutually exclusive ways to express a location (existing locationNo alone, an address to geocode, or lat/long + locationName) and the four required fields for new orders. It does not clarify the id-vs-orderNo matching precedence (that detail lives only in 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+resource (create/update one order) and enumerates the four operation modes with their distinct semantics, which is far more than a restatement of the title. It only implicitly distinguishes itself from the sibling `optimoroute_create_or_update_orders` via the phrase 'one order', never naming the batch alternative.

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 per-mode selection guidance: CREATE 'errors if orderNo exists', UPDATE 'existing only', MERGE 'safest for edits', SYNC 'create or REPLACE all fields'. That is genuine when-to-use advice for the operation parameter. It stops short of saying when to prefer this tool over its plural sibling or the read tools.

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

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

Beyond the destructiveHint annotation, it discloses several non-obvious traits: no geocoding is performed, the exact location payload requirements to avoid geocoding/creating a new location, the default match-and-merge behavior (matched by id or orderNo, only sent fields updated, otherwise created), and that the result is a per-order success list. This is substantive behavioral context that the annotations do not carry.

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 sentences, each carrying distinct information (scope, location constraint, default semantics, return shape), with the scope front-loaded. No filler or restatement of the title.

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

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

For a single nested-array parameter with no output schema, the description covers the essential call-time concerns, including what the response contains ('per-order success list'). It could go slightly further on partial-failure behavior or limits, but nothing critical for 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 coverage is 100%, so the baseline is 3. The description still adds value the schema does not state directly: the location payload rule (existing locationNo only, vs. latitude+longitude plus an identifier) and the default merge-vs-create resolution logic when no operation is given.

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 set (create, update, replace), the resource (orders), and the scope (up to 500 in one call). It distinguishes itself from the sibling optimoroute_create_order by explicitly framing itself as the bulk path and deferring per-order operation semantics to that 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?

It clearly establishes the bulk use case (up to 500 orders) and points to optimoroute_create_order as the semantic reference for per-order operations, which effectively routes the agent. It stops short of an explicit 'use this instead of create_order when…' statement, so the selection rule is inferred 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?

It discloses the surprising behavioral trait that the operation is read-only despite issuing a POST, which is exactly the kind of context annotations alone (readOnlyHint=true) don't explain to an agent. It also enumerates returned content, though it doesn't cover pagination 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?

Dense but front-loaded: the resource and scope lead, with the read-only caveat and endpoint suffix trailing. Every clause carries information, though the single long sentence is heavy.

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

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

With no output schema, the description usefully enumerates the returned data (times, positions, POD fields, tracking URL), and the read-only/POST note resolves the main behavioral ambiguity. Only the absence of sibling-routing guidance keeps it from being fully complete.

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 restates the 500-item cap (already maxItems) and that customer feedback is optional (already in the schema), adding little beyond the structured fields – 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 (Get) plus resource (completion status of orders) and enumerates the exact statuses returned, along with the concrete data fields (times, positions, POD data, tracking URL). An agent can distinguish this from optimoroute_get_orders or optimoroute_update_completion_details without opening a schema.

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

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

The description conveys what scenario this serves (checking order completion/POD) and notes the optional feedback toggle, but it never explicitly states when to use this versus siblings like optimoroute_get_orders or the update counterpart. Usage is implied rather than routed.

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, covering the safety profile. The description adds useful context beyond that: it explains what the status answers (sent, when, live) and that route-change counts can be included, which helps the agent understand the return semantics even without an output schema.

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

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

The description is front-loaded with the core question, then adds the optional parameter note and a brief API endpoint. All content is relevant, though the endpoint line is metadata that could be trimmed.

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 read-only tool with no output schema and minimal annotations, the description sufficiently explains what information is retrieved and how to control it via the optional parameters. It does not detail response formatting details, but none are required to invoke 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 both parameters. The description restates the date-omission default and that includeRouteChanges counts added/modified/removed routes, adding only marginal detail beyond the schema's own text; baseline 3 applies.

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

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

The description states a specific resource (dispatch status) and precisely enumerates what is checked: whether routes and customer notifications were sent to drivers, when, and whether they are live. This distinguishes it from planning-focused siblings like get_planning_status and routing-focused ones like get_routes.

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 stated purpose—checking dispatch status—and a default rule is given ('Omit date for the currently live date'). However, there is no explicit when-to-use vs alternatives, no mention of get_planning_status or get_routes, and no 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 only declare readOnlyHint=true, so the description carries the rest and does it well: it discloses the 500-event page cap, the pagination contract (tag → after_tag, remainingEvents), and the important caveat that events can arrive out of order from offline devices. That is real behavioral context an agent cannot infer from structured fields.

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, front-loaded with purpose and event types, then pagination, then the ordering caveat. The event-type list is long but pays for itself by enumerating the return values in the absence of an output schema.

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 naming the returned fields (tag, remainingEvents) and the event types, plus the ordering caveat. An agent has everything needed to call and paginate 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 baseline is 3, but the description adds meaning beyond the schema by explaining the tag's role in the incremental-read loop (returned tag feeds the next call's after_tag). That closes the schema's vague 'tag from a previous call' into an actionable workflow.

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 ('Read driver-app events for the live routes') and enumerates the exact event types it returns. No sibling tool covers event reading, so the distinction from get_routes/get_dispatch_status 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?

Clearly prescribes the usage loop: pass the returned tag as after_tag to fetch only newer events, and check remainingEvents for more. It does not name an alternative tool or state exclusions, but no sibling performs this function, so the routing guidance is effectively complete.

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, and the description adds real behavioral value beyond that: per-result success flags, ERR_ORD_NOT_FOUND instead of a hard failure, and an explicit reconciliation of 'Read-only despite using POST'. It does not mention auth needs, rate limits, or pagination, 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?

Three tight sentences, fully front-loaded: identity and scope first, then per-result error semantics, then the POST/read-only caveat. Every sentence carries distinct 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 must describe returns, and it does: the returned field set, the per-item success flag, and the ERR_ORD_NOT_FOUND behavior. Combined with 100% schema coverage on the single parameter, an agent has everything needed to call 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?

The single 'orders' parameter has 100% schema description coverage, including the {orderNo}/{id} shape and the 500-item cap. The description restates the lookup keys and limit but adds no syntax or format information beyond what the schema already documents, 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?

Names a specific verb (Fetch) and resource (full order data) and enumerates the payload fields returned: location, time windows, assignment, loads, skills, contact. The 'by orderNo or id' key-based lookup implicitly distinguishes it from the sibling search_orders, so an agent can route correctly.

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 clear implied usage: retrieve full records for a specific set of orders (max 500) identified by orderNo or id. However, it never states when to prefer this over sibling alternatives like optimoroute_search_orders or optimoroute_create_or_update_orders, leaving the agent to infer the boundary.

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 the behavioral burden and delivers: it enumerates the status codes (N/R/C/F/E) and mentions percentageComplete. With no output schema, this return-shape disclosure is genuinely useful context, though it says nothing about polling cadence or lifecycle transitions.

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

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

One dense sentence plus a short API endpoint reference. The purpose and status-code legend are front-loaded with no filler, and every clause carries information.

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

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

For a one-parameter read tool with no output schema, the description supplies the missing return-value semantics (status code legend and percentageComplete), which is exactly what an agent needs to interpret results. Nothing essential is omitted.

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 single parameter has 100% schema description coverage and is documented as 'the planningId returned by optimoroute_start_planning'. The description adds no syntax or format detail beyond that, so the schema does the heavy lifting; 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 (check/get) and resource (planning run / route optimization status) and explicitly ties it to the sibling that creates such a run, optimoroute_start_planning. An agent can distinguish this from optimoroute_get_dispatch_status or optimoroute_get_routes 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 by the reference to a run 'started with optimoroute_start_planning', which tells the agent this follows a start call. However, there is no explicit when-to-use/when-not guidance and no mention of alternatives such as stop_planning or how to poll versus wait.

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 covers the safety profile, so the description's added value is the behavioral detail: the polyline is 'large', the ordered stop list carries scheduled times, and dispatch status means 'sent to its driver, and changed since'. That is genuine context beyond the annotation, though pagination, result size caps, and missing-data behavior (e.g. no planned routes for a date) are not addressed.

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 core purpose and return shape, followed by the optional extras and the underlying API endpoint. No filler or repetition of the title.

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

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

With no output schema, the description carries the burden of describing return values, and it does so reasonably well: it names the per-driver/vehicle aggregates and the ordered stop structure with times. What is missing is edge-case behavior (empty result for a date with no plan) and any hint of result volume.

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 seven parameters are already documented in the schema, setting the baseline at 3. The description adds the useful grouping of these as optional filters ('one driver or vehicle') versus optional includes ('encoded polyline, start/end locations and dispatch status'), but adds no format or precedence detail beyond the schema.

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

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

States a specific verb+resource ('Get the planned routes') scoped to 'one date', and enumerates what the result contains (per driver/vehicle: duration, distance, loads, ordered stops with scheduled times). This distinguishes it from sibling read tools like get_orders or get_dispatch_status 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?

The 'for one date' scoping and the optional filter/include flags imply the intended usage, but there is no explicit when-to-use/when-not guidance and no naming of alternatives (e.g. when to prefer get_orders vs get_routes, or get_dispatch_status vs includeDispatchStatus). Adequate but leaves routing to inference.

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

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

The readOnlyHint annotation already establishes this as a safe read. The description adds genuine behavioral context beyond that: the ETA returned is the 'live ETA from the routes sent to drivers', distinguishing dispatched reality from planned data. It does not say what happens when an order is not scheduled (null/empty response) or whether the order lookup is scoped to a workspace, which would be the next useful disclosures.

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 compact segments: the payload question front-loaded, the input instruction, then the endpoint reference. Every sentence carries distinct information with no restatement of the title or name.

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 must convey return semantics, and it does so via the enumerated fields (driver/vehicle, stop number, time, live ETA). For a two-parameter read tool with a readOnly annotation, this is close to complete; only the not-scheduled case is left 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 both parameters carry descriptions, so the baseline is 3. The description's only added value is the phrasing 'Give orderNo or id', which implies the two identifiers are alternative lookup keys, but it does not state precedence when both are supplied or which is preferred.

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 precise verb+resource+payload: whether an order is scheduled, on which driver/vehicle, at which stop number and time, plus the live ETA. That field-level enumeration clearly separates it from list-style siblings like optimoroute_get_orders or optimoroute_search_orders, and from the dispatch-wide optimoroute_get_dispatch_status. It also names the backing endpoint (GET /get_scheduling_info), removing ambiguity about what data source is queried.

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 interrogative framing implies the calling context (checking an individual order's scheduling state), and 'Give orderNo or id' tells the agent which inputs to supply. However, there is no explicit when-to-use guidance, no exclusions, and no pointer to the sibling that answers the complementary question (e.g. optimoroute_get_planning_status or optimoroute_get_dispatch_status). Usage is inferable rather than stated.

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

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

Adds behavioral detail well beyond the readOnlyHint: the 35-day maximum range, a 500-per-page cap, the requirement to reuse identical parameters when paging, and an explicit warning that the operation is read-only despite using POST. The POST caveat reinforces rather than contradicts 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?

Four dense sentences, front-loaded with the primary lookup modes and followed by pagination and the POST/read-only clarification. No filler or repetition.

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

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

No output schema exists, and the description compensates by explaining what comes back (order data and/or scheduling info, plus the after_tag cursor) and how to consume it. For a 6-parameter search tool this is complete enough to invoke 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 carries the baseline. The description still contributes non-schema constraints: the 35-day ceiling on dateRange, the 500-item page size tying to maxItems, and representative status values beyond the enum list.

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

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

States a specific verb and resource ('Find orders') with the two supported lookup modes (date range, orderNo/id list) and the optional status filter. It is clearly distinguishable from mutating siblings, though it never names the closest read siblings (get_orders, get_routes) to sharpen the boundary.

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: a hard 35-day window for date ranges, lookup-by-list as the alternative, optional status narrowing, and the rule for paging ('pass the returned after_tag with the SAME other parameters'). No explicit when-not or sibling routing guidance is offered.

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 supply destructiveHint=true, so the description adds real value: irreversibility, the live-route side effect, the deliberate default inversion versus OptimoRoute's own API default, and the ERR_NOTHING_TO_SEND error condition. It does not mention auth/permission requirements or what a successful response contains, so not quite a 5.

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

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

Front-loads the action and the irreversibility warning, then appends the parameter caveat, error code, and verification tool. Four compact sentences, none 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?

With no output schema, the description still discloses the failure mode (ERR_NOTHING_TO_SEND) and the recommended confirmation path. For a two-parameter destructive dispatch tool, 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 already 100%, so the baseline is 3, but the description adds meaningful semantics the schema cannot: that sendNotifications defaults to FALSE in this wrapper even though the underlying API defaults to true, plus the Order Tracking settings that govern it. That override nuance is genuinely useful.

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 ('Dispatch the routes for a date to the drivers' mobile app') and anchors it to the equivalent UI action ('the web app's Send Routes'), which lets an agent distinguish it from read-only siblings like optimoroute_get_routes or optimoroute_get_dispatch_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 scopes when to use it (dispatch a date's routes), warns 'CANNOT be unsent', gives the condition for setting sendNotifications true, and routes the agent to optimoroute_get_dispatch_status for confirmation. This covers when-to-use, the irreversibility caveat, and the verification alternative.

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 destructiveHint=true; the description goes further by naming exactly what is destroyed (existing routes for that date are REPLACED under the default) and by disclosing the asynchronous contract (returns a planningId that must be polled). It does not mention permission/plan-gating beyond 'if the plan allows', which is a minor gap for a mutation 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?

Three dense sentences with zero filler, front-loaded with the destructive default before the alternative and the lifecycle. Every clause carries operational information.

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

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

For a 14-parameter async mutation with no output schema, the description covers the essential missing pieces: the return value (planningId), the polling path, and the cancellation path. It does not explain the async failure/timeout behavior, but the core call-correctness information is present.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds meaningful cross-parameter semantics: the startWith/lockType interaction and the destructive consequence of the EMPTY default, which the schema documents only as isolated enum values. It leaves the other twelve parameters to the schema, which is acceptable given full coverage.

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 precise verb+resource ('Start OptimoRoute's route optimization') with the scope ('for a date (or a dateRange for weekly planning, if the plan allows)'). It is immediately distinguishable from siblings like optimoroute_stop_planning and optimoroute_get_planning_status, which it names directly.

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

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

Gives explicit when/when-not guidance: default startWith EMPTY replaces existing routes, while startWith CURRENT (+ lockType) keeps them. It also names the follow-up alternatives (get_planning_status to poll, get_routes to read, stop_planning to cancel), so the agent knows the full operational sequence.

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, so the agent knows this cancels something. The description confirms the effect (stops a running process) and adds the endpoint context, but omits material behavior: whether the stop is immediate, whether partially produced routes/results survive, and error behavior when no planning is active.

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, front-loaded sentences with no filler. The trailing 'OptimoRoute: POST /stop_planning' is somewhat redundant against the name/title, but it is brief and gives API-level context at negligible 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?

For a one-parameter mutation with no output schema and a destructive annotation already present, the description covers what the tool does and its key input. Only secondary details – post-stop state and idempotency/error behavior – are missing, which is mild for a tool this simple.

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

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

Schema coverage is 100% and the single parameter's description already explains that planningId comes from optimoroute_start_planning. The description only restates 'by its planningId', adding no format, range, or sourcing detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (Stop) and resource (a running planning/optimization process) and identifies the key (planningId). It is clearly the counterpart to start_planning, though it never explicitly names that sibling as the pivot point.

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 'Stop a running planning process' – an agent can infer it is used to cancel an in-flight optimization. However, there is no explicit when-to-use/when-not guidance, no mention of the start_planning alternative, and no note on what to do if no planning is running.

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 supply destructiveHint=true, so the description carries most of the behavioral load and does so well: it discloses the 500-order batch cap, that the change is reversible, and that the response is a per-order success list. It does not mention auth requirements or partial-failure 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?

Three tight sentences with the core action, batch limit and reversibility front-loaded. The trailing 'OptimoRoute: POST /update_completion_details.' is endpoint metadata of marginal value to an agent but not damaging.

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 stating the return is a per-order success list, and it covers the cap, reversibility and timestamp formats. Auth and error/partial-failure semantics remain unstated, but nothing essential to invoking the tool 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 schema already documents id, orderNo, status enum and the three time encodings; the description only reinforces that each time accepts unixTimestamp, utcTime or localTime. Useful confirmation but nothing the schema does not already convey, 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 and resource ('Set the completion status of up to 500 orders') with concrete examples of the statuses applied, and the write verb plus the batch ceiling clearly separates it from the read-side sibling optimoroute_get_completion_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?

Gives clear context for when this is used ('mark success, failed or cancelled from an external system') and notes the operation is reversible by re-setting the status. It does not name exclusions or explicitly route to alternatives such as optimoroute_get_completion_details, so it stops short of the top band.

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 destructiveHint=true; the description goes well beyond that by naming the destructive consequence (existing route for that driver/date is UNSCHEDULED), the required follow-up workflow (re-run planning), and a hidden scope effect (start/end locations also apply to future optimizations). This is exactly the extra context annotations cannot convey, and it is consistent with destructiveHint.

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 change scope, then the warning, then the upstream endpoint. Efficient and zero filler, though the trailing 'OptimoRoute: POST /update_driver_parameters' is largely redundant with the name and adds little an agent can act on.

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 16-parameter mutation with no output schema, it covers the dangerous side effects and the follow-up action, which are the highest-risk gaps. It does not state partial-update semantics (whether omitted fields are preserved or cleared), which is the one behavior an agent still has to guess at.

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

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

Schema description coverage is 100%, so every parameter is already documented in the schema, including format patterns and coordinate pairing requirements. The description's field list largely restates those parameters without adding syntax or defaults, 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 ('Change one driver's setup for one date') and enumerates the concrete fields affected: enable/disable, work hours, assigned vehicle, capacities, start/end location. No sibling tool targets driver parameters, so the agent can route here unambiguously.

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 enumerated fields and the post-change instruction to re-run planning, but there is no explicit when-to-use/when-not or named alternative. For a tool whose scope is narrow and unopposed by siblings, this is adequate but not instructive.

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