refuse_deal

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

No annotations exist, so the description carries the full burden, and it does disclose meaningful behavior: the refusal consumes a pending deal and, when leaders are queued, returns still_pending/next/gate. It omits any diplomatic consequence of refusing (e.g. relationship effects), which for a refusal tool would be the one remaining behavioral trait worth naming.

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-loads the action and its scope, then adds the queue branch. The second sentence is long and packs several return fields, but each clause adds information about the response, so little is wasted.

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 no annotations and no output schema, the description compensates by describing the returned still_pending/next/gate fields, which an agent needs to continue the interaction. The gap is the absence of any stated side effect or consequence of refusing.

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?

The tool takes zero parameters, so the baseline is 4; there is no argument surface the description could or should elaborate, and the schema correctly forbids additional properties.

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 ('Refuse') plus a precisely scoped resource ('an incoming trade already on the table') and explicitly contrasts with sibling behavior ('Does not construct a new deal'), routing the agent away from propose_deal/negotiate_deal. Cross-references incoming_deal for the source of the deal.

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?

The condition for use is clear: only when a deal is already on the table, with incoming_deal named as the companion read. It also covers the multi-leader queue case and tells the agent to answer the next one without a discussion() read. No explicit when-not guidance beyond 'does not construct a new deal'.

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