openfda-mcp-server

Openfda Count Values

openfda_count_values

Read-only

Aggregate and tally unique values for any field across any openFDA endpoint. Returns ranked term-count pairs sorted by count descending; a date field tallies one term per distinct YYYYMMDD date, ranked the same way. Pair with openfda_search_adverse_events, openfda_search_drug_approvals, openfda_search_device_clearances, openfda_search_recalls, openfda_get_drug_label, or openfda_lookup_ndc when sample records help interpret the aggregates.

Input Schema

Name	Required	Description
`count`	Yes	Field to count. openfda_describe_fields gives the verified expression per field as countAs (null = not countable in any form). Otherwise: append .exact for whole-phrase counting of free-text fields (e.g. "patient.reaction.reactionmeddrapt.exact"); count identifier fields openFDA already indexes as keywords (product_ndc, application_number, pma_number) bare — .exact on those is rejected as not countable. A date field (receivedate, report_date, decision_date) is counted bare and yields one term per distinct YYYYMMDD date.
`limit`	No	Number of top terms to return (default 100, max 1000 — openFDA's own count maximum). truncated reports whether more distinct terms exist beyond it, except at the maximum itself, where openFDA offers no way to tell. A date field is the exception: openFDA sends every date, so the tool ranks them all and truncated is exact at any limit; scope search to at most limit dates to list each one.
`search`	No	Filter query to scope the count (e.g. patient.drug.medicinalproduct:"metformin"). Omit to count across every record in the endpoint. Separate clauses with spaces. A "+" written in the URL style of openFDA's examples also reads as a space where it separates: beside AND, OR, NOT, or TO, after a closing quote, paren, or bracket, or between a term and the next "field:" prefix (a:"x"+AND+b:"y", [20200101+TO+20201231], c:x+d:y). In a query that marks a clause required with a leading +field:, only the AND/OR/NOT/TO positions read that way. Any other "+" is sent as written, and inside a quoted phrase "+" is a literal plus sign. Double quotes, parentheses, and range brackets must balance, and the query must not end on a backslash — each is rejected before the request.
`endpoint`	Yes	Full openFDA endpoint path (e.g. "drug/event", "device/classification")

Output Schema

Name	Required	Description
`cap`	No	The limit applied to the term list.
`meta`	No	Response metadata
`error`	No	Present when the call failed. Absent on success.
`shown`	No	Number of terms returned in this response.
`notice`	No	Why the tally is empty — the search matched no records, or the matched records carry no value for the field — and how to widen it; when truncated, how to reach the omitted terms (on a date field, how many distinct dates were counted); at the 1000-term maximum, that openFDA cannot show whether more distinct values exist; how many count rows openFDA sent without a value or numeric count, which are left out. Absent when a complete list is returned.
`results`	No	Term-count pairs sorted by count descending
`termCount`	No	Number of distinct terms returned
`truncated`	No	True when at least one more distinct term exists beyond the limit. Absent when the list is complete, and at the 1000-term maximum, where openFDA cannot show whether more exist (notice says so). Exact at any limit on a date field, where every date arrives.
`truncationCeiling`	No	Count of the lowest-ranked term returned — omitted terms fall at or below it.

Schema Changelog

Changes observed during successful MCP inspections.

Changed6 schema fields changedOct 26, 2026

changedInput schema / properties / count / description

Previous value: -"Field to count. openfda_describe_fields gives the verified expression per field as countAs (null = not countable in any form). Otherwise: append .exact for whole-phrase counting of free-text fields (e.g. \"patient.reaction.reactionmeddrapt.exact\"); count identifier fields openFDA already indexes as keywords (product_ndc, application_number, pma_number) bare — .exact on those is rejected as not countable."New value: +"Field to count. openfda_describe_fields gives the verified expression per field as countAs (null = not countable in any form). Otherwise: append .exact for whole-phrase counting of free-text fields (e.g. \"patient.reaction.reactionmeddrapt.exact\"); count identifier fields openFDA already indexes as keywords (product_ndc, application_number, pma_number) bare — .exact on those is rejected as not countable. A date field (receivedate, report_date, decision_date) is counted bare and yields one term per distinct YYYYMMDD date."

changedInput schema / properties / limit / description

Previous value: -"Number of top terms to return (default 100, max 1000 — openFDA's own count maximum). truncated reports whether more distinct terms exist beyond it, except at the maximum itself, where openFDA offers no way to tell."New value: +"Number of top terms to return (default 100, max 1000 — openFDA's own count maximum). truncated reports whether more distinct terms exist beyond it, except at the maximum itself, where openFDA offers no way to tell. A date field is the exception: openFDA sends every date, so the tool ranks them all and truncated is exact at any limit; scope search to at most limit dates to list each one."

changedInput schema / properties / search / description

Previous value: -"Filter query to scope the count (e.g. patient.drug.medicinalproduct:\"metformin\"). Omit to count across every record in the endpoint. Double quotes, parentheses, and range brackets must balance, and the query must not end on a backslash — each is rejected before the request."New value: +"Filter query to scope the count (e.g. patient.drug.medicinalproduct:\"metformin\"). Omit to count across every record in the endpoint. Separate clauses with spaces. A \"+\" written in the URL style of openFDA's examples also reads as a space where it separates: beside AND, OR, NOT, or TO, after a closing quote, paren, or bracket, or between a term and the next \"field:\" prefix (a:\"x\"+AND+b:\"y\", [20200101+TO+20201231], c:x+d:y). In a query that marks a clause required with a leading +field:, only the AND/OR/NOT/TO positions read that way. Any other \"+\" is sent as written, and inside a quoted phrase \"+\" is a literal plus sign. Double quotes, parentheses, and range brackets must balance, and the query must not end on a backslash — each is rejected before the request."

changedOutput schema / properties / notice / description

Previous value: -"Why the tally is empty — the search matched no records, or the matched records carry no value for the field — and how to widen it; when truncated, how to reach the omitted terms; at the 1000-term maximum, that openFDA cannot show whether more distinct values exist. Absent when a complete list is returned."New value: +"Why the tally is empty — the search matched no records, or the matched records carry no value for the field — and how to widen it; when truncated, how to reach the omitted terms (on a date field, how many distinct dates were counted); at the 1000-term maximum, that openFDA cannot show whether more distinct values exist; how many count rows openFDA sent without a value or numeric count, which are left out. Absent when a complete list is returned."

changedOutput schema / properties / results / items / properties / term / description

Previous value: -"Field value"New value: +"Field value; on a date field, the date as YYYYMMDD"

changedOutput schema / properties / truncated / description

Previous value: -"True when at least one more distinct term exists beyond the limit. Absent when the list is complete, and at the 1000-term maximum, where openFDA cannot show whether more exist (notice says so)."New value: +"True when at least one more distinct term exists beyond the limit. Absent when the list is complete, and at the 1000-term maximum, where openFDA cannot show whether more exist (notice says so). Exact at any limit on a date field, where every date arrives."

Changed5 schema fields changedSep 22, 2026

changedInput schema / properties / count / description

Previous value: -"Field to count. Append .exact for whole-phrase counting of free-text fields (e.g. \"patient.reaction.reactionmeddrapt.exact\"). Identifier fields openFDA already indexes as keywords (product_ndc, application_number, pma_number) must be counted bare — .exact on those is rejected as not countable."New value: +"Field to count. openfda_describe_fields gives the verified expression per field as countAs (null = not countable in any form). Otherwise: append .exact for whole-phrase counting of free-text fields (e.g. \"patient.reaction.reactionmeddrapt.exact\"); count identifier fields openFDA already indexes as keywords (product_ndc, application_number, pma_number) bare — .exact on those is rejected as not countable."

changedInput schema / properties / limit / description

Previous value: -"Number of top terms to return (default 100, max 1000)"New value: +"Number of top terms to return (default 100, max 1000 — openFDA's own count maximum). truncated reports whether more distinct terms exist beyond it, except at the maximum itself, where openFDA offers no way to tell."

changedOutput schema / properties / error / properties / data / properties / reason / description

Previous value: -"Machine-readable failure mode. Declared by this tool: `rate_limited`: The openFDA daily or per-minute request limit is exceeded. `upstream_error`: The openFDA API returned a 5xx server error. `malformed_search`: The search query leaves a double quote, parenthesis, or range bracket unclosed, or ends on a backslash. `query_error`: The search or count query was rejected by openFDA (malformed field name, invalid syntax). `not_aggregatable`: openFDA cannot aggregate the count expression as written — an analyzed text field, or .exact on a field already indexed as a keyword. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `rate_limited`: The openFDA daily or per-minute request limit is exceeded. `upstream_error`: The openFDA API returned a 5xx server error. `malformed_search`: The search query leaves a double quote, parenthesis, or range bracket unclosed, or ends on a backslash. `query_error`: The search or count query was rejected by openFDA (malformed field name, invalid syntax). `not_aggregatable`: openFDA cannot aggregate the count expression as written — an analyzed text field, .exact on a field already indexed as a keyword, or a field with no countable form. Other values are possible when a failure originates below the handler."

changedOutput schema / properties / notice / description

Previous value: -"Guidance when no terms matched — how to verify the field name or adjust the count expression. Absent when terms are returned."New value: +"Why the tally is empty — the search matched no records, or the matched records carry no value for the field — and how to widen it; when truncated, how to reach the omitted terms; at the 1000-term maximum, that openFDA cannot show whether more distinct values exist. Absent when a complete list is returned."

changedOutput schema / properties / truncated / description

Previous value: -"True when the term list was capped at the limit — more distinct terms may exist."New value: +"True when at least one more distinct term exists beyond the limit. Absent when the list is complete, and at the 1000-term maximum, where openFDA cannot show whether more exist (notice says so)."

Changed6 schema fields changedAug 25, 2026

changedInput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedInput schema / additionalProperties
```
Added value: +false
```

changedOutput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedOutput schema / anyOf

Added value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "meta",
+      "results",
+      "termCount"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]

