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

Annotations already declare readOnlyHint=false, idempotentHint=false and destructiveHint=true, so safety is largely covered. The description adds genuinely new behavior: nothing is billed, no email is sent, the quote stays open until sent/accepted, and the call returns quote_id. It does not restate idempotency or permission requirements, so it is strong but not exhaustive.

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?

Front-loaded with a 'WRITE:' marker, then behavior, then parameter semantics, then return value and endpoint. The paycycle expansion is long but it is the only part that could not be inferred elsewhere, and every sentence carries information.

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?

No output schema exists, and the description compensates by naming the return value (quote_id) and the underlying endpoint (POST /quote). Required inputs, side effects, and preconditions are all covered, leaving nothing an agent needs missing for correct invocation.

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 100% schema coverage the baseline would be 3, but the description decodes the paycycle enum ('mon = monthly, 2mn = every 2 months, ...'), which the schema exposes only as opaque codes with the label 'Billing cycle of the quote.' It also clarifies the semantic constraint that each line's item must pre-exist. This is real meaning beyond the structured fields.

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 resource ('WRITE: create a quote (a proposal)') and scopes it to 'an existing customer,' which routes the agent away from chargeover_create_customer/contact. The parenthetical gloss on 'quote' removes ambiguity about what is being produced. An agent can distinguish this from every sibling create_* tool without opening a schema.

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 clear context: the customer must already exist, and each line must reference an existing item, with an explicit pointer to chargeover_list_items for that lookup. It does not state when NOT to use this (e.g. versus creating a subscription/invoice), so it stops short of full when/when-not guidance.

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