Delivery Planner by Spoke

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the write-but-non-destructive profile is covered structurally. Beyond that the description adds nothing: it does not say what is created or persisted, whether repeated calls duplicate state, or what the confirmation produces, and with no output schema the return value is entirely undisclosed.

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?

It is a single short sentence with no filler, so length is fine, but it is under-specified rather than concise, and the vague UI reference occupies the one slot where the tool's actual effect should be stated.

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?

This is a 7-parameter mutation tool with no output schema, so the description carries real burden to explain side effects and results. It explains neither, missing what an agent needs to call it confidently and to know whether the call succeeded in persisting a route.

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 71%, and the schema itself documents startPlaceId, stopPlaceIds, startTime, endPlaceId and ignoredFields richly. The description's "addresses and settings" adds no meaning beyond that — nothing about stop ordering, the optimizer's role, or what ignoredFields does in the result.

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?

"Records the addresses and settings" gives a weak verb and a fuzzy resource: it never says whether this creates a saved route, confirms an optimization, or persists a draft. The reference to "the Optimize button" is a UI artifact an agent cannot observe, and it does nothing to separate this tool from the sibling create_route.

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?

There is an implied trigger (data submitted by the Optimize button), but no explicit when-to-use, when-not-to-use, or prerequisite guidance. The sibling create_route is never mentioned, so the agent has no basis for choosing between saving a route and confirming one.

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 readOnly=false, idempotent=false, openWorld=true; the description goes further by explaining that every call creates a new route (matching non-idempotency) and, critically, that anyone with the returned link can view its addresses — a privacy consequence not encoded anywhere in structured fields. It also discloses a capability limit (no delivery time windows) that would otherwise cause silent misuse.

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 capability and scope, then usage triggers, then outputs, then exclusions — a sensible order with no filler sentences. It is on the dense side at roughly five clauses, but each one carries distinct information rather than repeating the 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?

Despite a single-parameter schema, the tool has real behavioral complexity (creates shareable artifacts, open-world geocoding, non-idempotent side effects), and the description covers side effects, sharing exposure, and capability limits. An output schema exists, yet summarizing the returned stops, duration, geometry, and links still helps the agent reason about follow-up steps.

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 parameter's own description already explains it is a single-use token returned when the user clicks Optimize. The description's sentence "Takes the single-use token the panel issues when the user clicks Optimize route" restates that rather than adding format, expiry, or failure semantics, so this is baseline territory.

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?

"Optimizes and saves one driving route for one driver with 1–20 delivery stops" gives a specific verb, resource, and hard scope bounds (single driver, 1–20 stops). It is clearly separable from siblings like confirm_route or select_addresses, which handle adjacent steps rather than route creation.

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?

States three concrete triggering intents (what order to visit, efficient route between stops, openable/shareable route) and an explicit exclusion list: no time windows, not for package tracking, transit, multiple drivers, or live traffic. It also names the precondition (token issued after the user clicks Optimize route), so the agent knows when the tool is even callable.

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 readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety and external-lookup profile is covered. The description adds that the result is the *nearest* address used to populate a start field, which is useful context. It omits what happens when no address is found, whether multiple candidates are returned, and any accuracy or rate considerations for an open-world lookup.

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 sentence with no wasted preamble, front-loaded with the verb 'Returns'. However, the phrasing 'from the Use current location button in the panel, to fill the start' is UI-jargon-heavy and grammatically tangled, weakening readability.

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?

The tool is simple (two numeric parameters) and has an output schema, so return values need no explanation. Still, for an open-world reverse-geocoding call, the description should say what happens on no-match or ambiguity; those gaps are moderate rather than fatal.

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 0%, so the description carries the burden, and it only says 'coordinates' without specifying coordinate system, precision, or units. The names latitude/longitude plus min/max bounds are largely self-explanatory, which prevents a 1, but the description adds no meaning 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: returns the nearest address for given coordinates, which is effectively reverse geocoding. It implicitly separates itself from search_places (text search) and select_addresses, though it never names a sibling. The UI-centric phrasing ('Use current location button in the panel') is odd for an API surface but the operation itself 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?

Usage is only implied through the UI trigger ('from the Use current location button... to fill the start'), which tells the agent the scenario but not the decision rule. There is no explicit statement of when to prefer this over search_places or select_addresses, and no exclusions or prerequisites.

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 establish readOnly/openWorld/non-destructive, and the description adds a genuinely useful behavioral caveat that annotations cannot convey: "Suggestions come from autocomplete and are not validated addresses." That tells the agent results may be wrong or incomplete and likely need a follow-up confirmation step. It stops short of describing result volume, ranking, or how locationBias affects outcomes beyond what the schema says.

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?

