`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
Tool	`get_result_set`
Title	Get result set
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.

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.

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 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 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.

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: Shows the candidates an earlier search eliminated, closest miss first, so you can see how near each one came to passing.

The Tool reference lists every tool.

get_result_set tool