Skip to main content
Chemia Discovery
Browse the documentation

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 is not charged against the daily allowance.

At a glance
Toolget_result_set
TitleGet result set
GroupWork with a result set
ChargedNo
Read-onlyYes
Parameters3, of which 1 required

What parameters does get_result_set take?

Parameters of get_result_set
ParameterTypeRequiredDefaultWhat it does
result_set_idstringYesnoneThe 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.
limitintegerNo50Rows per page, capped at 50; values below 1 are raised to 1. limit_applied and notice show what was used.
offsetintegerNo0Index 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.

Does get_result_set use my daily allowance?

  • Charged: no, it never uses the daily allowance.
  • Who can call it: your client lists the tools your account is entitled to, so a tool appears only when you can use it.

The allowance and the account rules are explained in Access and limits.

Annotations the server sets on get_result_set
AnnotationValueMeaning
idempotentHinttrueIf true, calling the tool again with the same arguments has no additional effect.
openWorldHintfalseIf true, the tool may interact with an open world of external entities.
readOnlyHinttrueIf 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 show how a call is written and validate against the tool's input schema.

How should I read get_result_set results?

  • Good to know. total_survivors is the true match count of the original search. retrievable is how many matches were stored 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.
  • Check this. Owning a result set is not enough. A set that came from a restricted dataset stops being readable if your account no longer holds full-dataset access, even though the rows were yours when the search ran.

"Good to know" explains a field whose meaning is not obvious, "Check this" marks a result that can look right and still mislead, and "Coverage note" says what the data does not cover. Reading results explains all three.

How does the server describe get_result_set?

This is the description an assistant sees for the tool.

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