Accept a quote: creates an order at its price

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

With no annotations, the description carries the full burden and does well: it discloses that the resulting order is unfunded, that no funds move at this step, that the other quotes are declined (a real side effect an agent would not otherwise predict), and that full order-placement validation runs. It does not cover failure/partial-failure behavior, whether the decline of sibling quotes is reversible, or permission requirements.

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 sentences, all front-loaded and content-bearing: effect, then the money caveat and next tool, then the user-confirmation guardrail. No redundant restatement of the title or schema.

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 mutating tool with no annotations, no output schema, and an undocumented nested object parameter, the description explains side effects and the follow-on step but leaves the opaque 'input' field and the response shape unexplained. Adequate to call safely at a high level, incomplete for construction of the arguments.

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% and the description names no parameters at all. The nested free-form 'input' object is entirely opaque, and 'request_id' is never explained as an idempotency or correlation key, so an agent must guess at both beyond the bare UUID types in 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?

States a specific verb and result: 'Creates an unfunded order at the quote's price and delivery time, on the quoted service's rail.' The 'unfunded' qualifier and 'No money moves' explicitly separate it from payment siblings like agoreum_pay_order, and 'with every check placing an order runs' links it to the place-order family.

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 follow-up path ('Pay it next with agoreum_pay_order, where the spend limits apply') and a prerequisite ('Confirm the provider, price and delivery with the user first'). It does not state when to prefer this over agoreum_place_order or agoreum_start_order, so the routing among order-creation siblings is left partly implicit.

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