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

Annotations declare only readOnlyHint=false, destructiveHint=true, openWorldHint=false; the description goes well beyond them by disclosing that accept immediately creates a confirmed order, that no payment method is charged at this step, that the buyer still completes payment through the normal flow afterward, and that a signed-in user or agent API key header is required.

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?

A single dense paragraph that front-loads the purpose, then the seller rules, the buyer rule, and the payment consequence, closing with auth requirements. It is appropriately sized for a stateful multi-action tool, though the action/role rules echo the schema's enum description closely.

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?

With an output schema present, return values need not be explained; the description still covers every decision point an agent needs — auth method, offer state requirements, action eligibility by role, counter_price conditionality, and the downstream consequence of acceptance.

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 100%, and the schema's own enum description already maps each action to seller vs. buyer and notes counter_price is required for 'counter'. The description largely restates these same role/action pairings, adding little syntax or format detail 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 ('Responds to') and resource ('a pending Make an Offer / bargaining offer'), which cleanly separates it from offers.make (creating an offer) and offers.list (reading them). The role-conditional action rules make the tool's scope unambiguous without opening the 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 explicit preconditions: sellers must use accept/reject/counter on a pending offer, buyers must use accept_counter on a countered offer. It does not name a sibling alternative for the underlying transaction (e.g. orders.place or offers.make), but the state conditions are precise enough to select the tool correctly.

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