Purpose is front-loaded in the opening sentence, followed by usage context and then exclusions — a sensible order. The middle sentence is long and could be split, but every clause carries information about trigger conditions or accepted input formats, 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 an output schema present, the description needn't explain return values, and it covers purpose, triggers, input forms, a quality caveat, and exclusions. What remains thin is how multiple addresses should be handled given the "one address" phrasing versus the spreadsheet mention, which is the main ambiguity for a tool resolving lists of stops.

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 50%: locationBias is well documented inline, but query has no schema description. The phrase "for one address or place name" partially compensates by implying query is a single free-text name rather than a batch, though this sits in slight tension with the mention of pasted spreadsheets. Baseline 3 is appropriate since the schema carries most of the parameter meaning.

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 first sentence gives a specific verb and resource ("Finds Google address suggestions, with place IDs") and scopes the input to "one address or place name," so the agent knows exactly what comes back. It distinguishes the tool from unrelated capabilities in the negative clause, but never names a sibling (e.g., select_addresses) as the adjacent option, so it falls short of a full 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?

The description states concrete triggering contexts — planning deliveries, ordering driving stops, optimizing multi-stop routes — and explicitly lists input forms (spreadsheets, CSV, numbered lists), plus clear exclusions (place recommendations, package tracking, transit directions). What's missing is routing to an alternative tool when the exclusion applies, so there is when/when-not but no named alternatives.

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 readOnlyHint/idempotentHint annotations, the description discloses the key behavioral traits: this is an interactive UI panel requiring a user decision, missing start/finish render as empty fields, fields in routeSettings.ignoredFields are shown as not applied, and clicking Optimize yields a single-use confirmation token for route creation. The "single-use token" is a mild tension with idempotentHint but is framed consistently as a read operation; what remains undisclosed is what happens if the user cancels the panel.

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 sentences, front-loaded with what the panel does, then inputs, then the read-only/token consequence. Dense but every clause carries information; the long compound sentences slightly reduce scannability.

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 nested-input tool with an output schema, the description covers the semantics an agent needs: input shape, empty-field behavior, ignoredFields rendering, and the token handoff to creation. Since an output schema exists, the return shape need not be restated; only dismissal/cancellation behavior is 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?

With 50% schema coverage, the description compensates meaningfully: it explains that each entry is an original address plus its suggested matches, that empty candidates become a re-search affordance, and that ignoredFields controls what is displayed as not applied. It adds no detail on roundTrip, distanceUnit, or timeAtStopMinutes, but those carry schema defaults and descriptions.

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?

"Shows a panel where the user picks a match for each address and sets the start, finish, time at each stop and distance unit" gives a concrete verb (shows a picker panel) and resource (address matches + route settings), which is clearly distinct from search_places or create_route. It stops short of naming a sibling as the alternative path, so the differentiation is inferred from the mention of route creation at the end rather than stated.

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?

Use context is implied rather than stated: the panel consumes "each original address with its suggested matches" and addresses lacking suggestions "let the user search again in the panel," which tells an agent this follows a place-search step. There is no explicit when-to-use/when-not guidance, and no statement about what the agent should do instead if it already has confirmed coordinates.

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 readOnly, idempotent, closed-world, non-destructive, so the safety bar is met structurally. The description still adds real behavioral value by promising no address transfer and no account creation, which is the key concern for a link-handoff tool. It stops short of describing the returned link's form or any environment prerequisites.

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 the tool does, then the eligibility rule, then the side-effect disclaimer. No filler and nothing repeated 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?

For a single-enum, no-output-schema tool with strong annotations, the definition covers purpose, gating conditions, and side effects sufficiently to invoke it correctly. The only soft spot is that no output schema exists and the description only loosely characterizes the return value as 'a link'.

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 0%, so the description must carry the meaning, and it does: the prose triggers map cleanly onto the three enum values (multiple_drivers, time_windows, stop_limit), including the 20-stop threshold that the enum name alone does not convey. It does not state that exactly one reason must be chosen or how to disambiguate when several apply.

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 gives a concrete verb and resource: it shows a link to Spoke Dispatch, a route planner, and scopes it to needs the free planner cannot cover. The closing sentence ('it does not transfer addresses or create a Dispatch account') implicitly separates it from create_route/create account flows, though it never names a sibling 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?

It states exactly when to use it ('only when the user explicitly asks for one of those') and enumerates the three qualifying conditions: multiple drivers, enforced delivery time windows, or more than 20 stops. The exclusion ('only when... explicitly asks') is an explicit when-not clause that prevents over-triggering.

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