# `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** | Item | Value | | --- | --- | | Tool | `count_materials` | | Title | Count materials | | Group | [Find materials](https://www.chemiadiscovery.com/docs/mcp/tools/#what-is-in-the-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](https://www.chemiadiscovery.com/docs/mcp/access/). **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. ```json 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](https://www.chemiadiscovery.com/docs/mcp/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](https://www.chemiadiscovery.com/docs/mcp/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. ## Which tools are related to count_materials? count_materials is in the group "Find materials". The other tools in it: - [`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. The [Tool reference](https://www.chemiadiscovery.com/docs/mcp/tools/) lists every tool. --- Canonical page: https://www.chemiadiscovery.com/docs/mcp/tools/count_materials/ 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)