search_materials tool

What parameters does search_materials take?

Which grants does search_materials need, and is it charged?

• Grants: professional_database or trial_database. One of them is enough.
• Charged: yes, each call uses one unit of the daily allowance (as of 2026-10-04).

Grants and the allowance are explained in Access, grants and limits.

What does a call to search_materials look like?

A two-property search that returns ten rows.

{
  "query": "semiconductors with a band gap between 1.1 and 1.6 eV and bulk modulus above 100 GPa",
  "max_results": 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 says where worked examples stand.

How should I read search_materials results?

• Convention. There are three different counts. total_survivors is the exact number of matches. results holds at most 50 of them, and truncated is true when it holds fewer than the total. Up to 5000 matches are stored for get_result_set; rows beyond that were counted but never stored. A query judged to match that many or more, or a scan that runs out of time, is not answered with rows: the reply is clarification_needed with a size estimate and ways to narrow it, and the call is refunded.
• Trap. Check source in every response. A source_id that is misspelt or not in the catalogue raises no error: it resolves to the registry default, the small trial subset, and requested_source then names that default too, so only a comparison with the id you sent shows the swap. A restricted dataset that was inferred from the query text, or taken as the server default, is narrowed to the trial subset without an error when your account lacks the professional_database grant; there requested_source differs from source.
• Gap. A search can answer only part of a question without saying so. A condition the parser cannot map to a property it knows (for example coercivity) is dropped: it is not in the parsed constraints, it has no constraint_ledger entry, and the matches reflect only the other conditions. Its only trace is a sentence in constraints.open_questions, and clarification_needed and notice stay empty. Compare the parsed constraints with what you asked. A ledger entry with state not_supported is the intended signal for a condition that is parsed but cannot be checked; extending it to dropped conditions is a planned fix, not current behaviour. Today it appears only for a parsed constraint whose property is outside the vocabulary or whose kind this server does not enforce (such as a cost ceiling or a material class); it never carries a count. Entries with state no_data count materials left out only because they have no measurement of that property.

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 explains the classes.

How does the server describe search_materials?

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

Search Chemia's materials corpus with a natural-language constraint query, for example "semiconductors with a band gap between 1.1 and 1.6 eV and bulk modulus above 100 GPa".

Returns the matching materials, the constraints parsed from the query, elimination counts, and a result_set_id that get_result_set can page through. If the query is too ambiguous to run, returns clarification_needed instead of guessing.

If a property named in the query has zero or below-threshold corpus coverage, the response carries property_offer instead: its note is prose written to be shown as is, naming the proxy routes that reach the property and their caveats (or, with no usable route, the irreducible verdict and what extraction would take). A ranking by such a property still returns its matches, with a property_offer saying they are not ordered by it, and ordering reads "cursor".

A property value carrying suspect is physically impossible for that property (a negative shear modulus, a density of 1,248 g/cm3): a data error in the corpus, kept with its number so it can be pointed out, and not a measurement. Real extremes (osmium's density, diamond's stiffness) are not flagged.

Every constraint is applied together in one query. eliminations holds that query's totals: matched is the number of materials meeting every constraint (equal to total_survivors) and eliminated the rest of the dataset. How many each constraint removed is in constraint_ledger.

Ranking by how much of an element a material contains works directly: "rank Sc compounds by Sc content" returns the highest atomic fraction first (weight fraction if the query says by weight), ranked across the whole match, with the value in each row's metadata element_fraction.

Rows come most stable first (lowest energy above hull, entries without one last) unless the query asks for a sort; ordering says which. That is an order, not a ranking; score_results ranks.

source_id picks a dataset from list_material_sources ("trial", "production") explicitly; a database named only in the query text is not guaranteed to be selected.

Compound classes are exact: "nitrides", "oxides", "sulfides", "halides" and the like mean compounds of two or more elements in which that element is the anion. So "nitrides" excludes N2 and nitrates, and "sulfides" excludes sulfates. Say "contains N" in the query to mean mere presence instead.

Searches cover real solids by default: frozen gases (N2, O2, He) and compounds of nonmetals alone (NH3, CO, H2O, organic crystals) are left out, and a real_solids entry in constraint_ledger says so. Say "including molecular solids" in the query to keep them.

constraint_ledger covers every constraint that is not a plain property threshold (cost ceiling, material class, operating conditions, form factor, composition, a "top N" sort). Each entry's state is applied (enforced; count is how many candidates it eliminated), not_supported (a parsed constraint that this server does not check, so no count is given: it means "not tracked", not "none match"; a condition the parser cannot map at all is dropped and shows only in constraints.open_questions), or no_data (candidates excluded from a real property check only for lacking that measurement: not a constraint failure, and not part of a same-property applied count). Plain thresholds are counted in eliminations.

max_results is capped at 50 per response; limit_applied and notice say when fewer came back than were asked for, and get_result_set pages through the rest.

Which tools are related to search_materials?

search_materials is in the group "Find materials". The other tools in it:

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

The Tool reference lists every tool.