`count_materials` tool

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". It needs one of these grants: professional_database or trial_database. Each call uses one unit of the daily allowance.

At a glance
Tool	`count_materials`
Title	Count materials
Group	Find materials
Needs one of	`professional_database` or `trial_database`
Charged	Yes, against the daily allowance
Read-only	Yes
Parameters	2, of which 0 required
Data as of	2026-10-04
Server release	1.5.0, read from the live server on 2026-10-04

What parameters does count_materials take?

Parameters of `count_materials`
Parameter	Type	Required	Default	What it does
`criteria`	`string`	No	`""`	The conditions to count, in plain language, parsed exactly as the query of search_materials is. Empty (the default) counts every material in the dataset. A database named in the text, such as "in the semiconductor database", is honoured.
`source_id`	`string` or null	No	not set	Dataset to count in, an `id` from list_material_sources. Null (the default) follows the same rule as search_materials. Compare `source` with `requested_source` in the response: they differ when your account cannot reach the dataset asked for, and the count then describes `source`. An id that is not in the catalogue falls back to the registry default without an error.

Which grants does count_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.

Annotations the server sets on `count_materials`
Annotation	Value	Meaning
`destructiveHint`	false	If true, the tool may make destructive updates. It matters only when the tool is not read-only.
`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 count_materials look like?

A count with two property limits.

Example arguments for count_materials

{
  "criteria": "band gap between 3 and 5 eV and energy above hull below 0.1 eV/atom"
}

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

Convention. count is None when the count did not run, and exactly one of not_countable, clarification_needed or property_offer says why. A count of 0 is a real answer; None is not one.
Convention. Every call is charged against the daily allowance, including a call with empty criteria. The charge is taken before the work runs and is refunded only when the reply is a clarification question.
Gap. Criteria that SQL cannot evaluate (cost, material class, form factor, operating conditions, and properties computed at query time) are not countable. They come back as not_countable; search_materials can evaluate them.

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

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

Count the materials that meet some criteria and return ONE exact number, use this instead of search_materials whenever the question is "how many": "how many materials have a band gap between 3 and 5 eV and energy above hull below 0.1 eV/atom", "how many materials are in the semiconductor database".

criteria is natural language, parsed exactly as search_materials parses its query; leave it empty to count every material in the database. The count is exact, each material's best-source value is tested, the same rule search_materials applies, and is never "too broad": 15,000 matches is an answer here, not a request to narrow.

count is None when the count did not run, and exactly one of these says why: not_countable (a criterion SQL cannot evaluate: cost, material class, form factor, operating conditions, or a property computed at query time, all of which search_materials can evaluate), clarification_needed (the criteria are too ambiguous to count; it carries the question that would resolve them), or property_offer (as on search_materials, a note written to be shown as is).

source_id picks a dataset from list_material_sources; a database named in criteria ("in the semiconductor database") is honoured too. Check source against requested_source: they differ when this account may not reach the database asked for, and the count then describes source, not the one named.

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

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.

The Tool reference lists every tool.

count_materials tool