> ## Documentation Index
> Fetch the complete documentation index at: https://docs.consensus.app/llms.txt
> Use this file to discover all available pages before exploring further.

# search

> The Consensus MCP search tool: find ranked, peer-reviewed papers for a query in one call, with academic filters.

`search` finds peer-reviewed papers for a query and returns them ranked, in one call. Your assistant reads the papers and writes the answer. It's the right tool for lookups and for questions your assistant can answer from a list of papers.

For a question that needs several research steps and a written, cited answer, use [`create_thread`](/mcp-tools/create-thread) instead. See [Search vs Threads](/mcp-tools/quickstart#search-vs-threads).

`search` works without an account at reduced limits. ChatGPT Deep Research may call it several times with different queries and filters while it builds a report.

## Parameters

Every parameter except `query` is optional.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `query` | string | Yes | The research question or topic, up to 500 characters. Use specific academic terminology for best results. |
| `year_min` | integer | No | Exclude papers published before this year. |
| `year_max` | integer | No | Exclude papers published after this year. |
| `month_min` | integer | No | Minimum publication month (1–12). Use with `year_min`. |
| `month_max` | integer | No | Maximum publication month (1–12). Use with `year_max`. |
| `study_types` | string array | No | Filter by study design. Values: `rct`, `meta-analysis`, `systematic review`, `literature review`, `case report`, `non-rct experimental`, `non-rct observational study`, `non-rct in vitro`, `animal`. |
| `sjr_max` | integer | No | Maximum journal quartile (SCImago Journal Rank). `1` is Q1 (highest), `4` is Q4. Set to `1` for Q1 journals only. |
| `sjr_min` | integer | No | Minimum journal quartile. Excludes better (lower-number) quartiles. For example, set to `2` to keep Q2–Q4. |
| `human` | boolean | No | Set to `true` to include only studies involving human subjects. |
| `controlled` | boolean | No | Set to `true` to include only controlled studies. |
| `sample_size_min` | integer | No | Exclude studies with fewer participants than this number. |
| `citation_min` | integer | No | Exclude papers with fewer citations than this number. |
| `medical_mode` | boolean | No | Set to `true` for clinical, medical, or evidence-based medicine questions. Limits results to top medical journals and clinical guidelines. |
| `exclude_preprints` | boolean | No | Set to `true` to return peer-reviewed papers only. |
| `open_access` | boolean | No | Set to `true` to include only open-access papers. |
| `duration_min` | integer | No | Minimum study duration in days. Useful for longitudinal or long-term studies. |
| `duration_max` | integer | No | Maximum study duration in days. |
| `country` | string | No | Comma-separated ISO 3166-1 alpha-2 country codes (for example `us,gb`) to limit to those countries of study. Unknown codes are ignored. |
| `publisher_name` | string | No | Comma-separated publisher names, for example `Elsevier`. |
| `journal_name` | string | No | Preferred journal, for example `Nature`. Boosts matching papers without excluding others. |
| `domain` | string | No | Comma-separated academic field codes, for example `med` or `bio,cs`. |
| `page` | integer | No | Zero-indexed result page, up to `49`. Pages after the first need a paid plan. |
| `page_size` | integer | No | Results per page. Defaults to 20, capped by your plan. |
| `include_full_text_chunks` | boolean | No | Set to `true` to include query-relevant [full-text excerpts](/api-full-text). Paid plans only. |

## Response

`search` returns a text payload written for AI agents: the ranked papers (title, link, authors, year, citation count, journal, and abstract), plus instructions to cite each paper inline by its number.

```text theme={null}
Found 20 papers, showing top 20.

[1] [Caffeine and endurance performance: a meta-analysis](https://consensus.app/papers/details/3f1c.../?utm_source=claude_code) (Smith et al., 2021, 154 citations, Sports Medicine, DOI: 10.1007/s40279-021-01470-1)
  Abstract text...

[2] ...

IMPORTANT INSTRUCTIONS: When discussing these findings, you MUST cite papers inline using their numbered references, e.g. [1], [2]. ...
```

Paid plans also get DOIs and, with `include_full_text_chunks`, full-text excerpts. In ChatGPT, results appear in the Consensus widget.

<Note>
  Need structured JSON? Use the [Consensus API](/api-quickstart-search), which shares your monthly allowance with MCP.
</Note>

## Example prompts

* "What does the research say about the effectiveness of remote work on productivity?"
* "Find RCTs and meta-analyses since 2020 on cognitive behavioral therapy for anxiety"
* "Search for high-quality human studies on gut microbiome and mental health with at least 100 participants"
* "Recent research on large language model hallucination from top-tier journals"

## Good to know

* **Cost:** one call per 100 papers returned, rounded up, with a minimum of one call per search. See [plans and access](/mcp-plans-and-access#how-calls-are-counted).
* **Papers per search:** your plan sets the maximum `page_size`, from 3 without an account up to 1,000 on Enterprise.
* **Rate limits:** set by your plan. See [plans and access](/mcp-plans-and-access#what-each-plan-includes).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.