Check OptimoRoute routes, orders and driver events, and create orders or start route planning.
Scored across 15 tools
Most tools have clearly distinct scopes, but get_orders and search_orders overlap because both can retrieve orders by orderNo/id. Similarly, create_order and create_or_update_orders require careful reading to distinguish single-order versus bulk semantics.
Every tool uses the same optimoroute_ prefix and snake_case verb_noun pattern (create_order, get_orders, update_completion_details). This is highly consistent and predictable.
15 tools is well-scoped for an OptimoRoute integration, covering order management, planning, dispatch, and completion without obvious filler. Each tool appears to earn its place.
The set covers the core order lifecycle, route planning, dispatch, and completion tracking, plus driver parameters. Minor gaps exist, such as no explicit delete_order or read-only endpoints for drivers, vehicles, or locations.
Create one order, or update an existing one, with address geocoding. operation: CREATE (new; errors if orderNo exists), UPDATE (existing only), MERGE (create or update only the fields you send — safest for edits), SYNC (create or REPLACE all fields with what you send). CREATE/SYNC/MERGE of a new order need date, type, location and orderNo or id. A location is either an existing locationNo alone, an address to geocode, or latitude+longitude+locationName. OptimoRoute: POST /create_order.
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | OptimoRoute's order id. Takes priority over orderNo when matching. | |
| date | No | Order date, YYYY-MM-DD. | |
| type | No | D = delivery, P = pickup, T = task. | |
| No | Customer email for notifications. | ||
| load1 | No | Load units #1 (boxes, kg, ...) per your capacity setup. | |
| load2 | No | Load units #2. | |
| load3 | No | Load units #3. | |
| load4 | No | Load units #4. | |
| notes | No | Notes for the driver's instructions. | |
| phone | No | Customer phone number. | |
| skills | No | Required driver skill codes. | |
| orderNo | No | Your order number, shown in the web app. Used to match existing orders. | |
| duration | No | Service time at the location, in minutes. | |
| location | No | Where the order is serviced. | |
| priority | No | L low, M medium (default), H high, C critical. | |
| operation | Yes | How to apply the order (see description). | |
| relatedId | No | id of a related pickup/delivery. | |
| assignedTo | No | Force the order onto one driver, e.g. {"serial": "102"} or {"externalId": "444"}. null clears it. | |
| timeWindows | No | When the order can be serviced, e.g. [{"twFrom": "10:00", "twTo": "14:00"}]. | |
| allowedDates | No | Restrict the dates the order may be scheduled, e.g. {"from": "2026-10-01", "to": "2026-10-07"}. | |
| customField1 | No | Legacy custom field #1. | |
| customField2 | No | Legacy custom field #2. | |
| customField3 | No | Legacy custom field #3. | |
| customField4 | No | Legacy custom field #4. | |
| customField5 | No | Legacy custom field #5. | |
| customFields | No | New-style custom fields keyed by the field key configured in OptimoRoute. | |
| relatedOrderNo | No | orderNo of a related pickup/delivery (set on the second order of the pair). | |
| allowedWeekdays | No | Weekdays the order may be scheduled on. Default: all. | |
| vehicleFeatures | No | Required vehicle feature codes. | |
| allowedDateTimes | No | Datetime windows in which the service may begin. | |
| acceptDuplicateOrderNo | No | Allow CREATE of an order whose orderNo already exists. | |
| notificationPreference | No | How order-tracking notifications are delivered for this order. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare destructiveHint=true; the description adds real behavioral content — CREATE errors on an existing orderNo, SYNC replaces all fields, MERGE touches only sent fields, geocoding is attempted for addresses, and location can be an existing locationNo or coordinates. It does not mention idempotency, rate limits, or auth requirements, but it is consistent with (not contradicting) the destructive hint.
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 operation-mode semantics, which is the highest-value information, and each sentence addresses a decision the caller must make. It is dense but not padded; only the endpoint note ('POST /create_order') feels like filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 32-parameter mutation tool with only destructiveHint=true as annotation coverage and no output schema, the description covers mode semantics and required fields well. It omits when to prefer the bulk sibling, error/partial-failure behavior beyond duplicates, and return shape, leaving gaps an agent may hit on first use.
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% across 32 parameters, so the schema already carries the per-field semantics (including the locationNo-only rule that the description restates). The description adds only the cross-cutting required-field rule for CREATE/SYNC/MERGE of a new order, which is a modest increment over the structured fields.
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 ('Create one order, or update an existing one, with address geocoding') and enumerates the four operation modes, which is genuinely informative. However it never distinguishes this tool from its obvious sibling optimoroute_create_or_update_orders (plural/bulk), so an agent cannot tell the two apart from the description alone.
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 gives in-tool guidance on which operation to pick ('UPDATE (existing only)', 'MERGE — safest for edits', 'SYNC (create or REPLACE all fields)') and states required fields per mode, which is useful. It offers no guidance on when to reach for this tool versus the plural sibling or the read/planning siblings, so the alternative-selection gap is unaddressed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create, update or replace up to 500 orders in one call. No geocoding here: each location must be an existing locationNo or carry latitude+longitude (+ locationNo, address or locationName). Per order, operation MERGE/SYNC/CREATE/UPDATE works as in optimoroute_create_order; by default an order matched by id or orderNo is updated with only the fields sent, otherwise created. Returns a per-order success list. OptimoRoute: POST /create_or_update_orders.
| Name | Required | Description | Default |
|---|---|---|---|
| orders | Yes | The orders, at most 500. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With destructiveHint=true already declared, the description still adds real behavioral content: the 500-order cap, the no-geocoding constraint requiring existing locationNo or lat/long, the merge-default that only sent fields are updated, and the per-order success list return shape. It does not disclose partial-failure semantics (whether a bad order aborts the batch).
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 tightly packed sentences, each carrying distinct information (scope, location constraint, operation/matching behavior, return shape, endpoint). No filler and the batch constraint 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 destructive bulk mutation with no output schema, the description covers scope, matching, partial-update semantics, and return format. The main remaining gap is failure handling on partially invalid batches, which matters given destructiveHint=true.
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 top-level parameter is fully documented in the schema (100% coverage), so the baseline is 3. The description adds meaning beyond the schema by explaining the location requirement and the id-vs-orderNo matching priority that governs how each element is interpreted.
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 set (create/update/replace), the resource (orders), and the bulk scope (up to 500 in one call). It also names the sibling optimoroute_create_order as the reference for single-order operation semantics, so an agent can place it without opening schemas.
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: use this for batch work, and it explicitly routes the per-order MERGE/SYNC/CREATE/UPDATE semantics to optimoroute_create_order rather than duplicating them. It also states the default matching behavior (id/orderNo, partial update vs create). It stops short of an explicit 'use this instead of X when Y' routing statement against the single-order tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the completion status of up to 500 orders (unscheduled, scheduled, on_route, servicing, success, failed, rejected, cancelled) with service start/end times and positions, proof-of-delivery form data (notes, signature and photo URLs, barcodes), the tracking URL and optionally customer feedback. Read-only despite using POST. OptimoRoute: POST /get_completion_details.
| Name | Required | Description | Default |
|---|---|---|---|
| orders | Yes | Orders to target, each {"orderNo": "..."} or {"id": "..."}. At most 500. | |
| includeCustomerFeedback | No | Include the customer's rating and comment, if customer feedback is configured. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes beyond the readOnlyHint annotation by warning 'Read-only despite using POST,' which disarms the natural assumption that POST mutates data, and by capping the request at 500 orders. It does not mention rate limits or error behavior, but the key behavioral surprise is disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single dense sentence front-loads the core action and packs statuses, payload, and the POST caveat without filler. It is long, but nearly every clause carries distinct information, so little 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 carries the return-value burden itself and does so by listing service times, positions, POD form data, tracking URL, and optional feedback. Combined with the 500-order cap, an agent has everything needed to invoke and interpret the call.
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 description need not document the two parameters, and it correctly does not. It loosely mirrors the optional feedback flag ('optionally customer feedback') but adds no syntax or semantics beyond what the schema already states, 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') and resource ('completion status of orders') and enumerates the exact status values returned along with the payload contents (times, positions, POD data, tracking URL). This clearly separates it from siblings like get_orders or get_events that return other data.
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 purpose implies when to call it (after orders have been serviced), but there is no explicit when-to-use guidance or named alternative for related queries. The sibling update_completion_details is the obvious counterpart and is never referenced, so routing between reading and writing completion details is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Have the routes (and customer notifications) for a date been sent to drivers, when, and are they the live routes? Optionally counts routes added, modified or removed since sending. Omit date for the currently live date. OptimoRoute: GET /get_dispatch_status.
| Name | Required | Description | Default |
|---|---|---|---|
| date | No | Date to check, YYYY-MM-DD. Omit for the live routes' date. | |
| includeRouteChanges | No | Include counts of routes changed since sending. |
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 meaningful behavioral context: it explains that the tool reports whether routes/notifications have been sent, when, and whether they are live, plus optional counts of added/modified/removed routes. It does not detail response granularity or pagination, but adds value 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?
The description front-loads the core question and then gives parameter guidance, ending with an API reference. Every sentence earns its place; there is no filler. It is appropriately sized for a two-parameter read-only status tool.
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, but the description explains what status outcomes are returned (sent, when, live-route status, optional change counts). Combined with annotations covering read-only safety and schema covering all parameters, it is nearly complete, though response format or pagination details are absent.
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 adds meaning beyond the schema by specifying that includeRouteChanges counts routes added, modified, or removed (schema says only 'changed') and reinforces omitting date for the live date. This nuance helps the agent understand the parameter’s effect.
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 resource (dispatch status of routes and customer notifications) and the exact questions it answers: sent status, timing, live-route status, and optional change counts. It distinguishes itself from planning/route siblings by focusing on what has been dispatched to drivers, though it does not name alternatives 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 usage guidance for the date parameter (omit for live date) and the optional change counts, but does not state when to choose this over get_planning_status or get_routes. The usage is implied by the status-check purpose rather than explicitly contrasted with siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read driver-app events for the live routes — on_duty, off_duty, start_route, end_route, start_service, success, failed, rejected, start_time_changed — up to 500 per call. Pass the returned tag as after_tag next time to get only newer events; remainingEvents says whether more are waiting. Events can arrive out of order when devices were offline. OptimoRoute: GET /get_events.
| Name | Required | Description | Default |
|---|---|---|---|
| after_tag | No | The tag from a previous call; omit to read from the start. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond readOnlyHint=true, the description discloses the 500-per-call cap, the incremental-fetch tag contract, the remainingEvents indicator, and the important caveat that events can arrive out of order when devices were offline. That ordering caveat is behavioral context an agent cannot get from annotations or schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core purpose, then pagination, then the ordering caveat, with the API endpoint tacked on. Dense but nearly every clause carries information; the long event-type enumeration is the only slightly padded element.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, yet the description covers the return contract (tag to reuse, remainingEvents flag) and the ordering caveat, so an agent has everything needed for correct repeated invocation of this read 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% and only one parameter exists, so the baseline is 3. The description adds genuine meaning by explaining that after_tag should be the tag returned from the previous call and that it filters to newer events only — richer than the schema's terse 'tag from a previous call'.
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 ('Read driver-app events for the live routes') and enumerates the exact event types returned, which distinguishes it from the order- and route-centric siblings. An agent can tell immediately this is the event-log reader.
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 explains the pagination workflow (pass the returned tag as after_tag to get only newer events), which is usage guidance for a repeat caller, but it never states when to prefer this tool over siblings like get_routes or get_dispatch_status. Usage is implied rather than framed against alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch full order data (location, time windows, assignment, loads, skills, contact) for up to 500 orders by orderNo or id. Each result has its own success flag; missing orders come back with ERR_ORD_NOT_FOUND rather than failing the call. Read-only despite using POST. OptimoRoute: POST /get_orders.
| Name | Required | Description | Default |
|---|---|---|---|
| orders | Yes | Orders to target, each {"orderNo": "..."} or {"id": "..."}. At most 500. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the readOnlyHint annotation by explaining that a POST is used for a read-only call, that results are per-item with individual success flags, and that missing orders return ERR_ORD_NOT_FOUND instead of failing the whole call. That partial-failure contract is exactly the kind of behavior an agent cannot get from the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, front-loaded with what is fetched and how, then the failure semantics, then the endpoint mapping. Every sentence carries unique information; nothing is restated from the schema or annotations.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description compensates by describing the per-result success flag and the not-found error code. Combined with the batch limit, identification keys, and endpoint mapping, an agent has everything needed to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and there is only one array parameter, so the baseline is 3. The description still adds value by restating that orders may be targeted by either orderNo or id and by surfacing the 500-item cap prominently in prose.
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 (fetch) and resource (full order data) plus the exact fields returned (location, time windows, assignment, loads, skills, contact) and the identification keys. This clearly separates it from sibling optimoroute_search_orders, which would be the discovery-oriented counterpart.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage (you already have orderNo/id values and want full order detail) but never states when to use this instead of optimoroute_search_orders or optimoroute_get_routes. No prerequisites or exclusions are spelled out, leaving the agent to infer the routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check a planning (route optimization) run started with optimoroute_start_planning: status N new, R running, C cancelled, F finished, E error, plus percentageComplete. OptimoRoute: GET /get_planning_status.
| Name | Required | Description | Default |
|---|---|---|---|
| planningId | Yes | The planningId returned by optimoroute_start_planning. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already establishes that this is a safe, non-mutating read. The description adds useful behavioral detail beyond the annotation by explaining that the response includes status codes N, R, C, F, E and a percentageComplete field, and by naming the underlying OptimoRoute endpoint GET /get_planning_status.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single tightly structured sentence followed by the API endpoint. It front-loads the purpose and status codes with no redundant or wasted wording.
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 status-check tool with one required parameter, no output schema, and annotations covering safety, the description is complete enough. It identifies the source of the planningId, explains the returned status codes and percentageComplete, and names the endpoint.
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 planningId is already documented as the value returned by optimoroute_start_planning. The description reinforces that the ID comes from a planning run started with optimoroute_start_planning, but adds no format, range, or constraint details 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 states a specific verb (Check) and resource (planning / route optimization run), and explicitly ties it to the sibling tool optimoroute_start_planning. It also enumerates the exact status values (N, R, C, F, E) and percentageComplete, making the purpose 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?
The description clearly indicates the tool is used to check a planning run started with optimoroute_start_planning, giving the key usage context. It does not explicitly state when-not to use it or mention alternative tools such as optimoroute_stop_planning, so it falls short of full guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the planned routes for one date: per driver/vehicle the duration, distance, loads and the ordered list of stops with scheduled times. Optionally filter to one driver or vehicle and include the encoded polyline, start/end locations and dispatch status. OptimoRoute: GET /get_routes.
| Name | Required | Description | Default |
|---|---|---|---|
| date | Yes | Date in YYYY-MM-DD format, e.g. 2026-09-30. | |
| driverSerial | No | Only this driver's route (serial number). | |
| driverExternalId | No | Only this driver's route (external id). | |
| vehicleRegistration | No | Only this vehicle's route. | |
| includeRoutePolyline | No | Include the encoded route polyline (large). | |
| includeRouteStartEnd | No | Include each route's start and end locations. | |
| includeDispatchStatus | No | Include whether each route was sent to its driver, and changed since. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already establishes this is a safe read. The description adds useful behavioral context by noting the polyline is large and that dispatch status reveals whether a route was sent and changed since, but it omits pagination, rate limits, or behavior for dates with no planned routes.
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 a short endpoint reference; the return contents and filtering options are front-loaded with no padding. The trailing 'OptimoRoute: GET /get_routes.' is low-value but harmless.
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 returns and does so concretely (per-driver/vehicle metrics plus ordered stops and scheduled times). Coverage is good for a 7-parameter read tool, though pagination and empty-result behavior are unstated.
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 and the baseline is 3. The description groups the parameters into filters (driver/vehicle) versus include-toggles (polyline, start/end, dispatch status), which clarifies intent but adds no format or constraint 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 (Get) and resource (planned routes) scoped to one date, and enumerates exactly what comes back (duration, distance, loads, ordered stops with scheduled times). This distinguishes it from siblings like optimoroute_get_dispatch_status or optimoroute_get_orders without needing 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 single-date scope and optional driver/vehicle filtering imply when the tool is appropriate, but there is no explicit when-to-use guidance or named alternative. An agent must infer the boundary against tools such as get_dispatch_status or get_completion_details that overlap on route data.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Is this order scheduled, and if so on which driver/vehicle, at which stop number and time, plus the live ETA from the routes sent to drivers. Give orderNo or id. OptimoRoute: GET /get_scheduling_info.
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | OptimoRoute's unique order id. | |
| orderNo | No | The user-specified order number. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
readOnlyHint=true already establishes this is a safe read, so the bar is lower. The description adds that the ETA is 'live' and sourced 'from the routes sent to drivers', which is useful freshness context, but says nothing about behavior when the order is unknown or not yet scheduled.
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 returned content in one tight sentence, zero fluff. The trailing 'OptimoRoute: GET /get_scheduling_info.' restates the endpoint and is minor waste, but does not bury the substance.
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, so the description must describe returns, and it does so concretely (driver/vehicle, stop number, time, live ETA) including the negative case of the order not being scheduled. Enough for a two-optional-parameter read tool whose safety profile is covered by annotations.
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 parameters are already documented there, so the schema carries the load. 'Give orderNo or id' usefully signals that either identifier works (consistent with zero required params), 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 retrieval (scheduling info for one order) and enumerates exactly what comes back: scheduled status, driver/vehicle, stop number, time, and live ETA. That enumeration distinguishes it from siblings like get_dispatch_status, get_planning_status, and get_routes without needing to name them.
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 frames the use case as the question an agent would ask ('Is this order scheduled...') and tells it to supply orderNo or id, so usage is implied but never contrasted with alternatives such as get_planning_status or get_dispatch_status. No when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find orders in a date range (at most 35 days) or by a list of orderNo/id, optionally filtered by status (e.g. failed, rejected, unscheduled), with order data and/or scheduling info. Up to 500 per page; pass the returned after_tag with the SAME other parameters to get the next page. Read-only despite using POST. OptimoRoute: POST /search_orders.
| Name | Required | Description | Default |
|---|---|---|---|
| orders | No | Orders to target, each {"orderNo": "..."} or {"id": "..."}. At most 500. | |
| after_tag | No | Cursor from the previous page's after_tag. | |
| dateRange | No | A date range, e.g. {"from": "2026-09-28", "to": "2026-10-02"}. | |
| orderStatus | No | Only orders in these statuses. | |
| includeOrderData | No | Include each order's full data. | |
| includeScheduleInformation | No | Include each order's driver, stop number and scheduled time. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, but the description adds substantial behavioral context: 'Read-only despite using POST', pagination mechanics (pass after_tag with the SAME other parameters), a 35-day maximum date range, and a 500-per-page limit. This is rich 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?
The description is front-loaded with the primary search conditions, then covers pagination, a behavioral caveat, and the endpoint. It is dense but every sentence or clause provides 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?
For a complex 6-parameter tool with nested objects and no output schema, the description covers the date range cap, pagination, return include flags, and the read-only nature. It misses whether dateRange and orders are mutually exclusive or whether one is required, so it is strong but not 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 the baseline is 3. The description adds the 35-day date-range cap and the pagination cursor reuse rule, which are not fully captured in the schema, but it does not elaborate on each parameter's individual meaning beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Find') and resource ('orders'), with clear scope: date range or list of orderNo/id, optional status filter. It does not explicitly name or differentiate from sibling tools like get_orders, so it falls just short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives clear context for when to use the tool (find orders in a date range or by a list, optionally filtered by status). However, it does not mention when not to use it or point to an alternative sibling such as get_orders, so it stops short of explicit alternative guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Dispatch the routes for a date to the drivers' mobile app (the web app's Send Routes). This makes that date the live routes and CANNOT be unsent. sendNotifications defaults to FALSE here (OptimoRoute's own default is true); set it true only when you mean to email/SMS customers per the account's Order Tracking settings. Returns ERR_NOTHING_TO_SEND if nothing changed since the last send. Confirm with optimoroute_get_dispatch_status. OptimoRoute: POST /send_routes.
| Name | Required | Description | Default |
|---|---|---|---|
| date | Yes | Date in YYYY-MM-DD format, e.g. 2026-09-30. | |
| sendNotifications | No | Also send customer notifications. Default false in this tool. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the destructiveHint annotation by naming the exact consequence ('This makes that date the live routes and CANNOT be unsent'), disclosing a per-tool default that diverges from the vendor default, and documenting the ERR_NOTHING_TO_SEND failure mode. These are precisely the operational traits an agent needs before committing a destructive dispatch.
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, then the irreversible consequence, then the default divergence, the error case, and the verification step — each sentence carries new, actionable 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?
For a two-parameter destructive mutation with no output schema, the description covers the effect, irreversibility, parameter default trap, error code, and the sibling used to verify success. Nothing an agent needs to invoke it safely is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds real meaning the schema lacks: the contrast between this tool's false default and OptimoRoute's own true default, plus the consequence of flipping it (email/SMS per Order Tracking settings). The date parameter's meaning is left to the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Dispatch the routes for a date to the drivers' mobile app') and anchors it to a known UI action ('the web app's Send Routes'). An agent can immediately distinguish this from read-side 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 frames when to use it (dispatch a date's routes), when to deviate from the default ('set it true only when you mean to email/SMS customers'), and routes the agent to the follow-up check ('Confirm with optimoroute_get_dispatch_status'). The irreversibility statement also functions as a strong pre-condition warning.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Start OptimoRoute's route optimization for a date (or a dateRange for weekly planning, if the plan allows). With the default startWith EMPTY, existing routes for that date are REPLACED; use startWith CURRENT (+ lockType) to keep them. Returns a planningId — poll it with optimoroute_get_planning_status, then read the result with optimoroute_get_routes. Can be cancelled with optimoroute_stop_planning. OptimoRoute: POST /start_planning.
| Name | Required | Description | Default |
|---|---|---|---|
| date | No | Date to plan, YYYY-MM-DD. Ignored if dateRange is set. | |
| lockType | No | With CURRENT: NONE allow changes; ROUTES keep planned routes; RESOURCES keep driver per order. | |
| balanceBy | No | Balance by WT working time or NUM order count. | |
| balancing | No | OFF best routes; ON balance workload; ON_FORCE balance and use every driver. | |
| dateRange | No | Plan several days at once (weekly planning). | |
| startWith | No | EMPTY (default) plans from scratch; CURRENT starts from existing routes. | |
| clustering | No | Minimize overlap between drivers' routes. | |
| depotTrips | No | Let drivers return to the depot to reload. | |
| useDrivers | No | Only plan with these drivers. Default: all available drivers. | |
| balancingFactor | No | 0.0-1.0, how much balancing outweighs route cost (ON_FORCE only). | |
| useOrderObjects | No | Only plan these orders. Default: all valid orders on the date. | |
| depotVisitDuration | No | Minutes spent at a depot visit. | |
| midRouteDepotVisits | No | Allow mid-route depot visits (needs Dynamic Mid-Route Depots on the account). | |
| includeScheduledOrders | No | When planning a subset, keep other orders already scheduled on those drivers (default true). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only carry destructiveHint=true; the description supplies the operative detail the annotation cannot - exactly what is destroyed (existing routes for the date) and the parameter combination that prevents it. It also discloses the async contract (returns a planningId to poll) and the cancellation path, which is behavior an agent needs before invoking.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Five tight sentences, each carrying distinct load: scope, destructive default and its mitigation, async return contract, lifecycle routing, and the API endpoint. The highest-stakes constraint (replacement of routes) 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 14-parameter, nested-object, no-output-schema tool, the description covers the points an agent cannot infer: destructive default, preservation path, async polling flow, and downstream/cleanup tools. Remaining parameter nuance is fully documented in the schema, so nothing critical 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%, so the baseline is 3, but the description adds cross-parameter semantics the schema does not: the interaction between startWith and lockType (CURRENT + lockType to preserve routes). That is genuinely more than the per-field schema text, though it covers only a subset of the 14 parameters.
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 ('Start OptimoRoute's route optimization for a date') with the exact scope (single date vs dateRange for weekly planning). Clearly distinguishable from siblings like get_planning_status, get_routes, and stop_planning, which it names as part of the lifecycle.
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 tells the agent when the destructive default applies ('startWith EMPTY, existing routes for that date are REPLACED') and how to avoid it ('use startWith CURRENT (+ lockType) to keep them'). It also routes the agent through the full workflow: poll with get_planning_status, read with get_routes, cancel with stop_planning.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Stop a running planning (optimization) process by its planningId. OptimoRoute: POST /stop_planning.
| Name | Required | Description | Default |
|---|---|---|---|
| planningId | Yes | The planningId returned by optimoroute_start_planning. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, so the safety profile is covered. The description adds that the process must be 'running' and that planningId comes from start_planning, but it says nothing about whether stopping is reversible, whether results are discarded, what errors occur for an unknown/completed ID, or what is returned.
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 action and scoping constraint front-loaded and the API endpoint mapping trailing. 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 one-parameter command tool with annotations covering destructiveness and no output schema, the definition has what an agent needs to invoke it correctly. Minor gaps remain around post-stop state and error conditions, but nothing essential 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 single parameter is already documented as 'The planningId returned by optimoroute_start_planning.' The description only restates that the ID identifies the planning, adding no format, type, or edge-case 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 and resource ('Stop a running planning (optimization) process') plus the identifying parameter, so the action is unambiguous. It does not explicitly contrast itself with the sibling optimoroute_start_planning or get_planning_status, but the verb does the differentiating work indirectly.
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 'running planning process' — an agent can infer this is only for in-flight optimizations. However, there is no explicit when-to-use, no mention of what to do if the planning already finished, and no named alternative or prerequisite beyond the planningId reference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set the completion status of up to 500 orders (e.g. mark success, failed or cancelled from an external system), optionally with service start/end times. Each time takes unixTimestamp, utcTime or localTime. Reversible by setting the status again. Returns a per-order success list. OptimoRoute: POST /update_completion_details.
| Name | Required | Description | Default |
|---|---|---|---|
| updates | Yes | The status updates, at most 500. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the destructiveHint annotation, it discloses the 500-order cap, that the operation is reversible by re-setting the status (directly mitigating the destructive flag), and that a per-order success list is returned. These are meaningful behavioral facts an agent would not otherwise know.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four compact sentences: purpose, timestamps, reversibility, return, endpoint. Scoping and the batch limit are front-loaded, 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?
For a single-parameter batch mutation with no output schema, it covers the important operational facts (cap, reversibility, time formats, return shape). It could say more about partial-failure handling in the returned success list, but nothing critical 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%, so the enum statuses and the unixTimestamp/utcTime/localTime variants are already fully documented in the schema. The description's restatement of the time formats adds little beyond what the structured fields provide, 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 ('Set the completion status of up to 500 orders') and clarifies the batch scope plus the external-system use case. An agent can distinguish it immediately 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?
The phrase 'from an external system' hints at the scenario (pushing status back from outside OptimoRoute), but there is no explicit when-to-use vs. when-not guidance and no sibling is named as an alternative. 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.
Change one driver's setup for one date: enable/disable, work hours, assigned vehicle, vehicle capacities, start/end location. WARNING: any existing route for that driver on that date is UNSCHEDULED; re-run planning afterwards. Start/end locations also apply to future optimizations. OptimoRoute: POST /update_driver_parameters.
| Name | Required | Description | Default |
|---|---|---|---|
| date | Yes | Date in YYYY-MM-DD format, e.g. 2026-09-30. | |
| enabled | No | Enable or disable the driver for this date. | |
| endAddress | No | End address shown on reports (needs end coordinates). | |
| externalId | Yes | The driver's external id from driver administration. | |
| workTimeTo | No | Work end, 24-hour HH:MM. | |
| endLatitude | No | End location latitude (needs endLongitude). | |
| endLongitude | No | End location longitude (needs endLatitude). | |
| startAddress | No | Start address shown on reports (needs start coordinates). | |
| workTimeFrom | No | Work start, 24-hour HH:MM. | |
| startLatitude | No | Start location latitude (needs startLongitude). | |
| startLongitude | No | Start location longitude (needs startLatitude). | |
| assignedVehicle | No | External id of the vehicle to assign for this date. | |
| vehicleCapacity1 | No | Vehicle load capacity #1 for this date. | |
| vehicleCapacity2 | No | Vehicle load capacity #2. | |
| vehicleCapacity3 | No | Vehicle load capacity #3. | |
| vehicleCapacity4 | No | Vehicle load capacity #4. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only flag destructiveHint=true; the description goes well beyond by disclosing the concrete destructive consequence (existing routes for that driver/date are UNSCHEDULED) and the required follow-up action (re-run planning). It also reveals non-obvious persistence behavior: start/end locations carry over to future optimizations.
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 of scope, one capitalized warning, one persistence note, one API path reference. The destructive warning is front-loaded and nothing is padded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 16-parameter destructive mutation with no output schema, the safety and follow-up consequences are covered well. The remaining gap is that it never says whether omitted optional fields are left unchanged or cleared, which matters for a partial-update tool with this many 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 is 3, but the description adds a semantic layer the schema cannot: start/end locations have lasting effect on future optimizations. It otherwise groups the editable fields at the same granularity the schema already documents.
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 with scope: changing ONE driver's setup for ONE date, then enumerates the exact facets (enable/disable, work hours, vehicle, capacities, start/end location). The sibling list is dominated by order/route tools, so this driver-scoped update is unambiguously distinguishable.
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 single-driver/single-date framing makes the usage context clear, and it explicitly tells the agent to re-run planning after the update. It does not name an alternative tool for the multi-driver or bulk case, so it falls short of full when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
optimoroute_create_or_update_ordersoptimoroute_create_orderoptimoroute_get_completion_detailsoptimoroute_get_dispatch_statusoptimoroute_get_eventsoptimoroute_get_ordersoptimoroute_get_planning_statusoptimoroute_get_routesoptimoroute_get_scheduling_infooptimoroute_search_ordersoptimoroute_send_routesoptimoroute_start_planningoptimoroute_stop_planningoptimoroute_update_completion_detailsoptimoroute_update_driver_parametersImport orders, manage your fleet, and generate optimized last-mile delivery routes at scale.
Route optimisation, orders, booking and fleet management for a SmartRoutes depot.
Check classes, attendance, customers, memberships and invoices in TeamUp and register customers.
Read-only access to a Zoopit account: orders, routes, fleet and live vehicle positions.
Add one secure layer between your agents and this server.
