Optimize routes
optimize_routesPlan delivery routes (vehicle routing problem, VRP): assign stops to vehicles and sequence each route from one depot, minimizing distance within max stops per vehicle, weight (kg), volume (m3) and time windows; dozens to thousands of stops. Send exactly one source of stops: plan_id, a saved plan (list_plans, get_import_result); dataset_id, an import; or stops, only for stops whose latitude and longitude are in this conversation (files, lists and addresses go through import_deliveries first). depot: depot_id from list_fleet, latitude/longitude, or an address (tell the user the depot_resolved match). A plan_id or dataset_id run is saved in that plan; stops save a new plan on every call (plan_name). A run spends one monthly stop per stop. Within 24 h of a plan's charged run, the same plan with the same stops or fewer (id and coordinates) is another try: no stops charged, plan limits still apply (Spanish 'otro intento'; never call it free); next_optimize_charged and charged_because say which applies. To vary a stops run (vehicles, max_stops), rerun its plan_id: sending the stops again charges again. Every call runs and charges, so first tell the user the stops it charges and those left, the vehicles and the constraints, get a yes, then call once. Arrival times need route_start_time. exclude_stop_ids leaves stops of a plan or dataset out for this run only. Identical arguments are deduplicated; a request over the account plan, or needing a constraint it lacks, is rejected and never partially applied. Tell the user when plan_replaced or plan_temporary is set. Returns optimization_id, with the result when it finishes within seconds; poll get_optimization_result.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| date | No | Delivery date YYYY-MM-DD in time_zone. Default: today. | |
| depot | Yes | Where every route starts: a saved depot, coordinates, or an address the server geocodes. | |
| stops | No | Stops whose coordinates are in this conversation. Every call saves a new plan. | |
| plan_id | No | A saved plan (list_plans, get_import_result). The run is saved in that plan. | |
| vehicles | Yes | Fleet for this run (1-50 vehicle types). | |
| plan_name | No | With stops: name of the new plan. Default: Optimization YYYY-MM-DD. | |
| time_zone | No | IANA time zone for date and times, e.g. America/New_York. | UTC |
| dataset_id | No | An import's stops (get_import_result, list_datasets), run in the plan it loaded into. | |
| depot_name | No | Depot name shown in the plan. | |
| use_volume | No | Optimize by volume. Omit to follow the vehicles' max_volume_m3; false keeps volumes for reference. | |
| use_weight | No | Optimize by weight. Omit to follow the vehicles' max_weight_kg; false keeps weights for reference. | |
| max_load_ratio | No | Highest share of each vehicle's weight/volume capacity to fill. Default 0.95 (5% margin); 1 only when the user asks to fill vehicles completely. | |
| idempotency_key | No | Optional key to deduplicate retries. By default identical arguments are deduplicated. | |
| exclude_stop_ids | No | With plan_id or dataset_id: stops to leave out of this run only; the plan keeps them. | |
| route_start_time | No | Time routes leave the depot, local HH:MM. Needed for arrival times and time windows. | |
| use_time_windows | No | Respect the stops' time windows. Omit to follow the data; false keeps them for reference. | |
| max_route_minutes | No | Target journey length per route in minutes (travel + service). A balancing target, not a hard limit: the engine evens routes out towards it and some may run longer. Tell the user it is a target, check the durations in the result, and when routes exceed it offer more vehicles or fewer stops per vehicle. | |
| service_time_minutes | No | Minutes spent at each stop. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| error | No | Structured error when the tool call failed. | |
| result | No | Present when the optimization finished within the call. | |
| status | No | queued / running / completed / failed. Absent on a preflight-only reply. | |
| plan_id | No | The plan this lives in, in the user's Vepathos account (list_plans). | |
| progress | No | Present while queued or running. | |
| plan_name | No | Name of that plan. | |
| preflight | No | Present instead of an optimization when confirmed was false: nothing ran, nothing was charged. | |
| expires_at | No | While running: when an unfinished run is dropped (UTC). Completed runs stay. | |
| free_retry | No | True when this run is another try (no monthly stops charged). Say 'another try' / 'otro intento'; never call it free. | |
| account_url | No | Opens the plan in the user's Vepathos account. Requires signing in; private to the account. | |
| plan_replaced | No | Set when the library was full: this plan was removed to make room. Tell the user its name. | |
| quota_charged | No | False when this run is another try of the plan or the trial: no stops charged. | |
| schedule_date | No | Date used for the run, YYYY-MM-DD. | |
| depot_resolved | No | Present when the depot was given as an address: tell the user the matched address the routes start from. | |
| plan_temporary | No | True when every library slot is kept or favorite: the plan lives outside the library and is deleted later. Tell the user. | |
| optimization_id | No | Handle for get_optimization_result. | |
| submitted_stops | No | Stops accepted into this job. | |
| idempotent_replay | No | True when identical arguments returned an optimization that already existed. | |
| full_trial_applied | No | Present when this job used the one-time MCP full trial. | |
| poll_after_seconds | No | Call get_optimization_result again after about this many seconds. | |
| vehicles_available | No | Fleet units declared (sum of vehicles[].count). | |
| free_retries_remaining | No | Other tries of this plan still available after this run: within 24 h, same stops or fewer, by plan_id. Say 'other tries' / 'otros intentos'; do not call the run free. | |
| stops_remaining_this_period | No | Stops left in the plan's current billing period (null means unlimited). |