# `show_eliminated` tool

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

**Parameters of `show_eliminated`**

| Parameter | Type | Required | Default | What it does |
| --- | --- | --- | --- | --- |
| `set_id` | `string` | Yes | none | The `result_set_id` of an earlier search, or of a set derived from one. Only result sets created by your own account are readable. |
| `constraint` | `string` or null | No | not set | Keeps only eliminations whose constraint name or stage contains this text, ignoring case: "thermal" matches "thermal_conductivity". Null (the default) shows every eliminated candidate. |
| `limit` | `integer` | No | `20` | How many candidates to return, capped at 50. There is no offset: use a narrower `constraint` to reach others. |

## Which grants does show_eliminated 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 `show_eliminated`**

| 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 show_eliminated look like?

The ten closest misses on one constraint.

```json Example arguments for show_eliminated
{
  "set_id": "3f2b8e9a-0c1d-4e7f-9a6b-5d4c3b2a1f00",
  "constraint": "band_gap",
  "limit": 10
}
```

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 show_eliminated results?

- **Convention.** `total` is how many materials were eliminated; `stored` is how many the set kept to show, which for a search is the closest 50 per constraint. `total`, not `stored`, answers "how many failed".
- **Convention.** Candidates are sorted by `violation_amount`, the shortfall in the property's `unit` to four significant figures. A candidate removed for lacking a value has no violation amount and is listed after every measured near miss.

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 show_eliminated?

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

List candidates an earlier search eliminated from `set_id`, sorted by violation_amount ascending (closest miss first), "how close did the near-misses come", not the survivors search_materials/ get_result_set already return.

constraint filters to eliminations matching that name or stage (substring, case-insensitive), e.g. "thermal" matches "thermal_conductivity". Omit it to see every eliminated candidate.

`total` is how many materials were eliminated (on that constraint, or on all): the search's own ledger count, plus every elimination a refine_result_set made. `stored` is how many of them the result set kept to show (the search keeps its closest 50 per constraint), and `limit` (max 50) is how many come back; there is no offset, so a narrower `constraint` reaches others. `total`, not `stored`, is "how many failed". Each candidate carries its `chemia_id` (the id users see; `material_id` is internal), `violation_amount` to four significant figures, and the property's `unit`.

limit is capped at 50 (MAX_ROWS) regardless of what's asked for, the same context-budget ceiling as this server's other tools; check `limit_applied`/`notice` rather than assuming the count matches what was asked for. Only a result set this account owns AND is still entitled to the source of can be read here, same rule as get_result_set.

## Which tools are related to show_eliminated?

show_eliminated 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.
- [`get_result_set`](https://www.chemiadiscovery.com/docs/mcp/tools/get_result_set/): 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.
- `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.

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

---

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

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)