Search and query CDC public health data — mortality, vaccinations, surveillance, behavioral risk.
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.
Average 4.5/5 across 4 of 4 tools scored.
Each tool targets a distinct action: discovering datasets, getting schema, querying data, and querying a separate CDC system. The descriptions clearly differentiate them, with cross-references that reinforce when to use each.
All tool names follow a consistent cdc_ + verb + noun pattern (discover_datasets, get_dataset_schema, query_dataset, query_wonder), using snake_case throughout. The naming is predictable and system-free.
With 4 tools, the server is tightly scoped to the CDC health data domain. Each tool covers a necessary step in the workflow (discover → explore → query), and there is no bloat or redundancy.
The four tools form a complete pipeline for discovering, inspecting, and querying CDC datasets, plus a specialized tool for WONDER mortality data. Minor gaps exist (e.g., no dedicated tool for WONDER schema, but the description covers necessary details).
cdc_discover_datasetsCdc Discover DatasetsASearch the CDC dataset catalog by keyword, category, or tag. Returns IDs, names, truncated descriptions, asset types, column counts, and update timestamps. The catalog also holds charts, maps, stories, files, and links; an entry whose columnCount is 0 is one of those and yields no data from the other tools. Use cdc_get_dataset_schema for the full column list of a chosen dataset.
| Name | Required | Description | Default |
|---|---|---|---|
| tags | No | Filter by domain tags (e.g., ["covid19", "surveillance"]). Tags widen the search instead of narrowing it — a dataset matches when it carries any one of them, so every tag added returns more results, and an unrecognized tag matches nothing and leaves the result set unchanged. Values match the catalog's own tag vocabulary, case-insensitively; the tags field on each result shows which values are in use. To narrow, combine tags with query or category, which intersect with the tag set. | |
| limit | No | Results to return (default 10, max 100). offset plus limit must not exceed 10000. | |
| order | No | Result ordering. "dataset_id" (default) sorts deterministically by each dataset's unique catalog ID — required for stable offset pagination, since consecutive pages form a gap-free, duplicate-free traversal. "relevance" returns best-match ranking for keyword search but is not stably paginable across pages, so walking offsets can skip or repeat datasets. | dataset_id |
| query | No | Full-text search across dataset names and descriptions (e.g., "diabetes mortality", "lead exposure children"). | |
| domain | No | CDC Socrata host to search. "data.cdc.gov" (default) and "chronicdata.cdc.gov" front the same catalog and return the same entries, so switching hosts neither widens nor narrows a search — chronic-disease and small-area collections such as PLACES, the Heart Disease & Stroke Atlas, and Environmental Public Health Tracking are found from either. | data.cdc.gov |
| offset | No | Pagination offset for browsing beyond first page (max 9999). offset plus limit must not exceed 10000; both CDC portals hold well under two thousand entries, so offsets near that ceiling page past the end of the catalog. | |
| category | No | Filter by domain category (e.g., "NNDSS", "Vaccinations", "Behavioral Risk Factors"). |
| Name | Required | Description |
|---|---|---|
| notice | No | Guidance when the page came back empty — how to broaden a search that matched nothing, where to check tag values when a tag filter was applied, or the size of the result set when the offset ran past its end. |
| datasets | Yes | Matching datasets. |
| totalCount | Yes | Total matching datasets in the catalog (for pagination). |
| appliedFilters | Yes | Filters applied to this query; absent fields indicate no filter on that dimension. Query, category, and tags intersect with each other, but multiple tags union. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, so the read-only nature is already disclosed. The description adds valuable behavioral context: it explains that the catalog includes charts/maps/stories/files/links, that columnCount=0 identifies those entries, and that they yield no data from other tools. This goes beyond the annotation and helps agents avoid fruitless queries.
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 the primary purpose, followed by a relevant caveat and an alternative tool pointer. No wasted words; every sentence earns its place. Well-structured and appropriately sized for the tool's complexity.
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?
With an output schema present, the description needn't detail return fields, but it still lists key result fields. It explains the non-dataset caveat and points to the schema tool. The 7 parameters are fully documented in the schema, and readOnlyHint covers safety. The description is complete enough for effective use, though it doesn't explicitly address pagination, which the schema already covers.
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 itself only briefly mentions 'keyword, category, or tag' as search dimensions, which adds a high-level mapping to query, category, and tags parameters. But the schema's own parameter descriptions are comprehensive, so the description adds little beyond that.
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's function: 'Search the CDC dataset catalog by keyword, category, or tag.' It names the specific resource (CDC dataset catalog), the verb (search), and acceptable search dimensions. It also distinguishes itself from siblings by referencing cdc_get_dataset_schema for full column lists, implying this tool is for discovery.
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 context for when to use this tool (searching for datasets) and explicitly directs users to cdc_get_dataset_schema for a full column list, an alternative. It also warns that entries with columnCount 0 are non-dataset assets and 'yields no data from the other tools,' effectively advising against using those with data tools. However, it does not explicitly contrast with cdc_query_dataset or state when not to use discovery.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
cdc_get_dataset_schemaCdc Get Dataset SchemaAFetch the column schema for a CDC dataset — names, data types, descriptions, row count, and last-updated timestamp. Returns the first 100 columns by default; wide datasets continue via column_offset. Get dataset IDs from cdc_discover_datasets.
| Name | Required | Description | Default |
|---|---|---|---|
| domain | No | CDC Socrata host to fetch the dataset from. "data.cdc.gov" (default) and "chronicdata.cdc.gov" front the same catalog, so a four-by-four ID resolves on either and the default works whichever host the dataset was found on. | data.cdc.gov |
| datasetId | Yes | Four-by-four dataset identifier (e.g., "bi63-dtpu"). Obtain from cdc_discover_datasets. | |
| column_limit | No | Columns to return in this call (default 100, max 500). Every dataset under the default arrives whole; past it the response reports totalCount and a nextOffset to pass back as column_offset. Raise this to pull a wide schema in one call. | |
| column_offset | No | Index of the first column to return, for continuing past a previous call (default 0). Columns keep the order the dataset declares, so column_offset plus column_limit walks the schema without gaps or repeats. An offset at or past the column count returns an empty window rather than an error. |
| Name | Required | Description |
|---|---|---|
| cap | No | The column_limit that bounded this response. |
| name | Yes | Dataset display name from the catalog (e.g., "Provisional COVID-19 Deaths by Sex and Age"). |
| shown | No | Number of columns returned in this response. |
| notice | No | Guidance when the response is a subset of the schema — which columns it covers, how to reach the rest, or that column_offset ran past the end. |
| columns | Yes | The requested window of dataset columns, with full types and descriptions. Bounded by column_limit/column_offset; the enrichment fields say how the window sits in the whole schema. |
| rowCount | No | Total number of rows when reported by upstream; omitted when unknown. |
| truncated | No | True when the returned columns are a subset of the schema. Absent means every column of the dataset is in this response. |
| updatedAt | No | Last data update timestamp when provided. |
| nextOffset | No | Value to pass as column_offset on the next call to continue after the last column returned. Present only when columns remain beyond this window. |
| totalCount | Yes | Total columns in the dataset schema, before column_limit/column_offset. |
| description | No | Dataset description when provided. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses key behaviors: it returns column metadata including row count and timestamp, defaults to 100 columns, supports pagination via column_offset, and handles offsets past the column count gracefully (returns empty window, not error). This adds value beyond the readOnlyHint annotation by detailing what the response contains and how pagination works.
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: the first clearly states purpose and return fields, the second covers pagination and ID source. It is front-loaded, no wasted words, and all information is relevant. 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 an output schema (so return format is covered), annotations (readOnlyHint), and 4 parameters with full schema descriptions, the description completes the picture by explaining pagination behavior and cross-referencing the discovery tool. No gaps remain for an agent to invoke it 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 description coverage, each parameter already has detailed explanations (defaults, enum, pattern, constraints, behavior). The description adds minimal new parameter info but reinforces the datasetId source (cdc_discover_datasets) and summarizes pagination, providing a convenient overview. Baseline is 3, and the summary adds marginal clarity.
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 states the specific verb "Fetch" and resource "column schema for a CDC dataset", listing the returned fields (names, data types, descriptions, row count, timestamp). It distinguishes from siblings by focusing on schema rather than discovery or querying, and explicitly references cdc_discover_datasets for obtaining dataset IDs.
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 tells the agent to get dataset IDs from cdc_discover_datasets, indicating a prerequisite. It also explains pagination behavior with column_offset and column_limit. However, it does not explicitly contrast with sibling tools (e.g., when to use cdc_query_dataset instead), relying on tool names to imply different purposes.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
cdc_query_datasetCdc Query DatasetAExecute a SoQL query against any CDC dataset. Supports filtering, aggregation, sorting, full-text search, and field selection. Use cdc_discover_datasets to find dataset IDs and cdc_get_dataset_schema to inspect columns before querying.
| Name | Required | Description | Default |
|---|---|---|---|
| group | No | SoQL GROUP BY clause. Requires aggregate functions in select. | |
| limit | No | Max rows to return (default 100, max 5000). Fewer come back when the page would cross the 200,000-character response budget; the response says so and gives a nextOffset to resume from. | |
| order | No | SoQL ORDER BY clause. Field name with optional ASC/DESC: "total_deaths DESC". Set one whenever paging with offset: SODA does not order results implicitly, so consecutive offsets without a deterministic order can skip or repeat rows. When the dataset has no natural unique column, Socrata's documented minimum tie-breaker is the system field `:id`, present on every dataset — order=":id". | |
| where | No | SoQL WHERE clause. Strings must be single-quoted: "state='California' AND year=2020". If a column name matches a SoQL keyword (group, select, where, order, limit, offset, having, search), wrap it in backticks: "`group`='By Year'". | |
| domain | No | CDC Socrata host to query. "data.cdc.gov" (default) and "chronicdata.cdc.gov" front the same catalog, so a four-by-four ID returns the same rows from either and the default works whichever host the dataset was found on. | data.cdc.gov |
| having | No | SoQL HAVING clause. Filters aggregated results. | |
| offset | No | Row offset for pagination (max 1,000,000). Pair with a deterministic order clause — an offset walk over unordered results can skip or repeat rows. | |
| search | No | Full-text search across all text columns. For precise filtering use the where parameter instead. | |
| select | No | SoQL SELECT clause — column names, aliases, or aggregates: "state, sum(deaths) as total_deaths". Omit for all columns. To enumerate distinct values of a column, set select to "{column}, count(*) as count" with group="{column}" and order="count DESC". | |
| datasetId | Yes | Four-by-four dataset identifier (e.g., "bi63-dtpu"). Obtain from cdc_discover_datasets. |
| Name | Required | Description |
|---|---|---|
| cap | No | The requested limit that bounded this response. |
| rows | Yes | Result rows with requested fields. Most values are strings (including numbers/dates); geo columns return GeoJSON objects. |
| shown | No | Number of rows returned in this response. |
| notice | No | Guidance when no rows matched, when further rows remain, or when the response budget cut the page short — how to verify filters, resume paging, or broaden the query. |
| rowCount | Yes | Number of rows returned in this response. |
| truncated | No | True when rows exist beyond the ones returned, established by fetching one row more than the limit rather than inferred from the row count. Absent means this response is the complete remainder of the result set. |
| nextOffset | No | Offset to pass on the next call to resume immediately after the last row returned. Present only when further rows exist and the resume point is within the offset ceiling; a deterministic order clause is what makes the walk gap-free. |
| effectiveQuery | Yes | The SoQL clauses sent to Socrata, as `$clause=value` pairs joined by "&". Values read exactly as they were supplied — not URL-encoded — so a clause can be copied back into the matching parameter of another call. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true, so the description doesn't need to restate that it's a read-only operation. The description adds useful behavioral context beyond annotations: full-text search guidance (prefer precise where over search), the ordering constraint for pagination, and the backtick convention for keyword column names. However, it does not disclose that queries may hit rate limits or that the response budget can truncate results even before the limit is reached (though limit description partially covers this). With strong annotations, a 3 is appropriate for the added value.
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 sentence, which is extremely concise. It front-loads the main purpose and lists supported operations efficiently. However, it could be slightly more structured by separating the operations list from the usage recommendations. No unnecessary words, but a bit dense for quick scanning.
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 complexity (10 parameters, 1 required), the existence of an output schema (which describes return values), and full schema coverage, the description covers the essential context: how to prepare (discovery/schema tools), query syntax, and subtle behaviors (order for pagination, keyword escaping). It is not missing critical information for usage. Minor gap: no mention of error handling or what happens with invalid SoQL, but that is often covered by schema validation.
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. However, the description adds significant meaning beyond the schema: it explains the ordering requirement for pagination (e.g., 'SODA does not order results implicitly'), provides a clear example for reproducing distinct values with select+group+order, gives the backtick workaround for SQL keyword column names, explains that domain endpoints return the same data, and details that limit default is 100 but may be reduced due to response budget. These enrichments earn it a 4.
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 a specific verb ('Execute a SoQL query') and resource ('any CDC dataset'), and clearly lists supported operations (filtering, aggregation, sorting, full-text search, field selection). It distinguishes itself from siblings by referencing cdc_discover_datasets and cdc_get_dataset_schema for related tasks, and the sibling tool cdc_query_wonder is implicitly an alternative for querying a different CDC data source.
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 tells the user when to use sibling tools before calling this one ('Use cdc_discover_datasets to find dataset IDs and cdc_get_dataset_schema to inspect columns before querying'). However, it does not clarify when to NOT use this tool (e.g., for non-CDC data or Wonder data via cdc_query_wonder), or provide explicit alternatives for failure cases. This is slightly lacking for a full 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
cdc_query_wonderCdc Query WonderAQuery CDC WONDER for national US mortality statistics — deaths, population, and crude/age-adjusted death rates — across its five mortality databases, selected with the database input: final underlying-cause data for 1999–2020 (the default) or 2018–2024, provisional data running from 2018 through the current year, and two multiple-cause databases covering the same two eras. Break results out by year, age group, sex, and/or race, and filter by ICD-10 cause of death, sex, age group, or year range; on a multiple-cause database, mcd_icd10 additionally matches a cause listed anywhere on the death certificate rather than only the one certified as underlying. Each database holds a different span of years (1999–2026 across all of them) and a request whose year_range falls outside the selected one's span is rejected with that span named. WONDER is a separate CDC system from the Socrata datasets the other cdc_* tools query. Data is national only — sub-national (state/county) breakdowns are not available through the API (CDC vital-statistics policy). Cause of death is a filter, not a grouping. Some measure cells come back as a CDC status token rather than a number — "Suppressed" (withheld for confidentiality), "Unreliable" (a rate from fewer than 20 deaths), or "Not Applicable" (no population denominator); those cells read null in rows and each one is listed in cellNotes with its token. CDC also drops whole rows before sending the table — strata with zero deaths, and strata whose death count is suppressed — so a stratum can be missing from rows entirely; messages carries CDC's statement whenever that happened. The whole table comes back by default; a broad grouping can run past a thousand rows, so set limit to take it a page at a time and follow the nextOffset the response reports. Paging shapes the response only — WONDER is asked once either way, and the figures, caveats and hidden-row notices are the same on every page. CDC rejects requests made less than 15 seconds apart across all five databases, so consecutive calls are spaced automatically and a follow-up call may wait about 16 seconds before it runs.
| Name | Required | Description | Default |
|---|---|---|---|
| sex | No | Filter by sex. | all |
| limit | No | Rows to return from the table CDC sent (1–5000). Omit to return the whole table. WONDER's request carries no limit of its own, so this pages a table already fetched in full rather than narrowing the query: the deaths, rates, caveats and hidden-row notices are the same whichever page is read. A four-dimension grouping can run past a thousand rows, so set this and follow nextOffset to walk them. | |
| offset | No | Index of the first row to return, for continuing past a previous call (default 0, max 10,000). Rows keep the order CDC returned them in, which is stable for a given query, so offset plus limit walks the table without gaps or repeats. An offset at or past the row total returns an empty page rather than an error. | |
| database | No | Which WONDER mortality database to query. "underlying_1999_2020" (D76) is final data for 1999–2020 and the default. "provisional" (D176) runs 2018 through the current year, updated weekly, and returns the most recent years labelled e.g. "2025 (provisional)". "underlying_2018_2024" (D158) is settled — not provisional — data for 2018–2024. "multiple_1999_2020" (D77) and "multiple_2018_2024" (D157) record every cause listed on the death certificate; without an mcd_icd10 filter they return the same figures as the underlying-cause database for the same era, so pick one only to use that filter. The two 1999–2020 databases report race in CDC's four bridged groups; the other three use the six single-race groups — figures broken out by race are not comparable between the two families. | underlying_1999_2020 |
| group_by | No | Dimensions to break results out by (1–4), in output-column order — e.g. ["year"], ["year","sex"], ["age_group","race"]. Results are always national. Cause of death is a filter (cause_icd10), not a grouping. "race" resolves to whichever race vocabulary the selected database uses — four bridged groups (Asian and Pacific Islander combined) on the 1999–2020 databases, six single-race groups plus a multiracial category on the others — so a race series from one family cannot be spliced onto one from the other. | |
| mcd_icd10 | No | Filter to deaths with this ICD-10 code recorded anywhere on the death certificate, whether or not it was the underlying cause — e.g. "died with a respiratory condition listed", a population no underlying-cause query can produce. Valid only when database is "multiple_1999_2020", "multiple_2018_2024", or "provisional"; the other databases record only the underlying cause and reject it. "999--999", the withheld-cause marker described under cause_icd10, is offered here too but only by "provisional". Combines with cause_icd10, which keeps meaning the underlying cause. Omit for all causes. | |
| age_groups | No | Restrict to deaths in any of the listed age groups — e.g. ["25-34","35-44"] covers both. "1" is the under-1-year group. "NS" is the group CDC puts a death in when the age was not recorded; it is not covered by any of the ten-year groups, so a filter listing all eleven of those still leaves those deaths out and returns fewer deaths than the same query unfiltered. List "NS" alongside them to match an unfiltered total, or on its own to count them. Omit for all ages, which includes them. | |
| year_range | No | Inclusive year range. These bounds span every database (1999–2026); the years the selected one actually holds are narrower, and a range outside them is rejected with that database's span named. Omit for all years the database holds. | |
| cause_icd10 | No | Filter to a specific ICD-10 underlying cause of death — the single condition CDC certified as having started the chain of events leading to death. Omit for all causes. Accepted by every database. "999--999" is not an ICD-10 code but CDC's own marker for deaths whose cause it is still withholding under the provisional database's six-month reporting lag; it counts that backlog, and only the "provisional" database offers it. |
| Name | Required | Description |
|---|---|---|
| cap | No | The requested limit that bounded this response. |
| rows | Yes | Result rows. Each carries the requested group-by dimensions plus deaths, population, crude_rate, and age_adjusted_rate (per 100,000) when age standardization is possible — it is omitted when age_group is a grouping dimension or age_groups selects a single group. Dimension values are CDC's own labels with only surrounding whitespace removed, so the same year keys identically across databases; nothing inside a label is changed, and on the provisional database a year reads "2025 (provisional)" or "2026 (provisional and partial)" rather than a bare year. A measure cell CDC returned as a status token instead of a number is null here; cellNotes names the cell and the token. When limit or offset is set these are one page of the table CDC sent, in its order; totalCount says how many rows the whole table holds. |
| shown | No | Number of rows returned in this response. |
| notice | No | Guidance when no rows matched, when the returned rows are a page of a larger table or the offset ran past it, and a note when CDC returned a status token in place of a measure value. |
| caveats | Yes | CDC-provided caveats and footnotes: data revisions, population-estimate sources, suppression and rate-reliability rules. They describe the whole table CDC assembled, so they come back complete on every page rather than scoped to the rows returned. |
| database | Yes | WONDER dataset code the rows came from — e.g. "D76", "D176", "D157". |
| messages | Yes | Notices CDC attached to this table, verbatim. The ones that matter say rows were withheld before the table was sent — "Rows with zero Deaths are hidden." and "Rows with suppressed Deaths are hidden." A withheld row is absent from rows entirely, with nothing in the table marking the gap, so while this array is non-empty a stratum missing from rows may have been dropped rather than unobserved, and any count, ranking, or completeness claim drawn from rows is partial. These describe the whole table, so they come back complete on every page. Empty when CDC withheld no rows. |
| rowCount | Yes | Number of rows returned in this response — the page size when limit or offset is set. |
| cellNotes | Yes | One entry per measure cell CDC returned as a status token rather than a number, covering the rows in this response only. Those cells read null in rows, so this is what tells a withheld value apart from an unreliable one or a genuinely absent one. |
| truncated | No | True when rows remain past the ones returned. Absent means this response runs to the end of the table, which is also the case for an offset past it. |
| nextOffset | No | Offset to pass on the next call to resume immediately after the last row returned. Present only when further rows remain. |
| totalCount | Yes | Rows in the whole table CDC returned, before limit/offset. Exact rather than estimated — the table is parsed in full before a page is taken from it. |
| databaseTitle | Yes | CDC's own title for that database, e.g. "Underlying Cause of Death, 1999-2020". Names the era and record type the rows describe, so a result read on its own is self-describing. |
| effectiveQuery | Yes | Human-readable summary of the grouping and filters sent to WONDER. |
| suppressedCount | Yes | How many cellNotes carry the "Suppressed" token — cells CDC withheld for confidentiality. Counted over the rows in this response, so it tracks the page rather than the whole table. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses many behavioral traits beyond the readOnlyHint annotation: suppressed values return as null with cellNotes, CDC drops rows with zero deaths or suppressed counts, whole table is fetched regardless of paging, rate limiting with auto-spacing, and that 'year_range outside the selected database's span is rejected with that span named.' The description adds significant context about error handling, response caveats, and CDC's internal behavior.
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 thorough but somewhat verbose (approximately 500 words). While every sentence provides useful information, it could be more concise by grouping related details (e.g., paging behavior is explained in two separate places). However, the structure is logical: purpose first, then database details, then filtering, then paging, then rate limiting. It is front-loaded with the core purpose. The length is justified by the tool's complexity.
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 complexity (9 parameters, nested objects, multiple databases, edge cases with suppressed values and hidden rows), the description is remarkably complete. It covers what the tool does, how to use each parameter, error cases, and behavioral nuances. The output schema exists, so return values are documented separately. The description leaves no major gaps for an AI agent to safely invoke this 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%, but the description adds substantial value beyond the schema. For example, it explains the race vocabulary difference between database families, the meaning of the 'NS' age group, the '999--999' withheld-cause marker, and that cause_icd10 is a filter not a grouping. It also clarifies paging semantics (CDC is queried once, paging shapes only the response). These details are not present in the schema descriptions.
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 opens with a clear statement of the tool's purpose: 'Query CDC WONDER for national US mortality statistics — deaths, population, and crude/age-adjusted death rates — across its five mortality databases.' It immediately distinguishes itself from sibling tools by noting that WONDER is a separate system from the Socrata datasets the other cdc_* tools query. The verb 'query' and resource 'CDC WONDER' are specific and 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 provides extensive when-to-use guidance: it explains the differences between the five databases, when to use multiple-cause vs. underlying-cause, how to handle paging (limit/offset), the 15-second rate limit with automatic spacing, and that sub-national data is not available. It also explains when not to use certain features (e.g., mcd_icd10 only valid on multiple-cause databases, cause_icd10 is a filter not a grouping). This is highly actionable for an AI agent.
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.
No comments yet. Be the first to start the discussion!
Sign in to create a connector for this server.
