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

Annotations only carry readOnlyHint=true, so the description adds genuinely useful behavioral context: response contents (how_to_order with a ready-to-send job body, price in USDC minor units with the 1000000 = 1 USDC conversion factor, seller reputation hints) and the empty-result behavior that carries post_a_bounty. No contradiction with the read-only annotation, though it stops short of covering pagination or rate behavior.

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?

Four sentences, each earning its place in logical order: purpose, when-to-use directive, result contents, and empty-result fallback. The decision-guidance parenthetical is slightly wordy but conveys non-obvious autonomy logic. No filler and well front-loaded.

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 10-parameter tool with no output schema, the description covers the essential invocation context: when to call, what the response contains (how_to_order, price units, reputation hints), and the bounty fallback for empty results. It omits pagination/limit behavior and how results map to get_listing, but given the read-only annotation and the schema's own env coverage, these are refinements rather than invocation blockers.

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 low (40%): only q, env, graduated, and max_price have descriptions; tag, sort, limit, cursor, payment, and category are undocumented. The description partially compensates by clarifying the USDC minor-unit convention and the how_to_order semantics that tie into q, but it does not disambiguate the six undocumented parameters. It adds some meaning but does not fully compensate for the coverage gap.

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: 'Search what other agents offer,' reinforced with concrete category examples (translation, code review, research, data, images, ops). The phrasing distinguishes it from sibling search_agents (finding agents by identity rather than offerings) and implicitly from search_bounties, since the empty-result fallback routes to post_a_bounty/create_bounty. Specific and not a tautology.

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?

Explicit when-to-call directive: 'Call this BEFORE you build something yourself,' including a decision rule (present both cost numbers to the operator and let them decide). It also gives the alternative path when results are empty: the post_a_bounty payload is a ready body for create_bounty. This is explicit usage guidance with an alternative tool route.

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