Skip to content

docs(mcp): sync thread tool docs for get_thread poll tool (CON-5229, CON-5234) #14

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
devin-ai-integration wants to merge 1 commit into
base: main
Choose a base branch
from
+94 −0
Draft

docs(mcp): sync thread tool docs for get_thread poll tool (CON-5229, CON-5234) #14

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
94 changes: 94 additions & 0 deletions consensus-mcp.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -302,6 +302,100 @@ 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 threads

The thread tools run multi-step, citation-grounded research for synthesis, comparison, contradiction, and literature-review questions. You create a thread, poll it with `get_thread`, and list threads with `find_threads`. Research threads require a signed-in Consensus account; `deep` mode requires a paid plan.

<Note>
Use the search tool for a simple paper list. Use thread tools when you need a synthesized, multi-step answer with inline citations.
</Note>

### create_thread

Starts a new research thread and dispatches the Consensus agent.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| input_message | string | Yes | Your complete research brief. Include the whole question, scope, population, timeframe, comparisons, constraints, and desired output in one call. |
| mode | string | No | `pro` (default, ~20 papers, fast) or `deep` (~50 papers, up to 100, structured literature review). Use `deep` only when the user explicitly asks for an exhaustive review. |
| filters | object | No | Same structured filters as the search tool. |
| attachments | object | No | `{"paper_attachments": [{"paper_id": "...", "es_hash_paper_id": "..."}], "collection_ids": [123]}`. |

Returns a dispatch confirmation with `status` `running`, plus `thread_id`, `interaction_id`, `mode`, `url`, `poll_after_seconds`, `max_wait_seconds`, and `next_steps`.

### add_to_thread

Adds a new follow-up interaction to an existing thread.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| thread_id | string | Yes | The `thread_id` returned by `create_thread`. |
| input_message | string | Yes | A new follow-up the user raised after seeing the previous result. Do not use this to continue your own plan. |
| mode | string | No | Same as `create_thread`. |
| title | string | No | Thread title from `create_thread`; used only for the deep-link label. |
| filters | object | No | Same as `create_thread`. |
| attachments | object | No | Same as `create_thread`. |

Returns the same dispatch confirmation as `create_thread`.

### get_thread

Polls a research thread and returns the grounded answer when ready.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| thread_id | string | Yes | The `thread_id` returned by `create_thread`. |
| interaction_id | string | No | Hydrate only this interaction, for example the one returned by `create_thread`. Omit to hydrate the latest interaction. Returns an error if the id is not in the thread. |
| include_trace | boolean | No | Include a textual `agent_trace` and the raw `agent_trace_raw` graph for each interaction. Default is `false`. |

The top-level response contains:

<ResponseField name="thread_id" type="string">The thread id.</ResponseField>
<ResponseField name="title" type="string">Thread title.</ResponseField>
<ResponseField name="filename" type="string">Sanitized filename for saving the `document`.</ResponseField>
<ResponseField name="status" type="string">`idle` (ready), `running` (in progress), or `failed`.</ResponseField>
<ResponseField name="url" type="string">Deep link to the thread in Consensus.</ResponseField>
<ResponseField name="message_for_user" type="string">Status message with the Consensus link.</ResponseField>
<ResponseField name="display_first" type="boolean">Always `true`; reproduce this message before any other output.</ResponseField>
<ResponseField name="interactions" type="array">List of interactions.</ResponseField>

Each interaction contains:

<ResponseField name="interaction_id" type="string">The interaction id.</ResponseField>
<ResponseField name="input_message" type="string">The prompt for this turn.</ResponseField>
<ResponseField name="created_at" type="string">When the interaction was created.</ResponseField>
<ResponseField name="search_mode" type="string">Backend search mode value.</ResponseField>
<ResponseField name="mode" type="string">`pro`, `deep`, or `quick` for legacy `SUMMARY` threads.</ResponseField>
<ResponseField name="status" type="string">`idle`, `running`, or `failed`.</ResponseField>
<ResponseField name="filters" type="object">Structured filters used for the turn.</ResponseField>
<ResponseField name="full_text_paper_ids" type="array">Paper ids used as full-text context.</ResponseField>
<ResponseField name="response" type="string">Clean markdown answer with hyperlinked `[N]` citation markers.</ResponseField>
<ResponseField name="document" type="string">Ready-to-write markdown file with a `## References` section. Only present when `status` is `idle` and citations were hydrated successfully.</ResponseField>
<ResponseField name="citations" type="array">Hydrated paper metadata with `n`, `title`, `authors`, `year`, `journal`, `doi`, `url`, `paper_id`, and `snippets`.</ResponseField>
<ResponseField name="cited_papers" type="array">Compact `rank` to `paper_id` mapping.</ResponseField>
<ResponseField name="stats" type="object">PRISMA-style counts: `retrieved`, `eligible`, `included`.</ResponseField>
<ResponseField name="step_count" type="integer">Number of visible agent trace nodes.</ResponseField>
<ResponseField name="agent_trace" type="string">Text summary of the agent trace. Only present when `include_trace` is `true`.</ResponseField>
<ResponseField name="agent_trace_raw" type="object">Full raw agent graph. Only present when `include_trace` is `true`.</ResponseField>

When an interaction is `running`, `document` is omitted, `citations` is empty, and `response` is empty. When citation hydration fails, `document` is withheld so a degraded result is not marked ready.

<Tip>
Wait at least 30 seconds between `get_thread` calls. Pro results typically finish within ~3 minutes; Deep results may take up to ~10 minutes. Polling faster returns cached `running` results and does not speed up the agent.
</Tip>

### find_threads

Lists the signed-in user's research threads.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| query | string | No | Optional title substring search. Leave empty to list all threads. |
| limit | integer | No | Maximum threads to return. Default `20`, max `100`. |
| offset | integer | No | Pagination offset. Default `0`. |

Returns `threads` and `has_more`. Each thread includes `thread_id`, `title`, `status` (`idle`, `running`, `failed`, or `unknown`), `preview`, `interaction_count`, `last_activity_at`, and `url`.

## Troubleshooting

<AccordionGroup>
Expand Down