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

# Document Search

> search_documents finds research, news, and curated source documents relevant to a question, with the content and citations attached.

`search_documents` is the qualitative tool. Your assistant hands it a question in plain language, and it
searches research, news, and curated sources for the documents relevant to that question, then returns the
documents themselves.

**It retrieves; it does not write the answer.** Your assistant reads the documents and answers from them. That is
why a result is a document set rather than a paragraph, and why you can always ask which document a claim rests on.

Reach for it when the answer is written down somewhere rather than sitting in a table: what a protocol does, what
changed in a launch, how an event played out, what has been published on a theme.

## What comes back

`sources` holds the retrieved documents. Each one carries:

| Field          | What it is                                                                                                                                                   |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `domain`       | Where the document came from. Values include `research`, `news`, `external_news`, `diligence`, `governance`, `twitter`, and `video_transcript`, among others |
| `title`        | The document title                                                                                                                                           |
| `url`          | A link back to the original                                                                                                                                  |
| `content`      | The document text your assistant reads and quotes from                                                                                                       |
| `published_at` | When it was published, on the domains that carry a date                                                                                                      |

`error` is set only when a run finds no usable document, and explains why.

Because `url` and `published_at` travel with every document, you can ask your assistant to cite what it used and
verify an answer is grounded in a real source rather than in the model's own knowledge.

## Example queries

Phrase these to your assistant directly, and it decides to call the tool.

### Concepts and protocols

```text theme={null}
What is EigenLayer restaking?
```

```text theme={null}
Explain Uniswap v4's new features.
```

### News and events

```text theme={null}
Latest news about Ethereum.
```

```text theme={null}
What happened with FTX?
```

### Market and sector coverage

```text theme={null}
Recent DeFi funding rounds this month.
```

The last two work, but they are exactly the phrasings the Tip below improves on. Swapping "latest" and "this
month" for the dates you actually mean narrows the document set considerably.

## Best practices

<Tip>
  The corpus spans years, and the search reads the time window out of your wording. Name concrete dates whenever the
  question is time-sensitive: "in August 2026" or "since 2026-08-01", not "latest" or "recently". A query with no
  date returns the best matches from the whole corpus, most of which will be old.
</Tip>

* **Ask one thing at a time.** Several focused searches usually beat one loaded question.
* **Name the entity precisely.** "Uniswap v4" and "Uniswap" pull different documents.
* **Ask for sources.** Requesting the URLs makes it obvious which documents an answer rests on.

## When to use something else

* You want a number that is true right now, such as a price, a ranking, or a TVL figure. Use the
  [tabular tools](/mcp/tools/datasets).
* You want a numeric series at a stated granularity over an exact window. Use the
  [timeseries tools](/mcp/tools/timeseries).

<Note>
  Which sources your key can reach follows its entitlements. If a search comes back thin, the material may sit
  outside what your key covers rather than outside the platform.
</Note>

More prompt patterns, grouped by use case, are on [What to ask](/mcp/prompts).