Server has 5 tools with visible input schemas and descriptions. Naming is action-verb-based (search_, get_), which is good. However, descriptions are uniformly terse (6-25 chars), providing minimal context for LLM tool selection. Parameter descriptions exist but lack format constraints, ranges, and dependency documentation. Output schemas are not formally documented, responses are returned as JSON-stringified text blobs rather than structured objects. Error handling is basic (generic catch-all console.error) with no recovery guidance. No tool annotations (readOnlyHint, etc.) despite all tools being READ_ONLY. Overall quality is below-average for a production agent toolkit.
Descriptions are critically short (6 - 25 characters). Baseline is 194 chars; these provide almost no context for LLM tool selection. E.g., 'Search for flights' (17 chars) does not explain when to use search_flights vs search_multi_city, what data it returns, or prerequisites.
Parameter descriptions lack format and constraint details. E.g., 'departureDate' says 'Departure date in YYYY-MM-DD format' but does not state validation rules (must be future, minimum/maximum range). 'adults' has no bounds (minimum is 1, but no maximum documented). 'cabinClass' enum is defined, but descriptions for enum values are missing.
Output schema is not documented. Tools return raw JSON.stringify() responses without a declared schema. LLMs cannot predict what fields are present, making downstream tool chaining fragile. E.g., does search_flights return 'offer_id' or 'offerId'? Does it include 'total_count' for pagination?
Recommendations
Expand all tool descriptions to 100 - 250 characters. Example: 'search_flights' should explain: 'Search for one-way, round-trip, or multi-city flights. Returns a list of offers with pricing, airlines, and departure/arrival times. Use search_flights for simple queries; use search_multi_city for trips with 3+ segments. All prices are in the search request's currency.'
Document parameter constraints in descriptions. For 'adults', add: 'Number of adult passengers (1 - 9; some airlines may have limits).' For 'departureDate', add: 'Must be a future date (today or later); format YYYY-MM-DD.'
Formalize output schemas. Attach a TypeScript interface or JSONSchema to each tool showing what fields are returned. E.g., search_flights returns { offers: Array<{offer_id: string, price: number, ...}>, total_count: number }.
Add readOnlyHint annotations to all 5 tools. Modify server.tool() calls to include { readOnly: true } or similar (check MCP SDK docs for the exact annotation syntax for v1.9.0).
Implement pagination: add 'limit' (1 - 50, default 20) and 'offset' (0 - 1000, default 0) parameters to search_flights and search_stays. Return 'total_count' in responses so agents know if more results exist.
Improve error messages. Instead of throwing generic errors, return structured error objects with 'code' and 'suggestion' fields. E.g., { error: 'missing_return_date', message: 'Round-trip flights require a returnDate. Provide the return date in YYYY-MM-DD format.', suggestion: 'Ask the user when they want to return.' }.
No tool annotations (readOnlyHint, destructiveHint, idempotentHint) despite all 5 tools being READ_ONLY. This metadata would help agents reason about idempotency and side effects.
Error handling is generic. All errors are caught, logged, and re-thrown with no guidance. E.g., 'Return date required for round-trip flights' (in search_flights) is a user-fixable error, but the LLM receives no hint to ask the user or suggest a correction.
No pagination support documented. search_flights and search_stays likely return large result sets, but tools do not accept limit or offset/cursor parameters. Agents cannot control response size, risking context window exhaustion.
Parameter naming inconsistency. search_stays uses snake_case ('check_in_date', 'check_out_date'), while search_flights uses camelCase ('departureDate', 'returnDate'). This forces the LLM to remember different conventions for similar concepts.
search_flightssearch_stays
Standardize parameter naming to snake_case across all tools. Rename 'departureDate' → 'departure_date', 'cabinClass' → 'cabin_class', etc. This reduces cognitive load on agents.
Document dependency relationships. In search_flights, the 'returnDate' parameter is required only if type='round_trip'; the 'additionalStops' parameter is required only if type='multi_city'. Add a note: 'returnDate: required if type=round_trip; additionalStops: required if type=multi_city.'
Add validation examples in parameter descriptions. E.g., 'origin: IATA airport code (SFO, LAX, JFK) or city code (NYC, LON). Must be different from destination.'
Document rate limits and timeouts. search_flights sets supplier_timeout to 15s (30s for multi-city). Explain to users: 'Searches may take up to 30 seconds. If a timeout occurs, retry, it may have succeeded server-side.'