Input schemas not visible in source code. Tool definitions reference 'DemographicsParameters', 'FailuresParameters', etc., but actual JSON Schema structures with type definitions, property descriptions, and constraints are not shown.
Generic, boilerplate descriptions that repeat 'Returns X' pattern without explaining WHEN to use each tool or how they differ. Example: 'Get Summary of Demographic Information - Returns summary of demographic information - Demographics' (91 chars). Descriptions lack specificity about use cases, required filters, or relationship to other tools.
Make input schemas explicit and visible in source. Define a JSON Schema for each parameter object with 'type': 'object', 'properties' with individual field descriptions, 'required' array, and type constraints (e.g., 'filters': {'type': 'string', 'description': 'Filter expression in FDIC API syntax, e.g., 'STATE=CA' or 'ASSET>1000000''}). See src/handlers/mod.rs tool registration.
Expand tool descriptions to 150-250 characters. Example: 'Get Summary of Demographic Information for all FDIC-insured banks. Use this to answer questions about depositor counts, deposit amounts, or branch distribution by location. Supports filtering by state, county, and asset size.' This clarifies WHEN to use it.
Add per-parameter descriptions in schema. For 'filters': 'String of filter conditions separated by &. Examples: STATE=NY, ASSET>500000. See FDIC API docs for full syntax.' For 'limit': 'Max results (1-10000, default 100).' For 'offset': 'Result set pagination offset (0-based). Use with limit for pagination.'
Document output schema for each tool. Add a 'response_schema' field or README section showing example JSON response, field types, and total_count/next_cursor pagination fields. This enables LLM to extract institution_id, state, asset values, etc., for downstream reasoning.
Remove 'ping' tool or move to server diagnostics. It adds no value to the data access API surface and should not be callable by agents.
Add error handling documentation. For each tool, document: (1) Invalid filter syntax → returns 400 with FDIC error code and suggestion. (2) No results → returns empty array with count=0 (not an error). (3) API timeout → returns 504 with guidance 'Retry with smaller limit or more specific filters.' This teaches the LLM recovery paths.
Parameter descriptions missing or abstract. All 8 tools accept 'CommonParameters' (api_key, filters, fields, sort_by, sort_order, limit, offset, file_format, file_download, file_name) but no per-parameter descriptions visible. LLM cannot understand: What is 'filters' format? What are valid 'file_format' values? What is 'offset' range? Per pattern, every parameter must have a non-empty description explaining what it controls.
Output schema not documented. Tools return FDIC API responses, but no schema documentation is visible for response structure, field types, or pagination hints. LLM cannot plan downstream composition (e.g., extract institution_id for chaining calls) without knowing response shape.
Ping tool is non-idiomatic. Health checks should not be exposed as callable tools to LLMs. This tool has risk=READ_ONLY, empty input {}, and trivial semantics ('Returns MCP server status for Inspector/health validation'). It wastes the LLM's reasoning cycles and clutters the tool palette. Remove it or move to server lifecycle.
No error handling guidance. Tools do not document what happens on invalid filters, missing fields, API failures, or empty result sets. LLM will not know whether to retry, ask the user, or treat it as unrecoverable.
Consider grouping tools by domain or adding discovery helper. Since all 8 tools follow the same pattern, add a 'describe_fdic_datasets' tool that returns brief summaries of each (Demographics: depositor counts; Failures: historical bank closures; Institutions: current institution directory, etc.). This helps LLM select the right tool first.
Add enum constraints for common parameters. For 'file_format', add 'enum': ['json', 'csv', 'xml']. For 'sort_order', add 'enum': ['asc', 'desc']. This eliminates hallucinated values.
Document pagination limits. Add to each tool description: 'Supports pagination via limit (max 10000) and offset parameters. Use these to fetch large result sets incrementally. Always include limit and offset in repeated calls to ensure stable pagination.'