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).
| 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 |
| 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
- Look up a material
- Property distributions and coverage
- Work with a result set
- Explore the knowledge graph
- Orient yourself
- Computed on demand
Grants, charges and limits are explained in Access, grants and limits.
What is in the group "Find materials"?
Search the corpus with a plain-language query, or count how many materials meet some criteria.
| Tool | What it does | Needs one of | Charged | Parameters |
|---|---|---|---|---|
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 | 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.
| 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 | 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 | 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.
| Tool | What it does | Needs one of | Charged | Parameters |
|---|---|---|---|---|
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.
| 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 | 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 | 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.
| 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.
| 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 | 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.
| 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. It holds every tool's parameters, example arguments, grants, charge and reading notes, as of 2026-10-04.