route_waypoints

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

With no annotations, the description fully covers behavior: it resolves coordinates using geocoding, computes haversine distances, and returns specific results. The CRITICAL section adds valuable retry logic (simplify names, test with single geocode). However, it omits authentication needs, rate limits, or output size constraints, though these are less critical for a read-only geocoding tool.

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?

The description is well-structured: a brief purpose sentence, then details, then crucial retry guidance. It is front-loaded and every part adds value. The retry section is somewhat lengthy but justified for agent reliability. Slightly verbose but appropriate for guidance.

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?

Given no output schema, the description explains returns as 'Resolved waypoints, leg distances, total distance, and bounding box' but lacks precise format specification. It also misses error handling beyond retry guidance (e.g., invalid JSON input). The description is functional but could be more explicit about output structure for an agent to parse correctly.

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 0%, but the description provides detailed Args: waypoints is a JSON array with example, output_mode explains 'json' default and 'text' alternative. This adds significant meaning beyond the raw schema (which only has type string). Minor improvement: could specify accepted values for output_mode more explicitly.

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 clearly states 'Geocode waypoints in order and compute route distances', specifying the verb (geocode, compute) and resource (waypoints, route distances). It distinguishes from siblings like geocode (single point) and distance_matrix (all pairs) by focusing on consecutive waypoints in order.

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 provides no guidance on when to use this tool versus siblings like geocode, batch_geocode, or distance_matrix. It does include retry guidance but fails to mention scenarios where alternative tools would be more appropriate, leaving the agent without decision-making context.

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