AgentSearch Review Board: what works now

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

Goes well beyond the readOnly/idempotent/openWorld annotations: down services are hidden unless include_down is true, board/network failures (HTTP 429) surface as MCP errors, no API key or AGENTSEARCH_BASE_URL is needed, and AgentSearch's own services get no ranking boost. The untrusted_note prompt-injection warning is exactly the kind of safety disclosure annotations cannot carry.

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?

Front-loaded with the call-to-action and free of filler, but it is one dense run-on paragraph with stacked parentheticals (env var defaults, category list). It earns nearly every sentence, yet light structure would make the mode switch and error behavior easier to scan.

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 contract itself: ranked fields (id, status, uptime_24h, p50 latency, price_usd, review counts/labels) and the single-service variant. Error behavior and configuration prerequisites are also covered, leaving little an agent needs before calling.

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; the description still adds value by explaining that include_down controls whether 'down' services appear and that service_id switches from a ranked list to single-service mode (with 7-day probe history and reviews). It does not add anything for max_price_usd, network, or limit beyond their schema text.

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?

Specific verb ('look up') plus a named resource ('AgentSearch Review Board') with explicit scope: which services work right now for a task across Pocket, x402 and remote MCP servers. It is clearly distinguishable from the sibling execution tools (agentsearch_web_search/extract/render) and from agentsearch_review_submit, which it names as the counterpart.

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 an explicit trigger ('Look up before choosing a tool'), an alternate mode ('Pass service_id instead of task'), and a follow-up path ('After you use a service, report how it went with agentsearch_review_submit'). The 'when not to use' side is implied by the named alternative for submissions.

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