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

Annotations only say readOnlyHint=false, openWorldHint=false, destructiveHint=false. The description adds critical behavioral context: token validity scope, placeholder token invalidity, the two-phase confirmWrite semantics, and that the token does not bypass preview/confirmation. It doesn't fully disclose error cases or idempotency, but given the annotations are minimal, the description carries the burden well. Minor deduction for not explaining what happens to reconciled lines if a parameter is invalid.

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 a dense single paragraph covering purpose, token requirements, confirmation semantics, and counterparty confirmation. It front-loads the primary purpose and then details the workflow guards. Slightly verbose in places (repeated emphasis on explicit confirmation), but every sentence adds operational value.

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 high-complexity transactional tool with 30 params and no output schema, the description covers the essential workflow, token, and confirmation semantics. It doesn't describe the output/return payload (confirmation_required is mentioned but full response shape is not), and it doesn't enumerate prerequisites like company connection. However, given the schema covers many params and the description addresses the riskiest aspects, 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 only 40%, so the description must compensate. The description explains the routeToken semantics (routing permission only), the confirmWrite semantics, confirmCounterpartyExplicit, and confirmQuotesAutoGenerateInBrc's purpose. It does not walk through all 30 params, but the critical workflow-guarding params are well explained. The description adds real meaning beyond the schema for the confirmation-related 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 states it creates a quote with generated references and reconciled product/VAT/Sales-analysis lines, distinguishing it from brc_create_quote (manual reference) and siblings with _gen_ref suffix. It clearly identifies the resource (quote) and the action (create). It could be sharper about why this tool vs brc_create_purchase_gen_ref or brc_create_sales_invoice_gen_ref, but the verb+resource is clear.

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 states the workflow prerequisites: requires a valid routeToken from brc_route_request, requires confirmWrite: true only after explicit confirmation, requires confirmCounterpartyExplicit: true, and explains that passing preflight is not confirmation. It also explains the confirmation_required response path. This gives an agent clear when-to-use and when-to-confirm guidance.

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