Descriptions are too brief (10-65 chars vs 50-200 char ideal). Examples: 'Returns information about the current user based on their JWT token.' (66 chars) lacks WHEN to use it or what fields are returned. 'Get the user's participation status in Airline and Hotel Loyalty programs' (76 chars) doesn't explain next steps or data format.
No output schemas documented in code. For example, list_bookings says 'Get an overview' but doesn't specify: is return value a list or object? What fields exist on each booking? Does it include booking_id, hotel_name, flight_number, dates? LLMs cannot plan downstream calls without this.
Expand all descriptions to 50-200 chars. Example for book_flight: 'Book a confirmed flight reservation. WHEN: Call after find_flights returns available options. REQUIRES: flightNumber (from search), departure date, class (enum: economy|business|first), optional frequent flyer number. RETURNS: booking_id, confirmation_number, total_price, seat_info. NOTE: This commits to payment, request user confirmation before calling.'
Document output schemas explicitly. Add a 'Returns' section to each tool description or metadata. Example: 'list_bookings returns {bookings: [{booking_id, type, hotel_name|flight_number, check_in|departure, total_price, status}], total_count}'
Convert free-form enums to strict enums in parameters. flightClass should be enum: ['economy', 'business', 'first']. roomType should be enum: ['single', 'double', 'suite', 'deluxe']. Replace examples with constraints.
Add dependency and sequencing hints. Example: 'Call find_flights first to get available flight_ids and prices. Then pass the flight_number and departure date to book_flight with your preferred class and frequent flyer number (optional).'
Include error recovery hints. Example for book_flight: 'If flight is fully booked, call find_flights with nearby dates. If user has already booked this flight, list_bookings will show it.'
Add a confirmation/dry-run capability for booking tools. Optionally: add a 'confirm' parameter defaulting to false. If false, return estimated cost and ask agent to call again with confirm=true. This prevents accidental bookings.
Score history
Overall score trend
↓ 14 points across a rubric change (v1 → v2)
35/100
Scored
Grade
Overall
Spec posture
Rubric
2026-09-22
F
35
<=2025-11-25
v2
2026-03-09
F
49
-
v1
Parameter descriptions lack actionable constraints. Example: book_flight requires 'flightClass' (type: string, no enum), description says 'Flight class (e.g., economy, business, first)' but gives examples instead of hard enum. LLMs will hallucinate values like 'premium economy' or 'first class' (two words).
No error handling guidance in descriptions. Tools don't state: what if the user has no bookings? What if a flight is already booked? What if hotel is full? Without recovery hints, agents cannot self-correct on failures.
Ambiguity between similar tools. find_flights vs book_flight, description doesn't explain: what do you get from find_flights that you pass to book_flight? Are you required to call find_flights first? Can you book directly by flight number? This wastes agent reasoning cycles.
Returned fields unclear for list_* tools. list_bookings and list_hotels accept filters and limits but descriptions don't state: are results paginated? What's the max result count? What fields does each booking/hotel object contain? Required for agents to extract IDs for downstream calls.
book_flight and book_hotel missing confirmation/dry-run pattern. These are irreversible state mutations (bookings commit to payment) but descriptions don't mention any confirmation step. Agents can mistake test runs for real bookings.
book_flightbook_hotel
Clarify what 'Optional booking type filter' means in list_bookings. Does 'type' mean 'show only bookings of type X' or 'filter by some other type field'? Reword: 'Filter results by booking type (HOTEL, FLIGHT, or ALL for both). Defaults to ALL.'
Document pagination for list_bookings and list_hotels. Add parameters: 'limit' (default 20, max 100) and 'offset' (default 0). Document response includes 'total_count' and 'has_more' so agents know if they need to paginate.
Specify date format precisely in descriptions. Instead of 'in ISO 8601 format', say 'ISO 8601 date string, e.g. 2025-03-15 (no time component)'. LLMs frequently mis-format dates.
Add hints about natural identifiers. For loyalty_info and whoami, clarify: 'Automatically resolved from JWT token, no parameters required.' For list_bookings, state: 'Filters are optional; without filters, returns all user bookings.'