road-trip-planner

plot_trip

Creates a road trip on Stopful, or updates one plotted earlier, and returns an interactive map of it — adding, removing, reordering or renaming stops, changing nights, dates or party size, and redrawing the route. Renders a multi-stop driving route as an interactive map and returns a link to it, plus an inline map in clients that support one. Takes a list of stops in driving order, each with a place name, optional decimal lat/lon and number of nights; a stop without coordinates is geocoded from its name, and coordinates that fall far from where the name resolves are reported back in the result. Accepts an optional trip name, start date, party size, and a day-by-day itinerary that becomes a day view over the map. The map shows per-leg drive times and distances and an estimate of what the trip will cost before anything is booked, and is editable: the traveller can drag a pin to move a stop or drag the route to add one, and their changes are saved to the trip. Covers road trips and other multi-stop routes; a single destination or a route with no stops to draw has nothing to render. The result contains the map link, the trip as structured data, and the trip's id (see the id parameter for updating an existing trip).

Input Schema

TableJSON Schema

Name	Required	Description
`id`	No	Optional. Id of a trip returned by an earlier call, identifying which trip this call applies to. To change an existing trip, send its `id` together with the COMPLETE new `stops` and `days` — the call replaces the itinerary rather than merging into it, and there are no partial updates. The map link then stays the same, and edits the traveller made on the map survive: a re-sent stop keeps the position they dragged it to, and stops or waypoints they added on the map but absent from `stops` are kept, while a stop that was there before and is now omitted is removed. Without an `id` a separate new trip is created and none of those map edits carry over. Sending `id` with no `stops` is also accepted and changes nothing — it returns the trip exactly as saved.
`days`	No	The day-by-day itinerary: one entry per calendar day of the trip, in order, each with a title and the day's activities. It renders as a tappable day view over the map, and selecting a day highlights that day's driving; the activities also become the trip's itinerary in the full Stopful planner, where the traveller can edit them. Send it when planning a trip, or when deliberately rewriting the itinerary — it REPLACES the saved one wholesale, there are no partial day updates. On a call that only changes the route of an existing trip, leaving `days` out keeps the saved itinerary untouched, which is usually what is wanted; the result echoes whatever is saved either way.
`name`	No	Optional trip name (e.g. 'Lisbon → Pyrenees'). Defaults to first → last stop.
`stops`	Yes	The route in driving order, 1 to 40 entries (the first is the origin). Required for a normal call — the only call that omits it is `id` on its own, which re-reads a saved trip unchanged. Each entry needs `name`; every other field is optional.
`guests`	No	Optional party size.
`startDate`	No	Optional trip start as ISO yyyy-mm-dd.

Output Schema

TableJSON Schema

Name	Required	Description
`id`	No	The trip's id. Pass it back as the `id` argument to apply a later change to this same trip.
`url`	Yes	Link that opens this trip on the map at stopful.com.
`days`	No	The day-by-day itinerary. Activities may include ones the traveller added in the planner rather than through this tool.
`trip`	Yes	The trip as rendered, after geocoding and (on a continuation) merging the traveller's own map edits.
`assumed`	No	Stops placed from their name alone because no coordinates were given — approximate pins.
`notFound`	No	Stops that were requested but could not be placed, so they are absent from the map and the route.
`warnings`	No	Stops whose supplied coordinates are far from where their name resolves, with the distance and the resolved position.
`unchanged`	No	True when the call only read the saved trip and changed nothing — an `id` sent with no `stops`.
`keptByTraveller`	No	Stops left where the traveller placed them on the map, so the coordinates supplied in this call were not applied.

TDQS

A4.8/5.0

Behavior5/5

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

Annotations only declare readOnlyHint=false, openWorldHint=true, destructiveHint=false, and idempotentHint=false. The description adds extensive behavioral detail: it returns an interactive map, supports editing with drag-and-drop, persists traveller changes, geocodes stops without coordinates, reports coordinate mismatches, replaces the itinerary instead of merging, and preserves map edits on update. It also explains the side effects (changes saved to the trip) and the read-modify-write nature of updates. This far exceeds the minimal expectations given annotations.

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 description is long but information-dense. It front-loads the core action and then layers details about behavior, edge cases, and result contents. Every sentence contributes new information (e.g., geocoding, edit persistence, replacement semantics, nothing-to-render case). While it could be tightened, the length is justified by the tool's complexity (6 params, nested objects, update semantics). No filler or repetition is present.

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?

The description covers the return value ('map link, the trip as structured data, and the trip's `id`'), the update workflow, geocoding behavior, coordinate mismatch feedback, editable map behavior, and the condition where the tool has nothing to render. It also explains the meaning of `id` on its own (re-reads a saved trip). Given the output schema exists and the tool's complexity, nothing critical is missing for an agent to call it correctly.

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

Parameters4/5

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 adds value by synthesizing the parameters into a coherent narrative: it clarifies how `stops` interact with `id` (replacement vs merge), how `days` behaves (replaces wholesale), and how geocoding works for name without coordinates. While the schema already documents each parameter individually, the description provides contextual links between them (e.g., 'the call replaces the itinerary rather than merging', 'map edits survive' when re-sending `id`). This raises it slightly above baseline.

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 precise verb+resource statement: 'Creates a road trip on Stopful, or updates one plotted earlier, and returns an interactive map of it.' It enumerates the exact operations (adding, removing, reordering, renaming stops, changing nights/dates/party size) and clearly distinguishes this multi-stop route tool from anything that would handle a single destination ('a single destination or a route with no stops to draw has nothing to render'). No sibling tools exist to differentiate, but the scope is unambiguous.

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

Usage Guidelines5/5

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

The description explicitly states when to use the tool (road trips and other multi-stop routes) and when not to ('a single destination or a route with no stops to draw has nothing to render'). It also gives clear guidance on create versus update semantics via the `id` parameter explanation, including the replacement behavior and retention of map edits. There are no siblings to compare against, so these context-based guidelines fully satisfy the dimension.

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

All road-trip-planner tools Inspect

Try in Browser

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

TDQS

A4.4/5.0

Disambiguation5/5

With only one tool, there is no possibility of confusing it with another. The single tool's purpose is clearly defined, even though it handles many sub-tasks internally.

Naming Consistency5/5

The sole tool name 'plot_trip' follows a consistent verb-noun pattern. Since there is only one tool, naming consistency is trivially maintained.

Tool Count2/5

One tool for an entire road trip planner domain is too few. A typical server would have separate tools for creating, fetching, updating, and deleting trips. This single overloaded tool makes agent workflows awkward and forces a single point of entry for all operations.

Completeness2/5

The tool handles creating and updating trips, including stop modifications and itinerary details, but lacks read (get), delete, and list operations. This creates dead ends (e.g., no way to retrieve a trip without modifying it) and leaves the domain partially covered.

Resources

Need Help?