os_route_get

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

Annotations include readOnlyHint=true, idempotentHint=true, and openWorldHint=true, which already indicate the tool has no side effects and may return variable results. The description adds minimal context beyond annotations: it mentions 'pgRouting-backed' implying a specific routing engine, but does not clarify behavior such as how stops are resolved (e.g., ambiguity handling), what constraints apply, or potential rate limits. Since annotations cover the safety profile, a 3 is appropriate as the description adds a little context but not deep behavioral details.

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 very short (one sentence), which is concise. It front-loads the core action and technology. However, it is under-specified for a tool with 7 parameters; the brevity comes at the cost of essential information. It omits key aspects like parameter overview, constraints, and output format. While concise, it does not earn its place fully because it fails to convey necessary usage details. A 3 reflects adequate efficiency but incomplete coverage.

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 has a complex schema with nested objects, multiple optional parameters, enums, and an output schema is present (though not shown). The description does not explain return values, which might be covered by the output schema, so that is not a critical gap. However, it does not explain what 'pgRouting-backed' means for the agent, nor does it outline the routing contexts (e.g., profiles, constraints) that the agent can use. Given the complexity, the description is incomplete; the agent lacks guidance on how to configure routes effectively. Annotations and schema are dense but not self-explanatory.

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%, meaning the schema does not provide descriptions for any parameters. The tool description does not describe any parameters either – it only mentions 'stops' implicitly. With 7 parameters and no descriptions, the description fails to compensate for the lack of schema descriptions. The enums for 'profile' and 'delivery' have no explanation, and the 'constraints' object is complex. This is a significant gap, as the agent has to guess parameter meanings.

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 states a clear verb ('Resolve route stops and compute') and a specific resource ('a pgRouting-backed route'). It clearly identifies the tool's function as routing, distinguishing it from most siblings (e.g., os_mcp_route_query, os_map_export). However, it lacks explicit mention of optional parameters like 'profile' or 'constraints', which are part of the purpose. It doesn't fully distinguish from the closely related 'os_mcp_route_query' sibling.

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 implies usage for computing routes, but provides no explicit guidance on when to use this tool versus alternatives. It does not exclude cases where other routing tools like 'os_mcp_route_query' might be more appropriate (e.g., different routing engine or simpler queries). No mention of required 'stops' array minimum of 2, or optional parameters like 'profile', 'constraints', or 'delivery' mode. The agent must infer conditions from the schema, which is not explicitly guided.

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