Static source inference · medium confidence · evidence: Streamable HTTP
Current-spec patterns detected
Summary
The CDC PLACES server has only 2 tools with minimal inline documentation. Tool names are clear action verbs (get_, area_), but parameter definitions, input schemas, and output structures are not visible in the provided source code. The descriptions are present but generic and lack depth about when/why to use each tool or what the agent should expect. Without seeing the actual schema definitions in src/places/tools.py, I cannot verify parameter types, enum constraints, pagination support, or output field documentation. The server uses fastmcp (HTTP transport) which is positive, but the lack of visible schema definitions and thin descriptions indicate definition quality issues typical of early-stage community tools.
Tools (2)
area_summary_statsread only33/100
Generate summary statistics for health metrics in a geographic area
Input schemas not visible. Tool definitions use 'get_cdc_places_data' and 'area_summary_stats' but no JSON Schema or parameter type definitions appear in provided source.
Descriptions lack depth and specificity. 'Retrieve CDC PLACES data for specified locations' (46 chars) does not explain WHEN to use this tool vs alternatives, what LOCATIONS means (state, county, zip?), what data fields are returned, or whether results are paginated. Descriptions should be 50-200 chars with actionable context.
No visible parameter descriptions. Tool implementations must list each parameter with a type and description (e.g., 'location (string, required): The geographic area as a state abbreviation, FIPS code, or zip code'). This is critical for LLM reasoning.
get_cdc_places_dataarea_summary_stats
Recommendations
Create a schema.json or explicit schema in the tool registration showing input/output types. Example: get_cdc_places_data should declare location (string, enum or pattern), data_categories (array of string with enum constraints like ['health_outcomes', 'health_risk_factors']), limit (integer 1-1000, default 20), offset (integer ≥0, default 0). Output should declare structure: {results: [{location_id, location_name, state_code, fips_code, metrics: [{indicator_name, value, unit, year}]}], total_count, next_offset}.
Expand descriptions to 80-150 characters. Example: 'Retrieve CDC PLACES health indicators for a US state, county, or zip code. Returns prevalence data for chronic diseases, health behaviors, and clinical care. Use this to understand health outcomes in a geographic area before requesting area_summary_stats.'
Add parameter descriptions to each tool definition. Example for get_cdc_places_data: 'location (required, string): The geographic area as a 2-digit state code (e.g., 'TX'), 5-digit FIPS county code (e.g., '48001'), or 5-digit zip code (e.g., '75001'). data_categories (optional, array): Filter results to specific health metric types. If omitted, returns all categories. Allowed values: health_outcomes, health_risk_factors, clinical_care, social_determinants. limit (optional, integer 1-1000, default 20): Maximum results per request. offset (optional, integer ≥0, default 0): Pagination offset for large result sets.'
Document the output schema explicitly. Example: 'Returns a JSON object with fields: results (array of location records), total_count (integer), next_offset (integer or null if end reached). Each location record includes: location_id (string), location_name (string), state_code (string), fips_code (string), metrics (array of {indicator_name, value, unit, year}).'
Output schema not documented. Agents need to know what fields 'summary statistics' or CDC data records contain, what types they are (numeric, string, date), and which fields are required vs optional. Undocumented responses force LLMs to guess field names.
No pagination or result limits visible. If 'get_cdc_places_data' can return hundreds of health indicators per location, there must be limit/offset parameters and a total_count or next_cursor in the response. Large unparameterized results blow context windows.
No error handling guidance. If a location is invalid or unavailable, the tool response must guide the LLM: 'Invalid FIPS code 99999. Valid FIPS codes are 2-digit state + 3-digit county (01001 - 56045). Did you mean county code 01003?' Instead of a raw 404 or validation error.
get_cdc_places_data
Add 'Available locations' guidance to error responses. If a user requests an invalid or unsupported location, return available state codes or sample supported counties to guide the agent toward a valid call.
For area_summary_stats, clarify what 'health metrics' are aggregated and over what geographic scope. Is this a summary of all metrics from get_cdc_places_data? Does it aggregate across sub-areas (e.g., all counties in a state) or analyze one area? Add a parameter description: 'location (required, string): The location key from get_cdc_places_data results (state code, FIPS code, or zip). Calculate aggregate statistics across all health indicators for this area. metric_aggregations (optional, array): Which summary statistics to compute. Allowed values: mean, median, percentile_25, percentile_75, min, max. If omitted, returns all.'
Consider adding a tool to list available locations, metrics, or data years. E.g., list_cdc_locations() returns {states: [array], available_counties: {state_code: [array of counties]}, latest_data_year: 2023}. This enables agent discovery without hardcoding assumptions.