Skip to main content
Chemia Discovery
Browse the documentation

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". Each call uses one unit of the daily allowance.

At a glance
Toolcount_materials
TitleCount materials
GroupFind materials
ChargedYes, against the daily allowance
Read-onlyYes
Parameters2, of which 0 required

What parameters does count_materials take?

Parameters of count_materials
ParameterTypeRequiredDefaultWhat it does
criteriastringNo""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_idstring or nullNonot setDataset 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.

Does count_materials use my daily allowance?

  • Charged: yes, each call uses one unit of the daily allowance.
  • Who can call it: your client lists the tools your account is entitled to, so a tool appears only when you can use it.

The allowance and the account rules are explained in Access and limits.

Annotations the server sets on count_materials
AnnotationValueMeaning
destructiveHintfalseIf true, the tool may make destructive updates. It matters only when the tool is not read-only.
idempotentHinttrueIf true, calling the tool again with the same arguments has no additional effect.
openWorldHintfalseIf true, the tool may interact with an open world of external entities.
readOnlyHinttrueIf 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 show how a call is written and validate against the tool's input schema.

How should I read count_materials results?

  • Good to know. 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.
  • Good to know. 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.
  • Coverage note. 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.

"Good to know" explains a field whose meaning is not obvious, "Check this" marks a result that can look right and still mislead, and "Coverage note" says what the data does not cover. Reading results explains all three.

How does the server describe count_materials?

This is the description an assistant sees for the tool.

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.