This is a well-constructed flight search MCP server with 13 tools, all with complete input schemas and descriptions. Naming follows verb_noun conventions consistently (search_flights, get_prices_calendar, lookup_airlines, etc.). Descriptions are action-oriented and typically 80-180 characters, explaining what each tool does and when to use it. All parameters have type definitions and descriptions. The server includes proper error handling with timeout logic (30s default, MAX_RETRY_DELAY=30s), retry logic with exponential backoff, and quota monitoring. Tool annotations (_READ_ONLY hints) are correctly applied to all 13 tools. However, there are gaps: (1) output schemas are not explicitly documented in the source (return types are not visible), (2) some parameter descriptions reference external APIs without full context (e.g., 'Travelpayouts quota'), (3) no structured error recovery guidance in tool descriptions, (4) parameter descriptions could include more format/constraint examples. The server uses fastmcp with proper async/await patterns, config-driven settings, and clean separation of concerns. The codebase is production-grade (Python 3.12+, type hints, tests, linting), but tool documentation is incomplete on the output side.

• Add explicit output schema documentation to every tool. For each tool, document the return type as a structured object with field names, types, and descriptions. E.g., 'Returns: { flights: [{id: string, airline: string, price: number, departure: ISO8601, ...}], total_count: number }'
• Enhance error handling guidance in tool descriptions. Add sentences like: 'May fail with quota exceeded (wait 1 hour), invalid airport code (use lookup_airports first), or date out of range. On error, try with fewer filters or alternative dates.'
• Replace example values in parameter descriptions with format constraints. Instead of '(e.g. MOW, BKK)', use '(IATA code, 3 uppercase letters)'. For dates, state explicitly: 'Format: YYYY-MM-DD or YYYY-MM for month-level searches.'
• Document parameter relationships and mutual exclusivity. E.g., for search_flights: 'departure_at is required. return_at is optional; if provided, enables round-trip search. max_transfers is not compatible with direct=true.'
• Add pre-call dependencies to tool descriptions. E.g., 'Requires valid IATA codes for origin/destination. If you have city names, call lookup_cities or lookup_airports first.'
• Document result limits and pagination for all tools returning lists. State: 'Returns up to {limit} results. If more exist, results are truncated; use limit and sort parameters to paginate.'
• Add currency and market parameter validation notes. Clarify acceptable values (e.g., 'currency: ISO 4217 code like USD, EUR, RUB') and default behavior when omitted.

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

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