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

Adds substantial context beyond the annotations: typical latency (~15 s), the polling handoff, job deduplication for identical questions, that code is read but never executed, and an epistemic caveat that a found statement is the vendor's own claim, not independent verification. The readOnlyHint=false annotation is consistent with the description's disclosure that a job is created (a job_id is returned).

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 trigger condition and free of filler, but it is one dense run-on paragraph carrying trigger, mechanics, async handoff, dedupe and caveat in a single breath. Splitting the async/dedupe/caveat sentences would improve scanability without adding length.

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?

An output schema exists, yet the description still supplies what the schema cannot: when the call is warranted, expected latency, what to do on timeout, job sharing, and how much to trust the result. For a paid, open-world, asynchronous research request this covers everything an agent needs before invoking 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 100% and all three parameters are already documented, including provider_id provenance and requirement examples, so the baseline is 3. The description's sample payload restates the same information rather than adding new semantics such as how request_ref links to a prior answer or how to phrase requirements that the answer vocabulary (yes/no/partly/unknown) can resolve.

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 (request research), a precise scope (one specific fact about one listing that its profile does not settle), and the exact sources consulted (vendor pages, code repository read-not-run, pricing page buttons). The answer shape (yes/no/partly/unknown with quotes, URLs, observation dates) makes it unmistakable which sibling produces this output versus get_provider_profile or compare_providers.

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?

The opening clause gives an explicit trigger condition and two concrete example questions, and the async path names the alternative: if not answered in ~15 s, call get_research with the job_id after poll_after_seconds. It also warns that identical questions share one job. It lacks an explicit 'do not use for' against broad siblings like research_capability or compare_providers, so the exclusion is only implied by 'one specific fact about one listing'.

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