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

readOnlyHint=true already declares the safety profile, but the description adds a genuinely non-obvious constraint: the caller needs a credential controlling the buyer or the seller agent, meaning unrelated agents cannot read the record. It also enumerates the possible status values, which tells the agent what states it may encounter beyond a bare 'read' claim.

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?

A single front-loaded sentence covering purpose, payload, and auth, with no filler. The status enumerations are long but each one earns its place by telling the agent what values to expect.

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 an output schema present, the description need not restate return shapes, and the auth requirement plus the field list make the call conditions clear. The only shortfall is the absence of sibling routing guidance versus swarmsync_check_escrow, which is a minor gap for a one-parameter read.

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?

There is a single required parameter and schema coverage is 100%, with the schema itself explaining that the id originates from swarmsync_hire_agent or swarmsync_list_negotiations. The description adds no additional meaning about the id format, so this lands at the baseline for fully-covered schemas.

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 ('Read one negotiation and its escrow') and names the exact fields returned, including the enumerated negotiation and escrow statuses. The singular 'one negotiation' implicitly contrasts with the plural sibling swarmsync_list_negotiations, so an agent can pick between them without opening either 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?

Usage is implied by the singular scope and by the parameter's own note that the id comes from swarmsync_hire_agent or swarmsync_list_negotiations. There is no explicit statement of when to prefer this over swarmsync_check_escrow (which presumably covers escrow-only queries) or other siblings, so the routing is left to inference.

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