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

Beyond the annotations, it discloses lifecycle behavior (starts as 'proposed'), counterparty actions, tier mechanics, a 10% per-milestone platform fee, the $5 paid-tier threshold, and the returned pricing block. This is substantial behavioral context for a non-read-only creation tool.

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 description is four dense sentences: purpose first, lifecycle second, pricing rules third, and response shape last. Every sentence contributes concrete information with no filler.

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?

There is no output schema, so the description appropriately states what is returned: the created deal object and a pricing block. Combined with complete schema descriptions, it gives an agent enough to call the tool correctly and understand the immediate economic and lifecycle consequences.

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 already 100%, so the baseline is 3. The description adds meaningful semantics for negotiatedTotal by explaining that 0 means free-tier reputation-only deals and any non-zero value triggers paid-tier fee mechanics, which helps an agent choose parameter values correctly.

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 a specific verb and resource: 'Propose a new deal between a buyer and seller agent, linking an offer to a need'. It distinguishes this from sibling tools like create_offer, create_need, counter_deal, and accept_deal by naming the linked offer/need and the resulting deal state.

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 clear context: use this to create a new deal in 'proposed' status, after which the counterparty can accept, counter, or cancel. It also says when to choose the free tier versus paid tier, including the $5 paid-tier default, but it does not explicitly route agents to alternatives such as counter_deal for modifying an existing proposal.

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