JFK MCP server has well-structured schemas with proper Zod validation and clear parameter types. Tool names follow verb_noun convention (search, get). However, descriptions lack depth and actionability. Most tool descriptions are under 100 chars and do not explain WHEN to use each tool vs. alternatives (e.g., text-search vs. vector-search distinction is unclear). Parameter descriptions are generic ('Filter by X') without guidance on expected formats, operators, or dependencies. Error handling is absent, no recovery guidance or actionable error messages visible in code. Output schemas are not documented in descriptions. The metadata filter structure is sophisticated but underdocumented for LLM reasoning.

• Expand tool descriptions to 100-200 chars. For text-search vs. vector-search, add: 'Use text-search for exact keyword matches (1 word, case-sensitive). Use vector-search for semantic/fuzzy matching across multiple words.' This disambiguates selection.
• Document output schemas in tool descriptions. E.g., 'Returns array of {page_id, document_date, file_name, relevance_score, text_snippet}.' This enables LLMs to chain tools and extract needed fields.
• Add operator examples to metadata filter descriptions. E.g., 'document_date: {operator: "gte", value: "2024-01-01"} or {operator: "between", value: ["2024-01-01", "2024-12-31"]}' so LLMs understand the schema structure.
• Implement error handling with actionable messages. E.g., 'No results found for query "X". Try: (1) broaden query to 2+ words, (2) remove metadata filters, (3) check NARA release date range (2017-2025).' This guides agent recovery.
• Add per-tool limit guidance. Descriptions mention 'default: 25, max: 100' but do not explain when to use smaller limits (faster response, fewer tokens) vs. larger (comprehensive results). Add: 'Use limit=10-20 for quick summaries; limit=50-100 for exhaustive research.'