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

Annotations cover only the safety profile (readOnly=false, openWorld=true, idempotent=false, destructive=false). The description goes well beyond that: it discloses the anonymous approach to the owner, that negotiation is bounded by the budget and the owner never sees it, that closing happens through Escrow.com, and that the call returns a deal id plus a status key. That is exactly the extra context the annotations cannot convey.

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?

Three sentences, front-loaded with the action and scope, followed by the precondition and the return contract. Every clause carries information an agent needs; nothing is restated from the title or schema.

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 output schema, the description correctly names the return values and routes to broker_status. It also covers the user-confirmation prerequisite. What it omits is the cost/fee implications of engaging a brokerage and what happens if the owner refuses or the budget is exceeded — relevant for a non-idempotent, open-world mutation.

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 75% (domain is undocumented), and the schema already explains email, notes, and max_budget. The description still adds genuine semantics for max_budget — it is a hidden ceiling the owner never sees, not a public offer — which changes how an agent should set it. It adds nothing for notes or domain.

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 and resource ('Ask GoMain's brokerage to acquire a domain someone else owns') and immediately distinguishes itself from direct-offer siblings like make_offer by specifying the domain must be owned by a third party. The agent can tell this apart from appraise_domain, check_availability, or make_offer without reading any 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?

Gives a concrete precondition — confirm the buyer's email and budget with the user before calling — which is real when-to-use guidance. It does not, however, name the alternatives (e.g. use make_offer when the domain is already listed for sale, or check_availability first), so the routing between siblings still requires inference.

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