Cancel a ride

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

Adds genuine behavior beyond the annotations: a free window while searching and for two minutes after a driver accepts, then a fee, plus the precondition that the ride must not have started. What remains unstated is whether cancellation is reversible and what happens to the fee if a ride is mid-acceptance; the destructiveHint=true annotation already signals the mutation.

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 the precondition, then the cost model, then the invocation rule. Every sentence carries information an agent needs.

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 destructive, output-schema-less tool this covers preconditions, cost consequences, and the trigger condition. The only real gap is the undocumented reason parameter and, secondarily, the ambiguity against cancel_scheduled_ride.

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 only 50%: ride_id is documented in the schema as omittable to target the active ride, but reason is documented nowhere. The description does not compensate, saying nothing about whether reason is surfaced to the driver or required in any case.

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?

Uses a specific verb and resource ("Cancels a ride") plus a decisive precondition ("that hasn't started"). It implicitly separates this tool from cancel_scheduled_ride, but never names that sibling explicitly, so an agent has to infer the boundary.

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?

Gives an explicit when-to-use rule, "Only call when the user asks to cancel", which is a real guard against proactive cancellation. It omits the when-not case that matters most here, namely that pre-scheduled rides belong to cancel_scheduled_ride.

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