send_message

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

Annotations already declare destructive=true, openWorld=true and idempotent=false, and the description adds genuinely non-redundant behavior on top: it may 'overwrite seller fields or rebuild retained drafts', invalid values 'reject the entire update', card selections are handled separately, quota is consumed, and dedup is 'bounded by retained session/job lifetime, not an unqualified retry guarantee'. That last caveat usefully qualifies the non-idempotent hint. It falls short of 5 only because the phrasing is compressed to the point of ambiguity in places.

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?

There is little filler, but the text is a single undifferentiated stream of clauses with no front-loading — the core action competes with quota, dedup and refusal notes for the opening position. Undefined acronyms (FAHCE) and bare schema tokens (TOOL_OFFER_INTAKE_V1) force parsing effort that a short structured layout would avoid.

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-stakes mutation tool with no output schema, the description covers the important contract: it returns a stable job, it may return a signed completed result under Prefer: wait, otherwise you poll get_result, and there is no payment or execution side effect. The only notable gap is nothing about failure responses or how the job handle should be retained across sessions.

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%, so baseline is 3, but the description earns above baseline by enumerating the intake keys (tool_url, docs, customer, pricing, payment, access, invocation, optional job and seller_name) and by stating that all non-enumerated values are strings and that a serialized TOOL_OFFER_INTAKE_V1 schema governs validation. That tells the agent message structure in a way the schema's single string field cannot.

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 the resource and the accepted payload shapes concretely: 'field: value lines, or a JSON-serialized StructuredIntake object', plus product questions, revisions and drafting commands. It also distinguishes itself from the polling sibling by pointing at get_result. It loses a point because the opening is a dense enumeration of value with undefined tokens (TOOL_OFFER_INTAKE_V1, FAHCE) that slow an agent down before it knows the core action.

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?

It gives real operational guidance: use 'HTTP Prefer: wait=1 through wait=5' to wait inline, 'Otherwise poll get_result', and 'Never resend uncertain work with a new request_id'. What is missing is any steering against the other siblings (assess_offer_readiness, export_offer) — an agent is told how to wait, not when this tool is the wrong entry point.

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