Poll a research task by request ID to check status and retrieve results; HTTP 202 means running, HTTP 200 returns completed data.
Retrieve the status and results of a research task by request_id. HTTP 202 means still running; poll until HTTP 200.
| Name | Required | Description | Default |
|---|---|---|---|
| requestId | Yes | Research task UUID returned by `research_create`. | |
| includeUsage | No | Include credit usage in the response. |
Changes observed during successful MCP inspections.
v0.1.0Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, open-world, and idempotent characteristics. The description adds useful behavioral detail beyond those annotations by explaining the HTTP 202 in-progress status and the need to poll until HTTP 200.
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?
Two tightly written sentences with no wasted words. The purpose is front-loaded, followed immediately by the key polling behavior.
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 simple two-parameter polling tool with full schema coverage and no output schema, the description covers the essential purpose and polling semantics. It does not describe the shape of returned results, but with no output schema that omission is minor.
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 description coverage is 100%, so both requestId and includeUsage are already documented in the input schema. The description mentions request_id but adds no syntax, format, or usage detail beyond what the schema provides, making this baseline-level.
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?
The description states a specific verb ('Retrieve') and resource ('status and results of a research task') with the lookup key ('request_id'). It is clear enough to distinguish from generic search tools, though it does not explicitly name the sibling tavily_research_create as the origin of the request_id.
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?
It gives clear operational guidance for polling: HTTP 202 means still running, and the agent should poll until HTTP 200. It does not explicitly say when not to use this tool or name alternatives, but the intended context is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.