negotiate

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

With no annotations, the description carries the full burden and does so well: it explains that propose/accept_proposal constitute agreement, that accept triggers HTLC creation, and that the initiator's secret is generated locally with only its hashlock sent, retrievable via get_deal_secret. It also discloses that a stale price causes refusal and that reject closes the deal.

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 bullet-list structure is front-loaded and appropriate for a five-action tool, with no filler sentences. Some clauses are long and nested, especially around accept and hashlock handling, but every part conveys useful semantics.

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 complex mutation tool with no annotations or output schema, the description covers action semantics, side effects, and secret handling thoroughly. It could go further by explaining the response after each action or explicitly telling the agent where to obtain thread_id, so it is strong but not fully self-contained.

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 descriptions cover only body and price minimally, and action/thread_id have no descriptions. The description compensates by mapping body to message and price to the exact price required for propose, accept_proposal, and accept, including the source (pendingPrice/currentPrice). That adds substantial meaning beyond the schema.

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 opens with 'Act in a deal thread' and enumerates five concrete actions, so the tool's scope is clear. It references deal_status and my_deals as sources of pricing state, indirectly separating negotiation writes from status reads, though it does not explicitly name every sibling it is not.

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 precise conditions for selecting accept vs accept_proposal vs propose, including that accept is only needed when youAccepted is false and that accept_proposal uses pendingPrice. It also tells the agent to re-read the deal if the named price has changed. It stops short of stating when to use negotiate versus RFQ tools like respond_to_rfq.

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