FastAPI-based backend for a healthcare appointment booking system with AI-powered chat agent that helps patients book appointments and doctors manage their schedules
Three tools with complete JSON schemas and clear descriptions. Naming follows verb_noun convention (get_*, create_). However, descriptions are brief (34-56 chars, below the 50-200 char LLM-optimized baseline), parameter descriptions lack detail on constraints and formats, and error handling is not visible in the code. No output schema documentation. Role-based access control is implemented server-side (good security), but tool composition could be tighter, create_appointment requires both start/end times rather than accepting duration, forcing the agent to calculate.
Create a new appointment for the current patient with a doctor
Get appointment statistics for the current doctor
Get available appointment slots for a doctor on a specific date
Descriptions are too brief (34-56 chars vs. 50-200 char baseline). 'Get appointment statistics for the current doctor' lacks context on when to use it, what it returns, or how it differs from availability queries.
Parameter descriptions lack actionable constraints. 'Date in ISO format (YYYY-MM-DD)' is stated but no validation guidance. 'Timeframe: today, yesterday, or tomorrow' should be an enum constraint, not free-form string.
No output schema documentation visible. Callers cannot see what fields AvailabilityResponse, AppointmentResponse, or DoctorStatsResponse contain, forcing LLMs to guess downstream field names for chaining.
Inferred effective spec: <=2025-11-25.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | D | 58 | <=2025-11-25 | v2 |
create_appointment requires both 'start' and 'end' ISO datetimes, forcing the agent to calculate end time. Accepting duration_minutes or slot_id would reduce cognitive load and match the availability query pattern.
No error handling guidance in tool definitions. If doctor_name is not found, the code raises ValueError, but the tool description does not explain recovery steps (e.g., 'Call search_doctors first').