maps_select_route

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

With no annotations provided, the description carries the full load for behavioral disclosure, and it does disclose one genuinely non-obvious behavior: 'guard against UI reordering.' This reveals statefulness and a consistency mechanism that would be impossible to infer from the schema. However, it never defines side effects, failure modes (e.g., out-of-range index), or result semantics, leaving some gaps.

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 sentences and roughly 35 words, with the core purpose front-loaded first. The first sentence establishes the action; the second adds a single, high-value refinement. Every word pulls weight—no fluff, no restating 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?

For a low-complexity tool (2 primitive params, no output schema), the description covers the action, the interaction model (UI-based candidate selection), and a key safety mechanism (expectedLabel guard). It's missing some ideal context like what happens on failure, what the return/acknowledgement is, and whether the selection persists—but for such a simple tool, this is a minor gap.

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 0% schema description coverage, the description must compensate, and it does so meaningfully: 'zero-based index' clarifies the integer parameter's semantics (range is already in the schema) and 'Pass expectedLabel from maps_read_route_summary when available to guard against UI reordering' explains the optional string's purpose and provenance. Both parameters receive worthwhile elaboration beyond what the raw JSON Schema types/ranges convey, though more precise format details for expectedLabel would push it to a 5.

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 uses a specific verb-resource-scope pattern: 'Select a currently displayed route candidate by zero-based index.' The qualifiers 'currently displayed' and 'zero-based' precisely scope the operation and distinguish it from related tools like maps_select_result (search results) or maps_set_travel_mode.

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 usage context is implied through 'currently displayed route candidate' (implying you should use this only when route candidates are on screen), and the tip about 'Pass expectedLabel from maps_read_route_summary' hints at a workflow. However, it never explicitly names alternatives, excludes any scenario, or states when NOT to use this tool. The context is sufficient to avoid obvious misuse, but the guidance is implicit, not prescriptive.

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