# `get_result_set` tool

Pages through the stored matches of an earlier search, up to 50 rows at a time, with the match totals and a next_offset to continue from. It needs one of these grants: `professional_database` or `trial_database`. It is not charged against the daily allowance.

**At a glance**

| Item | Value |
| --- | --- |
| Tool | `get_result_set` |
| Title | Get result set |
| Group | [Work with a result set](https://www.chemiadiscovery.com/docs/mcp/tools/#what-is-in-the-group-work-with-a-result-set) |
| Needs one of | `professional_database` or `trial_database` |
| Charged | No |
| Read-only | Yes |
| Parameters | 3, of which 1 required |
| Data as of | 2026-10-04 |
| Server release | 1.5.0, read from the live server on 2026-10-04 |

## What parameters does get_result_set take?

**Parameters of `get_result_set`**

| Parameter | Type | Required | Default | What it does |
| --- | --- | --- | --- | --- |
| `result_set_id` | `string` | Yes | none | The `result_set_id` returned by search_materials, refine_result_set, score_results or rerank_result_set. Only result sets created by your own account are readable. An id that does not exist and an id that belongs to someone else give the same "not found" error. |
| `limit` | `integer` | No | `50` | Rows per page, capped at 50; values below 1 are raised to 1. `limit_applied` and `notice` show what was used. |
| `offset` | `integer` | No | `0` | Index of the first row to return, starting at 0. Negative values are treated as 0. Use `next_offset` from the previous response; it is null when no rows remain. |

## Which grants does get_result_set need, and is it charged?

- **Grants:** `professional_database` or `trial_database`. One of them is enough.
- **Charged:** no, it never uses the daily allowance (as of 2026-10-04).

Grants and the allowance are explained in [Access, grants and limits](https://www.chemiadiscovery.com/docs/mcp/access/).

**Annotations the server sets on `get_result_set`**

| Annotation | Value | Meaning |
| --- | --- | --- |
| `idempotentHint` | true | If true, calling the tool again with the same arguments has no additional effect. |
| `openWorldHint` | false | If true, the tool may interact with an open world of external entities. |
| `readOnlyHint` | true | If true, the tool does not modify its environment. |

## What does a call to get_result_set look like?

The second page of twenty rows of an earlier search.

```json Example arguments for get_result_set
{
  "result_set_id": "3f2b8e9a-0c1d-4e7f-9a6b-5d4c3b2a1f00",
  "limit": 20,
  "offset": 20
}
```

These arguments validate against the tool's input schema, checked when the snapshot was taken on 2026-10-04. They show the shape of a call; they are not a recorded response. [Examples](https://www.chemiadiscovery.com/docs/mcp/examples/) says where worked examples stand.

## How should I read get_result_set results?

- **Convention.** `total_survivors` is the true match count of the original search. `retrievable` is how many matches were stored, up to 5000, and is the number you can page through. `truncated_at_persist` is true when the search matched more than were stored; no offset reaches those rows.
- **Trap.** Owning a result set is not enough. A set that came from a restricted dataset stops being readable if your account no longer holds the professional_database grant, even though the rows were yours when the search ran.

A Convention is a field or behaviour whose meaning is not obvious, a Trap looks right and is not, and a Gap is something we do not hold or do not check. [Reading results](https://www.chemiadiscovery.com/docs/mcp/reading-results/) explains the classes.

## How does the server describe get_result_set?

This is the server's own description, which a client passes to the model, lightly normalised for display.

Page through the full survivor list of an earlier search, using the result_set_id that search_materials returned. Only result sets created by this server are readable.

limit is capped at 50 (MAX_ROWS) regardless of what's asked for, the same context-budget ceiling search_materials applies, since this result also lands directly in the model's context. Walk offset -> next_offset (returned on every call, None once there is nothing left) to page through everything up to `retrievable`; check `limit_applied`/`notice` on the response rather than assuming a page holds as many rows as requested.

## Which tools are related to get_result_set?

get_result_set is in the group "Work with a result set". The other tools in it:

- `benchmark_against`: Compares the top five of a scored result set with a named incumbent material across the properties the set was scored on.
- `export_result_set`: Prepares a CSV or JSON file of an earlier result set's full stored match list and returns a download link and a resource to read it from.
- `plot_results`: Returns the data behind a chart of an earlier result set (bar, spider or Ashby) for you to draw or describe.
- `refine_result_set`: Narrows an earlier search's stored matches with extra property limits or element filters, without re-running the search. Returns a new result set; the original is unchanged.
- `rerank_result_set`: Re-orders an earlier result set, either by one property or by a new weighting of its constraints, and returns a new result set.
- `score_results`: Ranks an earlier search's stored matches by a weighted score across its constraints and returns a new result set whose rows are in ranked order.
- [`show_eliminated`](https://www.chemiadiscovery.com/docs/mcp/tools/show_eliminated/): Shows the candidates an earlier search eliminated, closest miss first, so you can see how near each one came to passing.

The [Tool reference](https://www.chemiadiscovery.com/docs/mcp/tools/) lists every tool.

---

Canonical page: https://www.chemiadiscovery.com/docs/mcp/tools/get_result_set/

Data as of 2026-10-04. Server release 1.5.0, read from the live server on 2026-10-04.

Tool reference as JSON: https://www.chemiadiscovery.com/docs/mcp/tools.json

[Site FAQ](https://www.chemiadiscovery.com/faq) | [Website privacy policy](https://www.chemiadiscovery.com/privacy) | [Website terms of use](https://www.chemiadiscovery.com/terms) | [Contact support](mailto:info@chemiadiscovery.com)