ValveRide Flow

Optimize a truck fuel plan

optimize_fuel_plan

Build an optimized diesel fuel plan for a truck route. Send the truck profile, current fuel, origin, and destination; ValveRide Flow routes the leg, discovers truck stops along it, prices them from its live retail diesel grid, applies your discount schedule on net price, and returns where to stop, how many gallons to buy, and the estimated savings (IFTA tax-aware). The response includes a tripId; to replan mid-trip, call again with that tripId, currentLocation set to the truck's live position, and the updated currentFuelGallons -- replans of the same trip bill at the replan rate ($0.08) instead of the full plan rate ($2.25). VENDOR RULE: if the user restricts fueling to a brand or network ("Love's only", "we can only fuel at Pilot or Flying J"), you MUST set vendorRule.allowedVendors to those brands. It is a hard rule: only those stations are considered and, if none works, the tool returns no_feasible_plan_under_vendor_rule instead of an off-brand stop. Put any discount the user mentions for that brand in discountSchedule with the same vendor in the SAME call (for example "10 cents off at Love's" = vendorRule.allowedVendors ["Loves"] plus discountSchedule [{vendor:"Loves", discountType:"CENTS_PER_GALLON", discountAmount:10}]). The response echoes vendorRule and appliedDiscounts so you can confirm both were enforced.

Input Schema

TableJSON Schema

Name	Required	Description
`truck`	Yes
`origin`	Yes	Where the trip starts, as {lat,lng} or a place string like "Des Moines, IA"
`tripId`	No	Optional: the tripId returned by this trip's first call. Pass it (with an updated currentLocation) to replan the SAME trip at the $0.08 replan rate; omit it for a new trip ($2.25). Must match the trip's destination and be within 14 days.
`options`	No	Optional planning knobs
`taxRates`	No	Optional per-jurisdiction diesel tax overrides; defaults to current US/CA rates
`vendorRule`	No	STRICT vendor allowlist. Set this whenever the user says they can only fuel at certain brands ("Love's only"). Only stations of these brands are considered; the plan never falls back to other brands. Aliases are accepted (Love's / Loves / Love, Pilot / Flying J / PFJ, TA / Petro). Infeasible under the rule returns the structured error no_feasible_plan_under_vendor_rule.
`destination`	Yes	Destination as {lat,lng} or a place string like "Denver, CO"
`currentLocation`	No	Optional: the truck's live position for a mid-trip replan. Defaults to origin; when set, the plan covers the remaining leg from here.
`discountSchedule`	No	Your negotiated fuel discounts, applied on top of retail to optimize on net price
`currentFuelGallons`	Yes	Fuel currently in the tank, in gallons

Schema Changelog

Changes observed during successful MCP inspections.

First observedSep 15, 2026

TDQS

A4.7/5.0

Behavior5/5

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

Even with annotations present, the description reveals behavior annotations cannot: the no-fallback vendor rule and its structured error no_feasible_plan_under_vendor_rule, the $2.25 vs $0.08 billing split, and the fact that the response echoes vendorRule and appliedDiscounts. No contradiction exists with the readOnlyHint or idempotentHint flags.

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

Conciseness4/5

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

The text is densely packed and front-loaded with the core purpose, and the VENDOR RULE block is clearly flagged. It is longer than strictly necessary and repeats some schema-level vendorRule detail, but each section adds operational value.

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

Completeness5/5

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

Despite 10 parameters and no output schema, the description covers end-to-end behavior, key outputs, replan semantics, pricing rates, and the vendor-rule failure mode. Optional knobs remain documented in the schema, so nothing critical for correct invocation is missing.

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

Parameters5/5

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

Although schema coverage is high, the description adds crucial inter-parameter meaning: how vendorRule.allowedVendors and discountSchedule must be paired in the same call, with a concrete '10 cents off at Love's' example, and how tripId plus currentLocation/currentFuelGallons drive replanning. This goes beyond the schema's isolated parameter descriptions.

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

Purpose5/5

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

The description opens with a specific verb and resource: 'Build an optimized diesel fuel plan for a truck route,' then enumerates the pipeline and concrete outputs including stops, gallons, savings, and a tripId. This is clearly distinct from the sibling fuel_market_snapshot, which is about market pricing rather than constructing a route plan.

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

Usage Guidelines4/5

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

It gives clear operational context: when to create a new trip versus replan mid-trip with a tripId and currentLocation, and when the vendorRule must be set. It does not explicitly contrast with fuel_market_snapshot or state a when-not-to-use, so it stops short of a 5.

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

All ValveRide Flow tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?