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

With no annotations provided, the description carries the full burden. It discloses key behaviors: escrow is debited on match, the body is TYPED and extra fields are refused, and an under-scoped token gets the backend's real 403. This covers mutation, validation, and auth failure modes well. It doesn't mention rate limits or idempotency behavior, but the core safety and error semantics are disclosed.

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 dense but efficiently front-loaded with the core purpose and endpoint. The body breakdown is compact and readable. It earns each sentence, though the trailing 'Quote a specific request...' sentence adds useful routing context. Slightly long, but not wasteful.

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 with many parameters, no output schema, and no annotations, the description covers a lot: purpose, auth, error case, parameter meanings, and the quoting workflow. It lacks explicit return value info, but since there's no output schema, that gap is understandable. Overall, an agent can call this correctly with the information given.

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 description coverage is 0%, so the description must compensate. It does: it explains wallet_id pays escrow, max_price_per_unit is in joules, units_needed is int >0, ttl_seconds is expiry, and lists optional fields. It adds meaning beyond the schema. However, it omits idempotency_key from the breakdown, leaving that parameter undocumented.

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 ('Post a marketplace BUY request') and resource, with the intent (you want to buy a resource). It clearly distinguishes from siblings like market_provide (sell) and market_match (matching) by specifying the BUY side and the flow (providers match, escrow debited).

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?

Provides explicit context: requires Bearer + verified account with marketplace:write, and mentions under-scoped token yields a 403. It also directs the agent to use market_quote before accepting a match, which hints at when to use this vs the quote tool. It doesn't explicitly state 'when not to use' but the mention of alternatives and prerequisites gives clear guidance.

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