firestarter_assist_book

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

Annotations declare destructiveHint=true, idempotentHint=false, and readOnlyHint=false, and the description reinforces this by stating the action dispatches a real crew and charges a fee. It also adds detail about the escrow inspection window when linked to a purchase execution, providing useful side-effect context beyond the annotations. No contradiction exists.

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 three sentences, each serving a purpose: stating the action, highlighting the real-world consequences and prerequisite, and describing a side effect. It front-loads the main action and is efficiently written without redundancy. It is concise and well-ordered.

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 the tool has 11 parameters, no output schema, and low schema coverage, the description leaves significant gaps. It doesn't mention what the booking returns (e.g., a booking ID), how errors are reported, or the format for addresses and contacts. While it explains the relationship to quotes and execution, it's incomplete for an agent to confidently construct a valid call with all required fields.

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 only 36% schema description coverage, the description should compensate by explaining key parameters, but it only lightly touches on quote_ref and provider. It mentions the 'exact quoted price' but doesn't explicitly map it to fee_cents, and leaves required params like pickup_address and dropoff_address unexplained beyond their names. The description adds some meaning but fails to fill the coverage gap for most of the 11 parameters.

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 the primary action: 'Book a courier from a firestarter_assist_quote result.' It specifies the resource (courier) and the source (quote result), and distinguishes it from sibling tools like firestarter_confirm_delivery by focusing on the booking action. It could be more explicit about the distinction from other shipping tools, but the purpose is unambiguous.

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 critical usage guidance: it dispatches a real crew, charges the buyer's order, and requires prior explicit confirmation of the quoted price. This tells the agent when it's appropriate to call the tool and what prerequisites must be met. It doesn't explicitly state alternatives, but it implies this is a post-quote, post-confirmation step, which is sufficient for distinguishing it from quote-generation tools.

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