docs(mcp): document add_to_thread and thread tools

consensus-mcp.mdx

@@ -302,6 +302,90 @@ Each search returns:
 - "Recent research on large language model hallucination from top tier journals"
 - "Use Consensus Deep Research to compare evidence for different treatments for insomnia"
 
+## Research thread tools
+
+The Consensus MCP server exposes research-thread tools for multi-turn, agentic research. Use `create_thread` to start a new thread and `add_to_thread` to continue an existing thread with a new follow-up.
+
+### `create_thread`
+
+Creates a new research thread and dispatches the Consensus research agent. Use this for detailed, synthesis, comparison, or multi-step research questions. For a simple list of papers, prefer the `search` tool.
+
+#### Parameters
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| input_message | string | Yes | Your complete research brief. Include the full question, scope, constraints, and any ordered sub-tasks. |
+| mode | string | No | Research depth. `pro` (default, fast) or `deep` (multi-step literature review, requires a signed-in paid caller). |
+| filters | object | No | Optional structured filters. Supports the same keys as the Search Tool. |
+| attachments | object | No | Optional attachments. `{"paper_attachments": [{"paper_id": "...", "es_hash_paper_id": "..."}], "collection_ids": [123]}`. |
+
+### `add_to_thread`
+
+Adds a new interaction to an existing research thread. Use this only for a genuinely new follow-up after seeing the previous interaction's results. Do not use it to decompose a single request across multiple calls — put the whole request in the `create_thread` brief instead.
+
+#### Parameters
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| thread_id | string | Yes | The `thread_id` returned by `create_thread`. |
+| input_message | string | Yes | A new follow-up question. The agent uses thread context and can reference papers from earlier turns. |
+| mode | string | No | Research depth. `pro` (default) or `deep` (requires a signed-in paid caller). |
+| title | string | No | The thread title from the `create_thread` response. Used only for the deep-link label; if omitted, the URL uses an `untitled` slug. |
+| filters | object | No | Optional structured filters. Supports the same keys as `create_thread`. |
+| attachments | object | No | Optional attachments. Same shape as `create_thread`. |
+
+### Dispatch response
+
+Both tools return an immediate dispatch confirmation while the agent runs asynchronously.
+
+<ResponseField name="thread_id" type="string">
+  The thread identifier.
+</ResponseField>
+
+<ResponseField name="interaction_id" type="string">
+  The new interaction identifier.
+</ResponseField>
+
+<ResponseField name="title" type="string">
+  The thread title used in the deep-link label.
+</ResponseField>
+
+<ResponseField name="status" type="string">
+  `running` while the agent is working.
+</ResponseField>
+
+<ResponseField name="mode" type="string">
+  `pro` or `deep`.
+</ResponseField>
+
+<ResponseField name="url" type="string">
+  Direct link to view the thread in Consensus.
+</ResponseField>
+
+<ResponseField name="message_for_user" type="string">
+  Human-readable confirmation with the Consensus link.
+</ResponseField>
+
+<ResponseField name="display_first" type="boolean">
+  Whether the result should be displayed first.
+</ResponseField>
+
+<ResponseField name="poll_after_seconds" type="integer">
+  Minimum seconds to wait before polling for completion (30).
+</ResponseField>
+
+<ResponseField name="max_wait_seconds" type="integer">
+  Maximum recommended wait time: 180 seconds for `pro`, 600 seconds for `deep`.
+</ResponseField>
+
+<ResponseField name="next_steps" type="string">
+  Polling instructions for the model.
+</ResponseField>
+
+<Note>
+  `deep` mode requires a signed-in paid Consensus account. Free accounts that request `deep` will receive a paid-account error.
+</Note>
+
 ## Troubleshooting
 
 <AccordionGroup>