Search Offers

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety bar is low; the description adds real value beyond that by enumerating the returned fields and disclosing the termination signal ('it is null on the last page') plus the stable-limit paging rule. It omits auth or rate-limit context, which keeps it from a 5.

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?

Purpose is front-loaded in the first sentence, then return fields, then the sibling pointer, then pagination — a clean priority order with no filler. Even the historical note ('once called Hourlies') earns its place by mapping older terminology to the resource.

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 carries the return-value burden and does it: it lists the fields returned and explains how to know when paging ends. Minor gaps remain (no mention of total result counts or ordering of the returned list beyond the sort param), but nothing needed to call it correctly is missing.

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 100%, so baseline is 3, but the description adds meaning beyond it — price is denominated in your account currency (relevant to interpreting price_range and the returned price), and the cursor/limit pairing is framed as a paging contract rather than two independent fields. Slight overlap with the schema's own 'keep it the same across pages' note keeps it at 4.

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 ('fixed-price Offers freelancers sell, by keyword or price') and immediately scopes what it returns: sales, rating, seller. It also names the sibling it is not — get_offer returns description, add-ons and images — so an agent can distinguish the list-search from the detail-fetch 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?

Explicitly routes the agent: use this for searching, use get_offer for description/add-ons/images, and gives the pagination protocol (pass next_cursor back as cursor with the same limit; null on the last page). It does not contrast against the other search siblings (search_projects, search_freelancers), but the fixed-price framing makes the boundary inferable.

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