Draft a reply to a buyer

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

With annotations declaring readOnlyHint=false, destructiveHint=false, and openWorldHint=false, the bar is lower, yet the description still adds real value: it discloses that the output is a DRAFT requiring human approval rather than a sent message, that negotiation state is persisted across rounds, and that buyer text is untrusted data (a prompt-injection warning). It stops short of stating permissions, rate limits, or what happens to an unapproved draft.

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?

Two sentences: the first front-loads the trigger ('Paste a buyer's message') with a compact pipeline, the second front-loads the critical return/behavior facts. Dense but no filler; the long enumerations of intents cost some readability without wasting much space.

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 multi-step tool with no output schema and zero schema-level parameter documentation, the behavior side is well covered but the invocation side is not: an agent cannot learn from the description what listingId vs. buyer mean, what tone changes, or where the floor/ceiling/rules configuration is sourced. Adequate, but with a clear gap on inputs.

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% across 4 parameters, so the description must compensate and largely does not. It alludes to the message body and references 'your floor/ceiling and rules' — which are not parameters at all — while the roles of listingId, buyer, and the friendly/brief tone enum are never explained.

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 names a specific verb and resource ('drafts a reply') and enumerates the full internal pipeline: intent detection, offer extraction, scam flagging, negotiation engine, thread tracking. An agent can distinguish this from negotiate_offer (which computes rather than drafts) and send_dm (which sends rather than returns a draft) without opening any 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?

'Paste a buyer's message' plus 'The thread is tracked for negotiation rounds' implies when the tool applies, and 'Returns a DRAFT needing your approval' implies the follow-on action. However, it never states when NOT to use it or names an alternative sibling (e.g., negotiate_offer, send_dm) for cases where drafting is the wrong step.

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