# Tool reference

The connector offers 28 tools in 7 groups, all read-only. 8 of them have a full reference page and the others are summarised here. Each entry shows the grants it needs and whether it is charged (as of 2026-10-04).

**At a glance**

| Item | Value |
| --- | --- |
| Tools | 28 |
| Groups | 7 |
| Parameters across all tools (top level) | 79 |
| Read-only tools | 28 of 28 |
| Charged tools | 3: `compute_pourbaix_stability`, `count_materials` and `search_materials` |
| Open to every signed-in account | 2: `list_capabilities` and `list_material_sources` |
| Full reference pages | 8 |
| Machine-readable | [tools.json](https://www.chemiadiscovery.com/docs/mcp/tools.json) |
| Data as of | 2026-10-04 |
| Server release | 1.5.0, read from the live server on 2026-10-04 |

## How are the tools organised?

The tools are grouped by what they are for. Each group below lists its tools with a one-sentence summary, the grants a caller needs (any one of them is enough), whether the call is charged against the daily allowance, and the parameters.

- [Find materials](https://www.chemiadiscovery.com/docs/mcp/tools/#what-is-in-the-group-find-materials)
- [Look up a material](https://www.chemiadiscovery.com/docs/mcp/tools/#what-is-in-the-group-look-up-a-material)
- [Property distributions and coverage](https://www.chemiadiscovery.com/docs/mcp/tools/#what-is-in-the-group-property-distributions-and-coverage)
- [Work with a result set](https://www.chemiadiscovery.com/docs/mcp/tools/#what-is-in-the-group-work-with-a-result-set)
- [Explore the knowledge graph](https://www.chemiadiscovery.com/docs/mcp/tools/#what-is-in-the-group-explore-the-knowledge-graph)
- [Orient yourself](https://www.chemiadiscovery.com/docs/mcp/tools/#what-is-in-the-group-orient-yourself)
- [Computed on demand](https://www.chemiadiscovery.com/docs/mcp/tools/#what-is-in-the-group-computed-on-demand)

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

## What is in the group "Find materials"?

Search the corpus with a plain-language query, or count how many materials meet some criteria.

**Find materials (as of 2026-10-04)**

| Tool | What it does | Needs one of | Charged | Parameters |
| --- | --- | --- | --- | --- |
| [`count_materials`](https://www.chemiadiscovery.com/docs/mcp/tools/count_materials/) | Returns one exact number: how many materials meet some criteria, or how many the dataset holds when no criteria are given. Use it instead of a search whenever the question is "how many". | `professional_database` or `trial_database` | Yes | `criteria`, `source_id` |
| [`search_materials`](https://www.chemiadiscovery.com/docs/mcp/tools/search_materials/) | Finds materials from a plain-language description of the properties and composition you want. Returns up to 50 matching rows, the constraints we understood, how many materials were eliminated, and a result_set_id that the other tools use to page, refine, rank and export the full match. | `professional_database` or `trial_database` | Yes | `query` (required), `max_results`, `source_id` |

## What is in the group "Look up a material"?

Resolve a name, list every entry for a formula, read one property or all of them, and classify materials as metals, semiconductors or insulators.

**Look up a material (as of 2026-10-04)**

| Tool | What it does | Needs one of | Charged | Parameters |
| --- | --- | --- | --- | --- |
| `classify_material` | Classifies materials as metal, semi-metal, semiconductor or insulator from their band gap, one result per input in the same order. | `professional_database` or `trial_database` | No | `materials` (required), `source_id` |
| `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. | `professional_database` or `trial_database` | No | `query` (required), `limit`, `source_id` |
| `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. | `professional_database` or `trial_database` | No | `material` (required), `most_stable`, `source_id` |
| [`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. | `professional_database` or `trial_database` | No | `material` (required), `property` (required), `source_id` |
| [`resolve_material_name`](https://www.chemiadiscovery.com/docs/mcp/tools/resolve_material_name/) | Resolves a commercial or common name, a formula or a Chemia ID to one canonical material, with its Chemia ID, formula and dataset. | `professional_database` or `trial_database` | No | `name` (required), `source_id` |

## What is in the group "Property distributions and coverage"?

See how a property is distributed across a dataset, and find routes to a property we do not hold directly.

**Property distributions and coverage (as of 2026-10-04)**

| Tool | What it does | Needs one of | Charged | Parameters |
| --- | --- | --- | --- | --- |
| [`find_property_proxies`](https://www.chemiadiscovery.com/docs/mcp/tools/find_property_proxies/) | When a property is missing or too thin in the corpus, finds ranked routes that reach it through related properties, with each route's equation, stated error, failure modes and the data we actually hold for its inputs. | `professional_database` or `trial_database` | No | `target_property` (required), `material_id`, `result_set_id`, `max_hops`, `source_id` |
| `plot_distribution` | Returns the histogram and summary statistics of one property across a whole dataset, or across a value range, as data you can draw or describe. | `professional_database` or `trial_database` | No | `property_name` (required), `min_value`, `max_value`, `source_id` |
| `property_stats` | Summarises how one property is distributed across a dataset: how many values and materials there are, the minimum and maximum, the mean and the 5th, 25th, 50th, 75th and 95th percentiles. | `professional_database` or `trial_database` | No | `property_name` (required), `min_value`, `max_value`, `source_id` |

## What is in the group "Work with a result set"?

A search returns its matches as a result set. These tools page through it, show what was eliminated, narrow it, rank it, chart it, compare it with an incumbent and export it.

**Work with a result set (as of 2026-10-04)**

| Tool | What it does | Needs one of | Charged | Parameters |
| --- | --- | --- | --- | --- |
| `benchmark_against` | Compares the top five of a scored result set with a named incumbent material across the properties the set was scored on. | `professional_database` or `trial_database` | No | `result_set_id` (required), `incumbent_name` (required) |
| `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. | `result_set_export` | No | `result_set_id` (required), `format` |
| [`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. | `professional_database` or `trial_database` | No | `result_set_id` (required), `limit`, `offset` |
| `plot_results` | Returns the data behind a chart of an earlier result set (bar, spider or Ashby) for you to draw or describe. | `professional_database` or `trial_database` | No | `result_set_id` (required), `kind` (required), `axis`, `axis_a`, `axis_b`, `top_n` |
| `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. | `professional_database` or `trial_database` | No | `result_set_id` (required), `additional_constraints`, `additional_composition_constraints`, `limit` |
| `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. | `professional_database` or `trial_database` | No | `result_set_id` (required), `sort_by`, `direction`, `primary_constraint`, `weights`, `limit` |
| `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. | `professional_database` or `trial_database` | No | `result_set_id` (required), `weights`, `top_n` |
| [`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. | `professional_database` or `trial_database` | No | `set_id` (required), `constraint`, `limit` |

## What is in the group "Explore the knowledge graph"?

Walk MatKG, the literature-derived knowledge graph: neighbours, paths, applications and substitutes.

**Explore the knowledge graph (as of 2026-10-04)**

| Tool | What it does | Needs one of | Charged | Parameters |
| --- | --- | --- | --- | --- |
| `graph_neighbors` | Lists the entities within a few steps of a material in MatKG, closest first. | `professional_database` or `trial_database` | No | `material` (required), `hops`, `limit` |
| `graph_shortest_path` | Finds the shortest path between two entities in MatKG, step by step. | `professional_database` or `trial_database` | No | `source` (required), `target` (required) |
| `graph_top_connected` | Lists the most connected entities in MatKG, to show what the graph covers before you ask about a specific material. | `professional_database` or `trial_database` | No | `limit` |
| `list_applications` | Lists the applications that MatKG associates with a material, ranked by how often the literature pairs them. | `professional_database` or `trial_database` | No | `material` (required), `limit` |
| `ontology_expand` | Broadens a plain-language request through MatKG into candidate materials, material classes and property filters you can use to build a search. | `professional_database` or `trial_database` | No | `query_text` (required) |
| `ontology_substitutes` | Suggests candidate substitutes for a material from shared applications in MatKG, each with its match in the dataset. | `professional_database` or `trial_database` | No | `material` (required), `application`, `limit`, `source_id` |
| `plot_knowledge_graph` | Builds a hub-and-spoke graph of nodes and edges around one entity from entities you already have, for you to draw. | `professional_database` or `trial_database` | No | `center` (required), `related` (required), `weights`, `title` |

## What is in the group "Orient yourself"?

List the datasets you can query and the capabilities of the wider platform.

**Orient yourself (as of 2026-10-04)**

| Tool | What it does | Needs one of | Charged | Parameters |
| --- | --- | --- | --- | --- |
| `list_capabilities` | Lists what this server and the wider Chemia platform can do, grouped by category. | none (open to every signed-in account) | No | none |
| [`list_material_sources`](https://www.chemiadiscovery.com/docs/mcp/tools/list_material_sources/) | Lists the datasets this server can query, with their ids, descriptions and whether access to them is restricted. | none (open to every signed-in account) | No | none |

## What is in the group "Computed on demand"?

Values that are not stored and are calculated from outside data when you ask.

**Computed on demand (as of 2026-10-04)**

| Tool | What it does | Needs one of | Charged | Parameters |
| --- | --- | --- | --- | --- |
| `compute_pourbaix_stability` | Computes the Pourbaix decomposition energy of a material, its thermodynamic tendency to decompose in water, from Materials Project data. The value is calculated when you ask and is never stored. | `materials_project_data` | Yes | `material` (required), `source_id` |

## Where is the machine-readable reference?

The same data is published as [tools.json](https://www.chemiadiscovery.com/docs/mcp/tools.json). It holds every tool's parameters, example arguments, grants, charge and reading notes, as of 2026-10-04.

---

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

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)