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

Goes well beyond the readOnly/openWorld/idempotent annotations: result cap (~24 rows), seller-ask price semantics, 15-minute cache, and a concrete billing model ('1 request per completed search, cache hits included; failed searches are free'). An agent can predict both cost and freshness before calling.

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?

Five short sentences, front-loaded with what/how/limits, then behavior, then cost, then docs. Every clause carries decision-relevant information with no filler.

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 13-parameter, no-output-schema tool it covers scope, row caps, caching, billing, and a docs link. The main remaining gap is return-shape guidance (what a row contains, and when 'full' vs 'summary' matters functionally), though the fields enum in the schema partly covers this.

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 the baseline is 3, but the description adds interpretation the schema lacks: prices are asking prices (not sold), result counts vary by sort (24 vs ~15 for best_match), and the docs link. It stops short of describing the lat/lon vs zip mutual exclusion already spelled out in the schema.

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 precise verb+resource+scope: search Facebook Marketplace US active listings near a ZIP or point. The 'active' qualifier and 'No sold search' cleanly separate it from sold-price siblings like ebay_sold/mercari_sold without opening a 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 clear context (location-scoped active listing search) plus an explicit exclusion ('No sold search'), which is the key selection axis against the sold/aggregate siblings. It does not, however, name the alternative tools (e.g. facebook_item for a single listing, the *_sold tools) the way a 5 would.

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