addedOutput schema / properties / error

Added value: +{
+  "additionalProperties": {},
+  "description": "Present when the call failed. Absent on success.",
+  "properties": {
+    "code": {
+      "description": "JSON-RPC error code for this failure.",
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    },
+    "data": {
+      "additionalProperties": {},
+      "properties": {
+        "reason": {
+          "description": "Machine-readable failure mode. Declared by this tool: `rate_limited`: The openFDA daily or per-minute request limit is exceeded. `upstream_error`: The openFDA API returned a 5xx server error. `malformed_search`: The search query leaves a double quote, parenthesis, or range bracket unclosed, or ends on a backslash. `query_error`: The search or count query was rejected by openFDA (malformed field name, invalid syntax). `not_aggregatable`: openFDA cannot aggregate the count expression as written — an analyzed text field, or .exact on a field already indexed as a keyword. Other values are possible when a failure originates below the handler.",
+          "examples": [
+            "rate_limited",
+            "upstream_error",
+            "malformed_search",
+            "query_error",
+            "not_aggregatable"
+          ],
+          "type": "string"
+        },
+        "recovery": {
+          "additionalProperties": {},
+          "description": "Actionable next step for the caller.",
+          "properties": {
+            "hint": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "hint"
+          ],
+          "type": "object"
+        },
+        "retryable": {
+          "description": "Whether retrying may succeed.",
+          "type": "boolean"
+        }
+      },
+      "type": "object"
+    },
+    "message": {
+      "description": "Human-readable description of what went wrong.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "code",
+    "message"
+  ],
+  "type": "object"
+}

removedOutput schema / required

Removed value: -[
-  "meta",
-  "results",
-  "termCount"
-]

Changed1 schema field changedAug 7, 2026

changedInput schema / properties / search / description

Previous value: -"Filter query to scope the count (e.g. patient.drug.medicinalproduct:\"metformin\"). Omit to count across every record in the endpoint."New value: +"Filter query to scope the count (e.g. patient.drug.medicinalproduct:\"metformin\"). Omit to count across every record in the endpoint. Double quotes, parentheses, and range brackets must balance, and the query must not end on a backslash — each is rejected before the request."

Changed6 schema fields changedJul 26, 2026

changedInput schema / properties / count / description

Previous value: -"Field to count. Append .exact for whole-phrase counting (e.g. \"patient.reaction.reactionmeddrapt.exact\", \"openfda.brand_name.exact\")"New value: +"Field to count. Append .exact for whole-phrase counting of free-text fields (e.g. \"patient.reaction.reactionmeddrapt.exact\"). Identifier fields openFDA already indexes as keywords (product_ndc, application_number, pma_number) must be counted bare — .exact on those is rejected as not countable."

addedInput schema / properties / count / minLength
```
Added value: +1
```
addedInput schema / properties / count / pattern
```
Added value: +"\\S"
```

changedInput schema / properties / search / description

Previous value: -"Filter query to scope the count (e.g. patient.drug.medicinalproduct:\"metformin\")"New value: +"Filter query to scope the count (e.g. patient.drug.medicinalproduct:\"metformin\"). Omit to count across every record in the endpoint."

addedInput schema / properties / search / minLength
```
Added value: +1
```
addedInput schema / properties / search / pattern
```
Added value: +"\\S"
```

Changed4 schema fields changedJun 12, 2026

addedOutput schema / properties / cap

Added value: +{
+  "description": "The limit applied to the term list.",
+  "type": "number"
+}

addedOutput schema / properties / shown

Added value: +{
+  "description": "Number of terms returned in this response.",
+  "type": "number"
+}

addedOutput schema / properties / truncated

Added value: +{
+  "description": "True when the term list was capped at the limit — more distinct terms may exist.",
+  "type": "boolean"
+}

addedOutput schema / properties / truncationCeiling

Added value: +{
+  "description": "Count of the lowest-ranked term returned — omitted terms fall at or below it.",
+  "type": "number"
+}

AddedJun 9, 2026

TDQS

A4.2/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the readOnlyHint annotation, the description discloses return behavior: results are ranked term-count pairs sorted descending, and date fields tally one term per distinct YYYYMMDD date. Truncation behavior is fully documented in the schema rather than repeated here, leaving minor behavioral context unstated in the description itself.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, zero waste: the core action and return format are front-loaded, followed by the sibling-pairing guidance. Nothing is redundant or buried.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, the description need not explain return fields, and the rich schema covers all four parameters thoroughly. The description supplies purpose, return ordering, date-field behavior, and sibling pairing, leaving only error/permission nuances to the schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already defines each parameter in depth, including .exact semantics, truncation, and search syntax. The description adds no parameter-specific meaning beyond what the schema provides, so the baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb and resource ("Aggregate and tally unique values for any field across any openFDA endpoint") and specifies the return shape (ranked term-count pairs sorted descending), which clearly distinguishes it from the search siblings that return sample records.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It tells the agent when this tool is useful relative to siblings: pair with specific search/lookup tools "when sample records help interpret the aggregates." It does not provide explicit when-not-to-use guidance or contrast with openfda_describe_fields, which is mentioned only in the schema, so it falls short of a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All openfda-mcp-server tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Openfda Count Values

Input Schema

Output Schema

Schema Changelog

TDQS

Glama MCP Gateway

Resources