# `resolve_material_name` tool

Resolves a commercial or common name, a formula or a Chemia ID to one canonical material, with its Chemia ID, formula and dataset. 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 | `resolve_material_name` |
| Title | Resolve material name |
| Group | [Look up a material](https://www.chemiadiscovery.com/docs/mcp/tools/#what-is-in-the-group-look-up-a-material) |
| Needs one of | `professional_database` or `trial_database` |
| Charged | No |
| Read-only | Yes |
| Parameters | 2, 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 resolve_material_name take?

**Parameters of `resolve_material_name`**

| Parameter | Type | Required | Default | What it does |
| --- | --- | --- | --- | --- |
| `name` | `string` | Yes | none | What to resolve: a common name such as "sapphire", a formula such as Al2O3, a Chemia ID such as CH-MAT-1599, or an internal id. Resolution tries the Chemia ID, then the internal id, then the name table (which pins one structure for a known name), then a formula match in the dataset. |
| `source_id` | `string` or null | No | not set | Dataset to resolve in, an `id` from list_material_sources. Null (the default) uses the server's default dataset. `source`, `requested_source` and `source_downgraded` in the response say what ran. An id that is not in the catalogue falls back to the registry default without an error. |

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

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

A common name.

```json Example arguments for resolve_material_name
{
  "name": "sapphire"
}
```

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

- **Convention.** The tool answers with one material by design. A formula that fits several structures returns status "ambiguous" with up to 8 candidates, the full `total` and the `ground_state`. The candidates are in Chemia ID order, not stability order, so the first is not the most stable; find_material_entries lists every entry.
- **Trap.** A common name is pinned to one specific structure. When that structure is not in the dataset you queried, the lowest-energy entry of the formula in that dataset stands in, so the Chemia ID returned can be a different structure than the name usually means.

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

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

Resolve a commercial or common material name to one canonical material, for example "sapphire" -> "Al2O3".

Returns that material's `chemia_id` (the user-facing Chemia identifier), its canonical formula, and the `dataset_tag` it belongs to. status is "found" (exactly one match), "ambiguous" (several matched, check `candidates`), or "not_found". This tool answers with ONE material by design; for "how many entries exist for X", that is a different question than this tool answers.

Resolved against the database, so it is dataset-scoped like every other lookup here: source_id explicitly picks a dataset from list_material_sources, and `source`/`source_downgraded` on the response report which one actually ran and whether your request was narrowed.

## Which tools are related to resolve_material_name?

resolve_material_name is in the group "Look up a material". The other tools in it:

- `classify_material`: Classifies materials as metal, semi-metal, semiconductor or insulator from their band gap, one result per input in the same order.
- `find_material_entries`: Lists every entry that matches a formula, a common name or a Chemia ID, with its structure and stability, so you can see all the polymorphs of a compound and pick the one you mean.
- `get_all_material_properties`: Lists every stored property of one material in a single call, each with its value, unit and kind of evidence, plus the material's structure.
- [`get_material_property`](https://www.chemiadiscovery.com/docs/mcp/tools/get_material_property/): Reads one stored property of one material, with its unit, the kind of evidence it comes from, and the material's structure.

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

---

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

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)