openfda-mcp-server
Server Details
Query FDA data on drugs, food, devices, and recalls via openFDA. STDIO or Streamable HTTP.
- Status
- Healthy
- Last Tested
- Transport
- Streamable HTTP
- URL
- Repository
- cyanheads/openfda-mcp-server
- GitHub Stars
- 1
- Server Listing
- @cyanheads/openfda-mcp-server
Glama MCP Gateway
Connect through Glama MCP Gateway for full control over tool access and complete visibility into every call.
Full call logging
Every tool call is logged with complete inputs and outputs, so you can debug issues and audit what your agents are doing.
Tool access control
Enable or disable individual tools per connector, so you decide what your agents can and cannot do.
Managed credentials
Glama handles OAuth flows, token storage, and automatic rotation, so credentials never expire on your clients.
Usage analytics
See which tools your agents call, how often, and when, so you can understand usage patterns and catch anomalies.
Tool Definition Quality
Average 4.2/5 across 14 of 14 tools scored. Lowest: 3.3/5.
Each tool targets a distinct FDA data domain or utility (e.g., adverse events, drug approvals, recalls, DataFrame operations). Descriptions are explicit about differences, such as separating animal events from human events, and the drug profile tool clearly replaces chaining multiple tools.
Tools follow a consistent 'openfda_' prefix with a verb-noun pattern (e.g., search_adverse_events, get_drug_label). Minor deviations like 'drug_profile' (noun-verb) and 'describe_fields' vs 'dataframe_describe' slightly break the pattern but remain understandable.
14 tools cover a broad range of FDA data sources (drugs, devices, food, tobacco, recalls, shortages) and include analytical helpers (count_values, DataFrame tools). The count is well-scoped for the domain—neither too sparse nor excessive.
The set covers major openFDA endpoints: adverse events, drug approvals, recalls, device clearances, labeling, NDC, shortages, and animal/tobacco reports. Missing endpoints like food contamination or cosmetics are niche, so the coverage is strong for common use cases.
Available Tools
14 toolsopenfda_count_valuesOpenfda Count ValuesARead-onlyInspect
Aggregate and tally unique values for any field across any openFDA endpoint. Returns ranked term-count pairs sorted by count descending. 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.
| Name | Required | Description | Default |
|---|---|---|---|
| count | Yes | Field to count. Append .exact for whole-phrase counting (e.g. "patient.reaction.reactionmeddrapt.exact", "openfda.brand_name.exact") | |
| limit | No | Number of top terms to return (default 100, max 1000) | |
| search | No | Filter query to scope the count (e.g. patient.drug.medicinalproduct:"metformin") | |
| 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 | Yes | Response metadata |
| shown | No | Number of terms returned in this response. |
| notice | No | Guidance when no terms matched — how to verify the field name or adjust the count expression. Absent when terms are returned. |
| results | Yes | Term-count pairs sorted by count descending |
| termCount | Yes | Number of distinct terms returned |
| truncated | No | True when the term list was capped at the limit — more distinct terms may exist. |
| truncationCeiling | No | Count of the lowest-ranked term returned — omitted terms fall at or below it. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, which the description aligns with. The description adds value by detailing the output structure (ranked term-count pairs sorted descending) and mentioning pairing with search tools for interpretation, enhancing transparency beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise at two sentences. The first sentence covers purpose and output, the second provides usage guidance. No redundant information, every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 4 parameters fully documented in schema and an output schema exists, the description explains the output format and provides usage guidance on pairing with other tools. It covers the essential context for effective use, though it omits operational details like pagination or rate limits, which are minor.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description only adds minor context (e.g., appending '.exact' for whole-phrase counting). It does not elaborate on parameter details beyond what the schema provides, keeping the score at baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool aggregates and tallies unique values for any field across any openFDA endpoint, specifying the output format (ranked term-count pairs). It distinguishes itself from sibling tools by mentioning pairing with search tools for interpreting aggregates, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly advises pairing with several sibling tools when sample records help interpret aggregates. While it doesn't explicitly state when NOT to use it, the pairing guidance provides strong context for appropriate usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
openfda_dataframe_describeOpenfda Dataframe DescribeARead-onlyIdempotentInspect
List the tables and column schemas on a DataCanvas staged by an openFDA search tool. Call before openfda_dataframe_query to discover the exact table name, column names, and DuckDB types needed for valid SQL. row_count is the full staged result set, not the inline preview count. Columns typed JSON hold nested openFDA objects/arrays — query them with DuckDB json functions.
| Name | Required | Description | Default |
|---|---|---|---|
| canvas_id | Yes | Canvas ID from an openFDA search tool response. |
Output Schema
| Name | Required | Description |
|---|---|---|
| tables | Yes | All tables and views available on this canvas. |
| canvas_id | Yes | Canvas ID that was described — pass to openfda_dataframe_query. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true and idempotentHint=true. The description adds behavioral details beyond annotations: row_count is the full staged set, and JSON columns require DuckDB json functions. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with primary purpose, followed by critical usage and behavioral details. Every sentence adds necessary value with no waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one required parameter, clear output schema), the description fully covers what the tool does, how to use it, and clarifies important output nuances (row_count, JSON columns).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for the single parameter canvas_id. The description does not add much beyond the schema, but baseline 3 is appropriate since schema handles the documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verbs ('List') and clearly identifies the resource ('tables and column schemas on a DataCanvas'). It differentiates from sibling tools like openfda_dataframe_query by stating it discovers schema information needed for queries.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states to call before openfda_dataframe_query for discovery, providing clear usage context. It does not mention when not to use, but the guidance is strong enough for an agent to decide.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
openfda_dataframe_queryOpenfda Dataframe QueryARead-onlyIdempotentInspect
Run a read-only SQL SELECT against a DataCanvas table staged by an openFDA search tool (canvas_id + canvas_table in its response when spilled=true). Enables GROUP BY, COUNT/SUM/AVG, time-series, and joins across the full result set without re-paging the API. Call openfda_dataframe_describe first to get the exact table and column names. Scalar fields are stored as text (CAST for numeric math); nested objects/arrays are JSON columns — read them with DuckDB json functions, e.g. json_extract_string(openfda, '$.brand_name[0]'). Only SELECT is allowed — DDL, DML, COPY, and file-reading functions are blocked.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | SQL SELECT against the staged table. Use the table name from openfda_dataframe_describe. Example: "SELECT classification, COUNT(*) AS n FROM spilled_ab12cd34 GROUP BY classification ORDER BY n DESC". | |
| canvas_id | Yes | Canvas ID from an openFDA search tool response (the canvas_id field). |
Output Schema
| Name | Required | Description |
|---|---|---|
| rows | Yes | Rows returned by the query (capped at the canvas row limit). |
| canvas_id | Yes | Canvas ID that was queried — reuse for follow-up queries. |
| row_count | Yes | Number of rows in this response. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and idempotentHint=true. The description goes beyond by explicitly blocking DDL, DML, COPY, and file-reading functions, and noting scalar fields are text and nested objects are JSON. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is four sentences, each serving a purpose: purpose, prerequisites, data type details, and constraints. It is front-loaded with the key action and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema (context signals: 'Has output schema: true') and thorough annotations, the description covers prerequisites, data types, and constraints. It is complete for a tool with 2 well-documented parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so both parameters are well-documented. The description adds context: canvas_id comes from a prior search tool response, and the query example references the table name from describe. A SQL example is provided, adding value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it runs a read-only SQL SELECT on a DataCanvas table, distinguishing it from sibling tools like openfda_search_adverse_events (searching) and openfda_dataframe_describe (schema inspection). It specifies the verb and resource with additional detail on supported operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly instructs to call openfda_dataframe_describe first for table/column names, and explains data type handling. While it lacks explicit when-not-to-use guidance, the context makes it clear this is for querying spilled data, not for searching or describing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
openfda_describe_fieldsOpenfda Describe FieldsARead-onlyInspect
Return the searchable field paths for an openFDA endpoint, grouped by category with type and description. Use before constructing a search query to find the correct dotted field path — field names differ per endpoint and are not discoverable from the tool schema alone.
| Name | Required | Description | Default |
|---|---|---|---|
| endpoint | Yes | openFDA endpoint to describe (e.g. "drug/event", "drug/shortages", "device/510k"). Must be one of the cataloged endpoints. |
Output Schema
| Name | Required | Description |
|---|---|---|
| groups | Yes | Field groups for this endpoint |
| endpoint | Yes | The endpoint these fields apply to |
| queryTips | Yes | openFDA query syntax reminders relevant to this endpoint |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint: true; description adds context about grouping by category and the discovery purpose. No contradictions, and description supplements annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences front-loaded with purpose, no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has output schema and description states output is grouped by category with type and description, which suffices for a metadata-discovery tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with full enum and description for the single parameter. Description does not add meaningful detail beyond the schema; baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool returns searchable field paths for an openFDA endpoint grouped by category with type and description. This specific verb+resource distinguishes it from sibling tools that search or count data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises using before constructing a search query to find the correct dotted field path, noting field names differ per endpoint. No explicit when-not or alternatives, but clear context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
openfda_drug_profileOpenfda Drug ProfileARead-onlyInspect
Resolve one drug name to its FDA identity, then fan out in parallel across the bounded per-drug openFDA endpoints and merge into one profile: identity, label highlights, adverse-event summary, recall history, Drugs@FDA approval, and shortage status. Replaces chaining openfda_get_drug_label, openfda_search_adverse_events, openfda_search_recalls, openfda_search_drug_approvals, and openfda_search_drug_shortages — and reconciles the identifier drift between endpoints that makes that chaining error-prone. Each section is best-effort: a miss returns null rather than failing the call. For deep dives into any one area, use the dedicated tool.
| Name | Required | Description | Default |
|---|---|---|---|
| drug | Yes | Drug name to profile — brand or generic (e.g. "metformin", "Humira", "Glucophage"). Resolved once to canonical FDA identifiers, which then key every sub-query. |
Output Schema
| Name | Required | Description |
|---|---|---|
| meta | Yes | Request metadata. |
| label | Yes | Label highlights from drug/label, or null when no label matched. |
| notice | No | Guidance when the drug could not be resolved or upstream errors degraded the profile. Absent on a fully populated profile. |
| recalls | Yes | Recent drug/enforcement recall actions (may be empty). |
| approval | Yes | Drugs@FDA approval summary, or null when no application matched. |
| identity | Yes | Identity resolved once and reused across every sub-query to avoid identifier drift. |
| shortage | Yes | Current or most-recent drug shortage status, or null when none on record. |
| sectionsFound | Yes | How many profile sections (label, adverse_events, recalls, approval, shortage) returned data. |
| adverse_events | Yes | Adverse-event summary aggregated over drug/event, or null when unavailable. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint=true; description adds critical behavioral details: best-effort per section (miss returns null, not failure) and parallel fan-out merge. This goes beyond annotations without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three focused sentences: core action, distinction from siblings, and behavioral note. No redundant information; every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, usage alternatives, behavior (best-effort), and given output schema exists, the description provides sufficient context about the profile sections. Complete for a single-parameter tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema already describes the 'drug' parameter with examples and resolution note (100% coverage). Description reinforces but does not add new parameter semantics. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool resolves a drug name to its FDA identity and merges multiple endpoint data into one profile. It distinguishes from siblings by explicitly naming the five tools it replaces and highlighting the reconciliation of identifier drift.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use (for a combined profile) and when not to ('For deep dives into any one area, use the dedicated tool'). Also explains it replaces chaining of multiple sibling tools, providing clear alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
openfda_get_drug_labelOpenfda Get Drug LabelARead-onlyInspect
Look up FDA drug labeling (package inserts / SPL documents). Check indications, warnings, dosage, contraindications, active ingredients, or any structured label section.
| Name | Required | Description | Default |
|---|---|---|---|
| skip | No | Number of results to skip for pagination (0-25000). Default 0. | |
| sort | No | Sort expression (field:asc or field:desc). Example: effective_time:desc. Invalid or non-sortable fields cause a query error — use a documented field name. | |
| limit | No | Maximum number of results to return (1-1000). Default 5. Labels are large. | |
| search | Yes | Query targeting label fields. Examples: openfda.brand_name:"aspirin", openfda.generic_name:"metformin", openfda.manufacturer_name:"pfizer". For a specific revision, pass set_id with the SPL UUID returned in earlier results. |
Output Schema
| Name | Required | Description |
|---|---|---|
| cap | No | The limit applied to this page. |
| meta | Yes | Pagination and freshness metadata. |
| shown | No | Number of labels returned in this response. |
| notice | No | Guidance when results are empty or paging overshot — how to broaden filters or correct field names. Absent when results are returned. |
| results | Yes | Drug label records. Each carries an openfda block (brand_name, generic_name, manufacturer_name, route) plus optional SPL sections like indications_and_usage, warnings, dosage_and_administration, contraindications, adverse_reactions; section presence varies per label. |
| truncated | No | True when more labels matched than this page returned — page with skip for the rest. |
| totalResults | Yes | Total matching label records in the dataset |
| effectiveQuery | Yes | Search filter applied to the drug label query, as submitted to openFDA |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint: true, making the read-only nature clear. The description adds value by specifying the content (package inserts, SPL, sections like indications and warnings), but does not disclose pagination or error handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, front-loaded with the core purpose. No wasted words, every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema and fully documented parameters, the description adequately covers purpose and typical use cases. It lacks explicit usage guidance but is complete enough for an informed agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear parameter descriptions and examples. The description adds minimal extra meaning beyond listing possible label sections; baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool looks up FDA drug labeling (package inserts/SPL documents) and lists example sections (indications, warnings, etc.), distinguishing it from sibling tools focused on adverse events, drug approvals, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for drug label information but does not explicitly state when to use vs alternatives or when not to use. No exclusions or comparisons provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
openfda_lookup_ndcOpenfda Lookup NdcARead-onlyInspect
Look up drugs in the NDC (National Drug Code) Directory. Identify drug products by NDC code, find active ingredients, packaging details, or manufacturer info. Pair with openfda_get_drug_label using the returned brand_name or set_id to read the package insert.
| Name | Required | Description | Default |
|---|---|---|---|
| skip | No | Number of records to skip for pagination (0-25000, default 0) | |
| sort | No | Sort expression (field:asc or field:desc). Example: listing_expiration_date:desc. Invalid or non-sortable fields cause a query error — use a documented field name. | |
| limit | No | Maximum number of records to return (1-1000, default 10) | |
| search | Yes | openFDA search query. Examples: product_ndc:"0363-0218", brand_name:"aspirin", generic_name:"metformin", openfda.manufacturer_name:"walgreen", active_ingredients.name:"ASPIRIN" | |
| canvas_id | No | DataCanvas session id from a prior call. Omit to start a fresh canvas; the response returns a new one when canvas is enabled. When canvas (CANVAS_PROVIDER_TYPE=duckdb) is enabled the full matched set is staged for SQL and limit/skip apply only to the inline path. |
Output Schema
| Name | Required | Description |
|---|---|---|
| meta | Yes | Response metadata |
| notice | No | Guidance when results are empty — how to broaden filters or correct field names. Absent when results are returned. |
| results | Yes | NDC directory records — product_ndc, brand_name, generic_name, labeler_name, dosage_form, route, marketing_category, active_ingredients[], packaging[], listing_expiration_date. |
| spilled | No | True when the full result set was staged on the canvas — use canvas_id with openfda_dataframe_query for SQL. False when it fit inline. Absent when canvas is disabled. |
| canvas_id | No | DataCanvas session id for the staged result set. Present when canvas is enabled. Pass to openfda_dataframe_query / openfda_dataframe_describe, or back into this tool to accumulate more tables on the same canvas. |
| truncated | No | True when more rows matched upstream than the 25000-row staging ceiling. Narrow the query (filters, date range) for a complete set. |
| canvas_table | No | Canvas table holding the full staged result. Present when spilled=true; reference it in SQL FROM clauses. |
| totalResults | Yes | Total matching NDC records in the dataset |
| effectiveQuery | Yes | Search filter applied to the NDC lookup, as submitted to openFDA |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description accurately describes the tool as a read-only lookup operation, consistent with the readOnlyHint annotation. No additional behavioral traits beyond the annotation are disclosed, which is adequate but not exceptional.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two focused sentences plus one sentence for tool pairing, with no fluff. It front-loads the core purpose and immediately provides actionable guidance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema and the tool's lookup nature, the description adequately covers return values and provides context on pagination, pairing, and data staging. It is complete for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema coverage, the baseline is 3. The description adds value by providing detailed examples for the search parameter, explaining canvas_id usage, and clarifying limit/skip behavior, enhancing understanding beyond bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool looks up drugs in the NDC Directory, identifies drug products, active ingredients, packaging, and manufacturer info. It distinguishes from sibling tools like openfda_get_drug_label by specifying pairing and different output fields.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly recommends pairing with openfda_get_drug_label using brand_name or set_id, providing context on when to use this tool versus others. It lacks explicit when-not-to-use guidance but gives clear usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
openfda_search_adverse_eventsOpenfda Search Adverse EventsARead-onlyInspect
Search adverse event reports across drugs, food, and devices. Use to investigate safety signals, find reports for a specific product, or explore reactions by demographics.
| Name | Required | Description | Default |
|---|---|---|---|
| skip | No | Number of records to skip for pagination (0-25000, default 0) | |
| sort | No | Sort expression (field:asc or field:desc). Example: receivedate:desc. Invalid or non-sortable fields cause a query error — use a documented field name. | |
| limit | No | Maximum number of records to return (1-1000, default 10) | |
| search | No | openFDA search query. Examples: patient.drug.medicinalproduct:"aspirin", patient.reaction.reactionmeddrapt:"nausea" AND serious:"1". Omit to browse recent. | |
| category | Yes | Product category — each has different field schemas in the response | |
| canvas_id | No | DataCanvas session id from a prior call. Omit to start a fresh canvas; the response returns a new one when canvas is enabled. When canvas (CANVAS_PROVIDER_TYPE=duckdb) is enabled the full matched set is staged for SQL and limit/skip apply only to the inline path. |
Output Schema
| Name | Required | Description |
|---|---|---|
| meta | Yes | Response metadata |
| notice | No | Guidance when results are empty or paging overshot — how to broaden filters or adjust the query. Absent when results are returned. |
| results | Yes | Adverse event records — fields vary by category (drug: patient/reactions/drugs, device: device details/event type, food: products/outcomes) |
| spilled | No | True when the full result set was staged on the canvas — use canvas_id with openfda_dataframe_query for SQL. False when it fit inline. Absent when canvas is disabled. |
| canvas_id | No | DataCanvas session id for the staged result set. Present when canvas is enabled. Pass to openfda_dataframe_query / openfda_dataframe_describe, or back into this tool to accumulate more tables on the same canvas. |
| truncated | No | True when more rows matched upstream than the 25000-row staging ceiling. Narrow the query (filters, date range) for a complete set. |
| canvas_table | No | Canvas table holding the full staged result. Present when spilled=true; reference it in SQL FROM clauses. |
| totalResults | Yes | Total matching adverse event records in the dataset |
| effectiveQuery | No | Search filter applied to the query, as submitted to openFDA |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already informs the agent this is safe. The description adds no behavioral details beyond the basic search capability, such as query syntax, pagination, or rate limits. Given the annotation coverage, the description is adequate but not rich in behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, directly stating the core action and use cases without any fluff. Every sentence earns its place, and the most critical information (what it searches and why) is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is minimal but adequate given the rich input schema (100% coverage), read-only annotation, and existence of an output schema. It provides a high-level overview but lacks deeper context about search syntax, result structure, or relationship with sibling tools like openfda_count_values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the parameters are already well-documented. The tool description does not add additional parameter-level insights beyond the high-level use cases, meeting the baseline expectation of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it searches adverse event reports across drugs, food, and devices, and provides specific use cases (investigating safety signals, finding product reports). This distinguishes it from sibling tools like openfda_search_animal_events or openfda_search_device_clearances.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear use cases ('investigate safety signals, find reports for a specific product, or explore reactions by demographics'), but does not explicitly exclude alternatives or mention when not to use this tool. However, the context is sufficient for an agent to decide.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
openfda_search_animal_eventsOpenfda Search Animal EventsARead-onlyInspect
Search adverse event reports for veterinary drugs and devices submitted to the FDA Center for Veterinary Medicine. Records include animal species, breed, age, weight, drug name and route, adverse reactions (using VeDDRA terminology), and outcome. Use to investigate safety signals for veterinary products, find reports by animal species or drug, or explore reaction patterns.
| Name | Required | Description | Default |
|---|---|---|---|
| skip | No | Number of records to skip for pagination (0-25000, default 0) | |
| sort | No | Sort expression (field:asc or field:desc). Example: original_receive_date:desc. Invalid or non-sortable fields cause a query error — use a documented field name. | |
| limit | No | Maximum number of records to return (1-1000, default 10) | |
| search | No | openFDA search query using field:value syntax. Examples: animal.species:"Dog", drug.brand_name:"Bravecto", reaction.veddra_term_name:"Vomiting", serious_ae:"true". Omit to browse recent reports. | |
| canvas_id | No | DataCanvas session id from a prior call. Omit to start a fresh canvas; the response returns a new one when canvas is enabled. When canvas (CANVAS_PROVIDER_TYPE=duckdb) is enabled the full matched set is staged for SQL and limit/skip apply only to the inline path. |
Output Schema
| Name | Required | Description |
|---|---|---|
| meta | Yes | Response metadata |
| notice | No | Guidance when results are empty or paging overshot — how to broaden filters or adjust the query. Absent when results are returned. |
| results | Yes | Animal adverse event records. Key fields: unique_aer_id_number, original_receive_date, serious_ae, animal (species, gender, breed, age, weight), drug[] (brand_name, active_ingredients, route, dose, administered_by), reaction[] (veddra_term_name, number_of_animals_affected), outcome[] (medical_status), primary_reporter, type_of_information. |
| spilled | No | True when the full result set was staged on the canvas — use canvas_id with openfda_dataframe_query for SQL. False when it fit inline. Absent when canvas is disabled. |
| canvas_id | No | DataCanvas session id for the staged result set. Present when canvas is enabled. Pass to openfda_dataframe_query / openfda_dataframe_describe, or back into this tool to accumulate more tables on the same canvas. |
| truncated | No | True when more rows matched upstream than the 25000-row staging ceiling. Narrow the query (filters, date range) for a complete set. |
| canvas_table | No | Canvas table holding the full staged result. Present when spilled=true; reference it in SQL FROM clauses. |
| totalResults | Yes | Total matching animal adverse event records in the dataset |
| effectiveQuery | No | Search filter applied to the query, as submitted to openFDA |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description adds behavioral context beyond annotations: it states the tool retrieves records with specific fields (species, breed, reactions, outcome), implying read-only behavior consistent with readOnlyHint=true. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two focused sentences, front-loaded with the primary action, followed by record contents and use cases. No redundant or extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists and annotations cover safety, the description provides sufficient domain context, example uses, and record content overview. No gaps identified for a search tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so all parameters are already documented. The description adds no new parameter-specific meaning, merely listing example query values that align with the schema. Baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description specifies a clear verb ('Search') and resource ('adverse event reports for veterinary drugs and devices'), lists included data fields, and gives concrete usage examples ('investigate safety signals', 'find reports by animal species or drug'). It effectively distinguishes from siblings like openfda_search_adverse_events (human events).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description suggests when to use: 'investigate safety signals... find reports by animal species or drug, or explore reaction patterns.' It implicitly differentiates from human-focused siblings, but lacks explicit when-not or alternative tool guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
openfda_search_device_clearancesOpenfda Search Device ClearancesARead-onlyInspect
Search FDA device premarket notifications — 510(k) clearances and PMA approvals.
| Name | Required | Description | Default |
|---|---|---|---|
| skip | No | Pagination offset (0-25000). | |
| sort | No | Sort expression (field:asc or field:desc). Example: decision_date:desc. Invalid or non-sortable fields cause a query error — use a documented field name. | |
| limit | No | Maximum number of records to return (1-1000). | |
| search | No | openFDA search query. Examples: applicant:"medtronic", advisory_committee_description:"cardiovascular", product_code:"DXN", openfda.device_name:"catheter". Omit to browse recent. | |
| pathway | Yes | Premarket pathway. 510(k) is the most common; PMA is for higher-risk devices. | |
| canvas_id | No | DataCanvas session id from a prior call. Omit to start a fresh canvas; the response returns a new one when canvas is enabled. When canvas (CANVAS_PROVIDER_TYPE=duckdb) is enabled the full matched set is staged for SQL and limit/skip apply only to the inline path. |
Output Schema
| Name | Required | Description |
|---|---|---|
| meta | Yes | Response metadata |
| notice | No | Guidance when results are empty — how to broaden filters or correct field names. Absent when results are returned. |
| results | Yes | 510(k) or PMA records — 510(k) carries k_number, device_name, applicant, product_code, decision_date, decision_description, advisory_committee_description; PMA carries pma_number, trade_name, generic_name, supplement_number plus shared applicant/product_code/decision_date/decision_description. |
| spilled | No | True when the full result set was staged on the canvas — use canvas_id with openfda_dataframe_query for SQL. False when it fit inline. Absent when canvas is disabled. |
| canvas_id | No | DataCanvas session id for the staged result set. Present when canvas is enabled. Pass to openfda_dataframe_query / openfda_dataframe_describe, or back into this tool to accumulate more tables on the same canvas. |
| truncated | No | True when more rows matched upstream than the 25000-row staging ceiling. Narrow the query (filters, date range) for a complete set. |
| canvas_table | No | Canvas table holding the full staged result. Present when spilled=true; reference it in SQL FROM clauses. |
| totalResults | Yes | Total matching device clearance records in the dataset |
| effectiveQuery | No | Search filter applied to the device clearance query, as submitted to openFDA |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, so the description doesn't need to reinforce that. The description adds some behavioral context by mentioning canvas_id behavior ('the full matched set is staged for SQL'), but doesn't disclose other traits like rate limits, auth requirements, or pagination limits beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence front-loads the core purpose with no extraneous words. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Output schema exists, so return values are covered. The description, combined with rich schema annotations (100% coverage), suffices for an agent to understand the tool's basic function. However, it lacks hints on constructing effective search queries or handling the canvas parameter, which the schema partially addresses.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents each parameter. The description adds no extra meaning beyond what the schema provides. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Search FDA device premarket notifications — 510(k) clearances and PMA approvals.' It specifies the verb (Search), the resource (FDA device premarket notifications), and the specific subtypes (510(k) and PMA). This distinguishes it from sibling tools like search_drug_approvals or search_adverse_events.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for searching device clearances but provides no explicit guidance on when to use this tool vs alternatives (e.g., when to use search_drug_approvals instead). No when-not-to-use or alternative suggestions are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
openfda_search_drug_approvalsOpenfda Search Drug ApprovalsARead-onlyInspect
Search the Drugs@FDA database for drug application approvals (NDAs and ANDAs). Returns application details, sponsor info, and full submission history. Pair with openfda_get_drug_label to read the approved label, or openfda_count_values to aggregate by sponsor_name, product_type, or route.
| Name | Required | Description | Default |
|---|---|---|---|
| skip | No | Number of records to skip for pagination (0-25000, default 0) | |
| sort | No | Sort expression (field:asc or field:desc). Example: submissions.submission_status_date:desc. Invalid or non-sortable fields cause a query error — use a documented field name. | |
| limit | No | Maximum number of records to return (1-1000, default 10) | |
| search | No | openFDA search query. Examples: openfda.brand_name:"humira", sponsor_name:"pfizer", submissions.submission_type:"ORIG" AND submissions.review_priority:"PRIORITY". Omit to browse recent. | |
| canvas_id | No | DataCanvas session id from a prior call. Omit to start a fresh canvas; the response returns a new one when canvas is enabled. When canvas (CANVAS_PROVIDER_TYPE=duckdb) is enabled the full matched set is staged for SQL and limit/skip apply only to the inline path. |
Output Schema
| Name | Required | Description |
|---|---|---|
| meta | Yes | Response metadata |
| notice | No | Guidance when results are empty — how to broaden filters or correct field names. Absent when results are returned. |
| results | Yes | Drug application records — application_number, sponsor_name, openfda block (brand_name, generic_name, route, product_type, substance_name), products[] (active_ingredients, dosage_form, marketing_status), submissions[] (submission_type, submission_status, submission_status_date, review_priority). |
| spilled | No | True when the full result set was staged on the canvas — use canvas_id with openfda_dataframe_query for SQL. False when it fit inline. Absent when canvas is disabled. |
| canvas_id | No | DataCanvas session id for the staged result set. Present when canvas is enabled. Pass to openfda_dataframe_query / openfda_dataframe_describe, or back into this tool to accumulate more tables on the same canvas. |
| truncated | No | True when more rows matched upstream than the 25000-row staging ceiling. Narrow the query (filters, date range) for a complete set. |
| canvas_table | No | Canvas table holding the full staged result. Present when spilled=true; reference it in SQL FROM clauses. |
| totalResults | Yes | Total matching drug approval records in the dataset |
| effectiveQuery | No | Search filter applied to the Drugs@FDA query, as submitted to openFDA |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, which the description does not contradict. The description adds behavioral context about canvas_id staging data for SQL and explains how limit/skip behave differently when canvas is enabled. This goes beyond what annotations provide, though it could mention rate limits or data freshness.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences plus a pairing note. It front-loads the core purpose and follows with actionable usage guidance. No unnecessary words or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema, full parameter coverage, and annotations, the description is complete. It covers purpose, return contents, pagination, canvas integration, and cross-tool usage. No obvious gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters. The description adds value with example search queries, sort expression syntax with warning about invalid fields, and explanation of canvas_id behavior. This provides practical guidance beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it searches the Drugs@FDA database for drug application approvals (NDAs and ANDAs) and returns application details, sponsor info, and submission history. This specific verb-resource combination distinguishes it from sibling tools like openfda_search_adverse_events or openfda_get_drug_label.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit pairing suggestions: use openfda_get_drug_label to read labels, openfda_count_values for aggregation. It also mentions 'omit to browse recent' for the search parameter. However, it does not state when not to use this tool or explicitly rule out alternatives beyond those two.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
openfda_search_drug_shortagesOpenfda Search Drug ShortagesARead-onlyInspect
Search FDA drug shortage records. Returns per-product shortage status, availability, therapeutic category, dosage form, manufacturer, and dates. Use to check whether a drug is currently in shortage, find all oncology drugs with supply issues, or retrieve the openfda block (brand_name, product_ndc, rxcui) to chain into openfda_get_drug_label or openfda_lookup_ndc.
| Name | Required | Description | Default |
|---|---|---|---|
| skip | No | Number of records to skip for pagination (0-25000, default 0) | |
| sort | No | Sort expression (field:asc or field:desc). Example: update_date:desc. Invalid or non-sortable fields cause a query error — use a documented field name. | |
| limit | No | Maximum number of records to return (1-1000, default 10) | |
| search | No | openFDA search query using field:value syntax. Examples: status:"Current", therapeutic_category:"Oncology", generic_name:"carboplatin", company_name:"pfizer". Omit to browse all records. Call openfda_describe_fields({ endpoint: "drug/shortages" }) for the complete field list. | |
| canvas_id | No | DataCanvas session id from a prior call. Omit to start a fresh canvas; the response returns a new one when canvas is enabled. When canvas (CANVAS_PROVIDER_TYPE=duckdb) is enabled the full matched set is staged for SQL and limit/skip apply only to the inline path. |
Output Schema
| Name | Required | Description |
|---|---|---|
| meta | Yes | Response metadata |
| notice | No | Guidance when results are empty — how to broaden filters or correct field names. Absent when results are returned. |
| results | Yes | Drug shortage records. Key fields: generic_name, status ("Current"/"Resolved"), availability, therapeutic_category, dosage_form, presentation, package_ndc, company_name, contact_info, initial_posting_date, update_date, update_type. openfda block contains brand_name, product_ndc, rxcui, spl_set_id for cross-linking. |
| spilled | No | True when the full result set was staged on the canvas — use canvas_id with openfda_dataframe_query for SQL. False when it fit inline. Absent when canvas is disabled. |
| canvas_id | No | DataCanvas session id for the staged result set. Present when canvas is enabled. Pass to openfda_dataframe_query / openfda_dataframe_describe, or back into this tool to accumulate more tables on the same canvas. |
| truncated | No | True when more rows matched upstream than the 25000-row staging ceiling. Narrow the query (filters, date range) for a complete set. |
| canvas_table | No | Canvas table holding the full staged result. Present when spilled=true; reference it in SQL FROM clauses. |
| totalResults | Yes | Total matching drug shortage records in the dataset |
| effectiveQuery | No | Search filter applied to the drug/shortages query, as submitted to openFDA |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the description's burden is reduced. The description adds behavioral context by stating it returns per-product shortage data and the openfda block. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: first clearly states purpose and results, second gives actionable use cases and chaining. Front-loaded and every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the 5 parameters (all described in schema) and presence of output schema, the description covers the tool's primary function and integration points. Could mention that it is read-only, but annotation already covers that.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description does not add additional meaning beyond what the schema provides. It mentions fields like status and therapeutic_category in examples, but this is already in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies 'Search FDA drug shortage records' and enumerates returned fields (shortage status, availability, therapeutic category, etc.). It distinguishes from siblings by mentioning chaining to openfda_get_drug_label and openfda_lookup_ndc, and giving specific use cases like checking oncology drugs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage contexts: 'Use to check whether a drug is currently in shortage, find all oncology drugs with supply issues, or retrieve the openfda block...' It also suggests chaining to other tools. Lacks explicit when-not-to-use or alternatives, but given the specific nature of the tool, the guidance is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
openfda_search_recallsOpenfda Search RecallsBRead-onlyInspect
Search enforcement reports and recall actions across drugs, food, and devices.
| Name | Required | Description | Default |
|---|---|---|---|
| skip | No | Pagination offset (0-25000). | |
| sort | No | Sort expression (field:asc or field:desc). Example: report_date:desc. Invalid or non-sortable fields cause a query error — use a documented field name. | |
| limit | No | Maximum number of records to return (1-1000). | |
| search | No | openFDA search query. Examples: classification:"Class I" (also "Class II" or "Class III"), recalling_firm:"pfizer", reason_for_recall:"undeclared allergen". | |
| category | Yes | Product category | |
| endpoint | No | Report type. Default enforcement. The recall endpoint is only available for devices. | enforcement |
| canvas_id | No | DataCanvas session id from a prior call. Omit to start a fresh canvas; the response returns a new one when canvas is enabled. When canvas (CANVAS_PROVIDER_TYPE=duckdb) is enabled the full matched set is staged for SQL and limit/skip apply only to the inline path. |
Output Schema
| Name | Required | Description |
|---|---|---|
| meta | Yes | Response metadata |
| notice | No | Guidance when results are empty — how to broaden filters or correct field names. Absent when results are returned. |
| results | Yes | Enforcement or recall records — recall_number, classification, recalling_firm, product_description, reason_for_recall, status, voluntary_mandated, distribution_pattern, report_date. Field set varies between enforcement and recall endpoints. |
| spilled | No | True when the full result set was staged on the canvas — use canvas_id with openfda_dataframe_query for SQL. False when it fit inline. Absent when canvas is disabled. |
| canvas_id | No | DataCanvas session id for the staged result set. Present when canvas is enabled. Pass to openfda_dataframe_query / openfda_dataframe_describe, or back into this tool to accumulate more tables on the same canvas. |
| truncated | No | True when more rows matched upstream than the 25000-row staging ceiling. Narrow the query (filters, date range) for a complete set. |
| canvas_table | No | Canvas table holding the full staged result. Present when spilled=true; reference it in SQL FROM clauses. |
| totalResults | Yes | Total matching recall/enforcement records in the dataset |
| effectiveQuery | No | Search filter applied to the recall query, as submitted to openFDA |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations declare readOnlyHint=true, so the description does not need to restate that. However, it adds no additional behavioral context such as rate limits or pagination behavior. With annotations covering safety, the contribution is minimal but not missing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the verb and resource. It is efficient but could be slightly more informative without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 7 parameters (including required category and endpoint limitations) and an output schema, the description is too sparse. It does not mention the endpoint constraint (recall only for devices) or the required category.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds no extra meaning beyond what the schema already provides for each parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies the verb 'Search' and the resources 'enforcement reports and recall actions' across three categories (drugs, food, devices). This distinguishes it from sibling tools that focus on adverse events, drug approvals, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like openfda_search_adverse_events or openfda_search_drug_approvals. The description does not mention prerequisites or exclude cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
openfda_search_tobacco_reportsOpenfda Search Tobacco ReportsARead-onlyInspect
Search problem reports submitted to the FDA for tobacco products, including e-cigarettes, vaping products, cigarettes, and smokeless tobacco. Reports capture product type, reported health problems (e.g. seizure, chest pain), product problems (e.g. exploding battery), whether a non-user was affected, and submission date. Use to investigate safety signals, find reports by product type, or analyze health effects.
| Name | Required | Description | Default |
|---|---|---|---|
| skip | No | Number of records to skip for pagination (0-25000, default 0) | |
| sort | No | Sort expression (field:asc or field:desc). Example: date_submitted:desc. Invalid or non-sortable fields cause a query error — use a documented field name. | |
| limit | No | Maximum number of records to return (1-1000, default 10) | |
| search | No | openFDA search query using field:value syntax. Examples: tobacco_products:"Electronic cigarette", reported_health_problems:"Seizure", nonuser_affected:"Yes". Omit to browse recent reports. | |
| canvas_id | No | DataCanvas session id from a prior call. Omit to start a fresh canvas; the response returns a new one when canvas is enabled. When canvas (CANVAS_PROVIDER_TYPE=duckdb) is enabled the full matched set is staged for SQL and limit/skip apply only to the inline path. |
Output Schema
| Name | Required | Description |
|---|---|---|
| meta | Yes | Response metadata |
| notice | No | Guidance when results are empty or paging overshot — how to broaden filters or adjust the query. Absent when results are returned. |
| results | Yes | Tobacco problem report records. Key fields: report_id, date_submitted, tobacco_products[] (product type description), reported_health_problems[] (health effects), reported_product_problems[] (device/product defects), number_tobacco_products, number_health_problems, number_product_problems, nonuser_affected. |
| spilled | No | True when the full result set was staged on the canvas — use canvas_id with openfda_dataframe_query for SQL. False when it fit inline. Absent when canvas is disabled. |
| canvas_id | No | DataCanvas session id for the staged result set. Present when canvas is enabled. Pass to openfda_dataframe_query / openfda_dataframe_describe, or back into this tool to accumulate more tables on the same canvas. |
| truncated | No | True when more rows matched upstream than the 25000-row staging ceiling. Narrow the query (filters, date range) for a complete set. |
| canvas_table | No | Canvas table holding the full staged result. Present when spilled=true; reference it in SQL FROM clauses. |
| totalResults | Yes | Total matching tobacco problem reports in the dataset |
| effectiveQuery | No | Search filter applied to the query, as submitted to openFDA |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, which is consistent with a search tool. Description adds context about data fields and purposes. Does not mention limitations like rate limits or data freshness, but the read-only nature is clear. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences that efficiently convey purpose, data scope, and use cases. Every sentence adds value; no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Descriptions of all 5 parameters are present in schema, output schema exists, annotations present. The tool description covers typical use cases. Minor missing context (e.g., data update frequency) but not critical for tool selection.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds some context for the 'search' parameter by providing field examples (e.g., tobacco_products, reported_health_problems) but schema already includes examples. Overall, moderate added value beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it searches tobacco problem reports, lists specific products (e-cigarettes, chewing tobacco), types of data captured (health problems, product problems), and explicit use cases (safety signals, product type). Distinguished from sibling tools by focusing on tobacco.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides use case examples (investigate safety signals, find reports by product type) but does not explicitly contrast with sibling tools or specify when not to use (e.g., for drug events use another tool). Implicitly scoped to tobacco, but no direct guidance on alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Claim this connector by publishing a /.well-known/glama.json file on your server's domain with the following structure:
{
"$schema": "https://glama.ai/mcp/schemas/connector.json",
"maintainers": [{ "email": "your-email@example.com" }]
}The email address must match the email associated with your Glama account. Once published, Glama will automatically detect and verify the file within a few minutes.
Control your server's listing on Glama, including description and metadata
Access analytics and receive server usage reports
Get monitoring and health status updates for your server
Feature your server to boost visibility and reach more users
For users:
Full audit trail – every tool call is logged with inputs and outputs for compliance and debugging
Granular tool control – enable or disable individual tools per connector to limit what your AI agents can do
Centralized credential management – store and rotate API keys and OAuth tokens in one place
Change alerts – get notified when a connector changes its schema, adds or removes tools, or updates tool definitions, so nothing breaks silently
For server owners:
Proven adoption – public usage metrics on your listing show real-world traction and build trust with prospective users
Tool-level analytics – see which tools are being used most, helping you prioritize development and documentation
Direct user feedback – users can report issues and suggest improvements through the listing, giving you a channel you would not have otherwise
The connector status is unhealthy when Glama is unable to successfully connect to the server. This can happen for several reasons:
The server is experiencing an outage
The URL of the server is wrong
Credentials required to access the server are missing or invalid
If you are the owner of this MCP connector and would like to make modifications to the listing, including providing test credentials for accessing the server, please contact support@glama.ai.
Discussions
No comments yet. Be the first to start the discussion!
Your Connectors
Sign in to create a connector for this server.