Travel time/distance matrix

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

The annotations already declare readOnlyHint=true, so the agent knows the tool is safe for reads. The description adds value by noting that cells are null for nonexistent routes, which is useful behavioral information. However, it does not discuss error behavior (e.g., if an origin/destination cannot be resolved), performance constraints, or rate limits. With good annotation coverage, a 3 is appropriate.

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 two sentences long, front-loads the key output (travel times and distances), and wastes no words. The null-cells detail is a nice addition. It could potentially be even more concise, but it is already very efficient.

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 moderately complex tool with 4 parameters and no output schema, the description does well to explain the core matrix behavior and the null-case. It lacks details on return format (e.g., row/column order, units) and error handling, but the annotations handle the safety profile. Given the lack of output schema, a bit more about the return structure would be helpful, but overall it is reasonably complete.

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%: two required parameters ('origins', 'destinations', 'profile') have descriptions in the schema, but 'origins' and 'destinations' are only described generically. The description adds a concrete example ('5 hotels against 3 sights') that clarifies the batch comparison use case beyond the schema. However, it does not explain the 'language' parameter or the format of coordinates ('lat,lon') which is already in the schema. The description provides moderate added value on top of 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?

The description uses a specific verb ('computes') and clearly states the core resource ('travel times and distances from every origin to every destination in one call'). It also contrasts with the sibling 'route' tool by emphasizing the all-pairs matrix behavior, and includes the helpful detail that cells are null where no route exists.

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 explicitly describes the ideal usage scenario ('comparing options') and gives a concrete example ('5 hotels against 3 sights'). While it does not provide explicit when-not-to-use guidance or mention alternatives, the context is clear enough. Sibling tools like 'route', 'optimize_route', and 'straight_line_distance' are implicitly distinguished by the matrix emphasis.

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