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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower, yet the description still adds real behavior: no cost, no API key, answers always terminate in callable next_calls, and 'trail' aggregates are counts only and suppressed below 3 buyers. The demand.filled webhook behavior for keyed callers is also disclosed. Minor cost: the webhook/waiting-for-seller flow is not obviously reconciled with openWorldHint=false.

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 opening directive is correctly front-loaded, but the body is a run-on string of fragments with broken grammar ('a dry-run buy with a draft because', 'trail: what agents with a goal like yours took...'), which reads as truncated rather than terse. Several clauses earn their place; the phrasing does not.

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 does carry the return-shape burden and covers listings, wishes, next_calls and trail, which is useful. It leaves gaps on what a listing record actually contains and how the 'trail' data relates to the results, and the garbled sentences reduce confidence an agent can rely on it.

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 50% — 'compact' is documented in the schema, 'goal' is not. The description compensates with a concrete example ('{"goal": "create a Swiss QR bill"}') and, critically, the '+' multi-goal separator semantics that appear nowhere in the schema. That is genuine added meaning beyond structured fields.

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 concrete action and output: 'Describe your goal in a sentence; get matching listings, related wishes and next steps.' The imperative 'Start here' positions it as a market entry point. It never names a sibling such as search_listings or market_map, so the boundary with those tools is left to inference.

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?

'Start here. Costs nothing, no key needed' gives a clear use condition and prerequisite. It also covers multi-need batching ('Separate them with +') and the no-result fallback path via demand.filled/webhook_url. It stops short of any explicit exclusion or alternative-tool routing.

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