Flight MCP Server has solid naming conventions and complete input schemas for all four tools. Tool names follow verb_noun patterns (search_flights, get_airport_info, get_flight_status, get_airline_info) which is excellent. All tools have descriptions and properly typed JSON Schema inputs with parameter descriptions. However, critical gaps exist: (1) NO documented output schemas, the code returns types.TextContent but doesn't specify what fields are in the response text or structured format; (2) minimal error handling guidance, validation errors are caught but LLM guidance on recovery is limited; (3) no tool annotations (readOnlyHint, destructiveHint, idempotentHint); (4) parameters lack some constraints (e.g., adults has min/max but return_date has no format validation detail in description); (5) no pagination support declared despite search_flights likely returning multiple results. The server is functional and well-structured but lacks production-grade polish around output documentation and error recovery patterns.

• Document the output schema for each tool. For search_flights, specify: 'Returns {flights: [{airline: string, flight_number: string, departure: ISO8601_datetime, arrival: ISO8601_datetime, duration_minutes: integer, price_usd: number, available_seats: integer}], total_results: integer}'. For get_airport_info, specify: 'Returns {iata_code: string, name: string, city: string, country: string, timezone: string}'. Apply similar structure to get_flight_status and get_airline_info.
• Add pagination to search_flights: introduce 'limit' (default 20, max 100) and 'offset' (default 0) parameters. Update description: 'Returns up to 20 matching flights, ordered by price. Use offset and limit for pagination.'
• Enhance error messages with actionable guidance. In error_handler.py, when airport_code validation fails, return: 'Invalid airport code "ABC", expected 3-letter IATA code. Example valid codes: LAX, JFK, ORD. Call search_airports() if unsure.' Similarly for flight_number validation.
• Add tool annotations to tool definitions. Wrap each Tool() with readOnlyHint=True since all are query-only, no state modification. Example: types.Tool(name='search_flights', description='...', inputSchema={...}, readOnlyHint=True).
• Expand tool descriptions to 80 - 150 characters. Example for get_airport_info: 'Get airport details including name, city, country, and timezone. Pass IATA 3-letter code (e.g., LAX, JFK, ORD). Returns airport metadata needed for itinerary planning.'
• Add parameter validation context to descriptions. For return_date in search_flights, update: 'Return date in YYYY-MM-DD format (optional for one-way flights). Must be on or after departure_date if provided.' For adults, note: 'Number of adult passengers (1 - 9, default 1).'

Inferred effective spec: <=2025-11-25.

• Relies on Logging (deprecated) - log to stderr or use OpenTelemetry