Loading ToolBench
MCP server for accessing US Census Bureau data as tools
Single tool 'census/get' has a clear, action-verb name and reasonable description (54 chars), but multiple critical definition gaps significantly limit its production-readiness. The tool schema is properly structured with JSON Schema types and descriptions for all parameters, meeting baseline requirements. However, the parameter descriptions lack actionable context, expected value formats, and constraints. The tool lacks any output schema documentation, error handling guidance, pagination support, or data limiting patterns despite potentially retrieving large Census datasets. No per-parameter constraints (enums, min/max, patterns) are enforced. No security documentation for API key handling beyond the brief 'Optional Census API key override' note. The implementation shows competent HTTP/JSON-RPC handling but falls short of agent-tool patterns for discovery, error recovery, and result structuring.
Retrieve data from the US Census Bureau API
No output schema documented. Tool returns JSON-formatted Census API data as plain text, but LLMs cannot determine what fields to expect or plan downstream tool calls. Census Bureau API responses vary by dataset; documentation should specify structure and typical fields returned.
Parameters lack format constraints and actionable descriptions. 'year' has no range (e.g., 1990-2024); 'dataset' has no enum of valid endpoints (e.g., acs/acs5, acs/acs1, dec/dhc); 'variables' array has no guidance on variable codes (e.g., 'B01003_001E' for total population); 'for' geography spec has no format explanation (e.g., 'state:06' for California, 'county:06001' for Alameda County). Without these constraints, LLMs hallucinate invalid values.
No pagination or result-limiting pattern. Census API can return hundreds or thousands of rows; no indication of max records returned, pagination cursor, or offset support. Tool description does not warn agents about large result sets that could exhaust context windows. See baseline: 'cap results at a reasonable limit (e.g. 20-50) and offer pagination.'
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-22 | D | 51 | 2026-07-28+ | v2 |
| 2026-03-09 | F | 41 | 2025-03-26+ | v1 |
Error handling lacks recovery guidance. Code returns isError:true with plain text error messages (e.g., 'Census API key not provided', 'HTTPError: 400 Bad Request'). No actionable guidance for LLM: Should it retry? Request input from user? Try a different dataset? See baseline: 'Error responses must tell the LLM what to do next.'
Parameter descriptions are under 20 characters for most params (e.g., 'Year of the data, e.g. 2020' is 30 chars but incomplete). 'Variables to retrieve' (20 chars) lacks guidance on format (Census variable codes, not human-readable names). 'Geography spec' is too vague, 'state:06' example is helpful but description does not explain the colon-separated format or available geographic levels (state, county, tract, block group).
No tool annotation for read-only behavior. Tool makes external Census API calls without modification, but inputSchema lacks readOnlyHint annotation to signal to agents this is a safe, idempotent, read-only query. See pattern:tool for annotation expectations.
API key handling lacks security best practice documentation. Code supports optional 'key' parameter with fallback to CENSUS_API_KEY environment variable. No explicit warning that passing 'key' as a tool parameter will log it in agent traces. Pattern dictates credentials must be server-side only.
Tool description lacks usage prerequisites and discovery hints. LLMs need to know: 'Before calling, ensure you have a Census API key from census.gov. If you don't know which dataset to query, call census/describe_datasets first (if available) or describe your data need in natural language.'