Provides an optional SMS adapter for sending appointment reminders via Twilio.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@clinic-frontdesk-mcp Book a diabetes follow-up with Dr. Mehta tomorrow at 6 PM."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Give your LLM a front desk.
An open-source MCP server that turns any MCP-compatible client — Claude Desktop, Claude Code, or your own agent — into an AI receptionist for a small medical clinic.
It handles the front desk: booking and rescheduling appointments, registering patients, taking pre-visit intake, sending reminders, and answering questions about timings, fees and location. The LLM is the brain; this server is the hands.
You: Book Mr. Shah with Dr. Mehta tomorrow evening for a diabetes follow-up.
Claude: Dr. Mehta has 6:00, 6:30 and 7:00 PM open tomorrow. Which suits him?
You: 6 PM.
Claude: Booked — Rajesh Shah with Dr. Anjali Mehta on Mon 10 Aug 2026 at 6:00 PM,
for diabetes follow-up. A reminder goes out 24 hours before. Reference #1.
You: He's had a headache for three days, should he take something?
Claude: I can't advise on that one — it's best discussed with the doctor. Dr. Mehta
has 11:00 AM free on Tuesday if you'd like to bring the visit forward.
You: Cancel it, actually.
Claude: That's Rajesh Shah with Dr. Mehta, Mon 6:00 PM, diabetes follow-up.
Shall I cancel it? ← nothing has happened yetBehind those four turns: a patient lookup, a live availability check, a transactional booking, a queued reminder, a clinical question routed away from the model's own opinion, and a destructive action held back for confirmation.
Here is the same conversation from the server's side — the tools the model reaches for, and what comes back. Every line was captured from a real session; nothing here is mocked up.
A calendar with tool descriptions bolted on gets the happy path right and the other paths wrong. The interesting work here is in the failure modes:
The awkward bit | How it's handled |
Two agents grab the same slot at once | Overlap check + insert in one |
Clocks jump forward and back | Non-existent wall-clock slots skipped, ambiguous ones offered once, durations measured in real elapsed time |
"Should he take something for the headache?" | A curated clinical vocabulary short-circuits to the doctor redirect — a rule, not a similarity score that can drift |
The FAQ has no good answer | Returns |
The requested slot is gone | Returns the nearest alternatives, not a bare error, so the conversation keeps moving |
Logs are patient records too | Names collapse to initials, phone numbers are masked, before anything is written |
Related MCP server: MCP Medical Appointments Demo
This server handles logistics only. It has no clinical knowledge and is not a medical device.
No clinical advice. Medical questions return the clinic's standard "please discuss this with the doctor" response, with an offer to book an appointment. This is enforced in code, not left to the model's judgement — see Clinical safety.
No diagnoses stored. Intake records what the patient said, in their words.
Confirmation before destructive actions. cancel_appointment does nothing without an explicit
confirm=true; called without it, it returns a preview to read back to the caller.
Patient data stays on the machine running the server, in a single SQLite file. There are no external calls in v1 unless you explicitly configure the optional Twilio adapter.
Logs go to stderr only (stdout is the MCP transport) and PII is redacted before anything is
written: phone numbers are masked and names collapse to initials. The audit_log table records
every write action in the same redacted form.
The database is not encrypted at rest. Store CLINIC_DB_PATH on an encrypted volume and treat that
file as you would any other patient record.
This server has no screen of its own. It plugs into an app you already talk to — Claude Desktop is the easiest one — and that app grows a set of front-desk abilities. You do the talking; it does the booking.
Setup is five steps and takes about ten minutes. Exactly one of them uses a terminal, and it's a single line you copy and paste.
Download it from claude.ai/download, install it like any other app, and sign in.
uvuv is a small free tool that fetches and runs this server for you. It brings its own copy of
Python, so there is nothing else to install.
Open a terminal — on a Mac press ⌘+Space, type Terminal, press Enter; on
Windows click Start, type PowerShell, press Enter — then paste one of these and press Enter:
# macOS or Linux
curl -LsSf https://astral.sh/uv/install.sh | sh# Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"Close the terminal window when it finishes. That's the last command you'll type.
In Claude Desktop, go to Settings → Developer → Edit Config. That opens a file called
claude_desktop_config.json in a text editor. If you'd rather open it by hand, it lives at:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Replace everything in that file with the block below, then save. If the file already has other
entries under mcpServers, add just the "clinic-frontdesk" section alongside them.
{
"mcpServers": {
"clinic-frontdesk": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/prashant-cr/Clinic-front-desk-MCP-server",
"clinic-frontdesk-mcp"
],
"env": {
"CLINIC_DB_PATH": "/Users/you/clinic-data/clinic.db",
"CLINIC_NAME": "Demo Family Clinic",
"CLINIC_TIMEZONE": "Asia/Kolkata"
}
}
}
}Three things to change for your clinic:
Line | Change it to |
| Where the patient file should live. Windows example: |
| Your clinic's name, as it should read in confirmations and reminders |
| Your timezone, in IANA form — |
Use a full path for CLINIC_DB_PATH, starting from the drive or your home folder. Claude Desktop
doesn't start the server from any particular folder, so a short path like clinic.db ends up
somewhere you won't find it.
Quit it completely — ⌘+Q on a Mac, or right-click the taskbar icon and Quit on
Windows; closing the window isn't enough — then open it again. The first launch takes a few extra
seconds while uv downloads the server.
Look for the tools icon near the message box; clinic-frontdesk should be listed. Then just ask:
Who are the doctors at the clinic?
If you get three doctors and their hours back, you're done. The first run creates the patient file and fills it with a demo clinic — three doctors, four patients and a small FAQ — so you have something to practise on before real data goes in.
Pick the receptionist_system prompt in Claude's prompt menu to put it into a warm, careful
receptionist frame of mind, with the safety rules already in place.
Plain sentences work. There are no commands to memorise.
Say something like | What happens |
"What's free with Dr. Mehta on Thursday afternoon?" | Reads out the open slots |
"Book Mrs. Rao with Dr. Iyer on Tuesday at 11, for a vaccination." | Checks the slot, books it, reads the booking back |
"New patient — Anil Kumar, 98200 12345." | Registers him, or finds him if that number is already on file |
"Move appointment 14 to Friday morning." | Reschedules and moves the reminder with it |
"Cancel appointment 14." | Shows you the appointment and waits for you to confirm |
"What's on today?" | Each doctor's day: appointments, gaps, missing intake forms |
"Do you take insurance?" | Answers from the clinic FAQ, or says it doesn't know |
Ask it a medical question and it won't answer one — it will point the caller to the doctor and offer an appointment. That's deliberate; see What it will not do.
What you see | Try this |
No | Quit Claude Desktop completely and reopen it. Check the config file for a missing comma or bracket |
"command not found: uvx" in the logs |
|
It answers but never books anything | It's answering from memory rather than the tools. Ask directly: "Use the clinic tools to check Dr. Mehta's availability tomorrow." |
Times look wrong |
|
You want to start with an empty clinic | Add |
Everything sits in the single file at CLINIC_DB_PATH on your own machine. Nothing is uploaded
anywhere. To back it up, copy that file — the way you'd copy a photo — and keep the copy
somewhere safe and encrypted. To move to a new computer, install the server there and copy the file
across.
Start a conversation with the server connected and try these in order. The first run seeds a demo clinic with three doctors, four patients and a FAQ.
"Who are the doctors at the clinic and when do they work?"
→ list_doctors. Dr. Mehta (general practice, split morning/evening shifts), Dr. Iyer
(pediatrics, 20-minute slots), Dr. Sheikh (dermatology, 45-minute consultations).
"What's open with Dr. Mehta next Monday evening?"
→ check_availability. Returns real bookable slots in clinic-local time, past ones excluded.
"Book Mr. Shah with Dr. Mehta tomorrow evening for a diabetes follow-up."
→ find_patient, then book_appointment. Read back the confirmation. A reminder is queued for
24 hours before. Try booking the same slot again — you will get the nearest alternatives instead
of a bare failure.
"He's been tired in the afternoons for about two months, takes metformin 500mg twice daily,
allergic to penicillin."
→ submit_intake. Then ask "what will the doctor see?" → get_intake returns a
one-paragraph brief a doctor can read in ten seconds.
"Actually, can we move that to Wednesday morning? And what are your consultation fees?"
→ reschedule_appointment (old → new summary, reminder re-queued) and answer_faq.
Then try the guardrails:
"He's had a bad headache for three days — should he take something for it?" → the doctor redirect, not advice.
"Cancel his appointment." → a preview and a request to confirm. Nothing is cancelled until you say yes.
"What's the wifi password?"
→ match: none, so the agent offers to check with the front desk rather than inventing an answer.
# Run straight from the repository, no clone needed
uvx --from git+https://github.com/prashant-cr/Clinic-front-desk-MCP-server clinic-frontdesk-mcp
# Or clone and install
git clone https://github.com/prashant-cr/Clinic-front-desk-MCP-server
cd Clinic-front-desk-MCP-server
uv pip install -e .
# With the optional SMS adapter
uv pip install -e '.[twilio]'Requirements: Python 3.11 or newer, and nothing else — SQLite is created and seeded on first run.
Not yet on PyPI. Until the first release, use the git forms above. After publication,
uvx clinic-frontdesk-mcpbecomes the one-line install and the configargsshorten to["clinic-frontdesk-mcp"]. If you cloned the repo, pointcommandat/path/to/repo/.venv/bin/clinic-frontdesk-mcpwith"args": [].
Any MCP-compatible client works — the server speaks stdio and nothing else. Claude Code:
claude mcp add clinic-frontdesk \
--env CLINIC_DB_PATH=/absolute/path/to/clinic.db \
--env CLINIC_TIMEZONE=Asia/Kolkata \
-- uvx --from git+https://github.com/prashant-cr/Clinic-front-desk-MCP-server clinic-frontdesk-mcpFor other clients, give them the same command, arguments and environment variables as the JSON above in whatever format they use.
Tool | What it does |
| Doctors with specialty and usual weekly hours |
| Open slots for a doctor; falls back to the next three openings when a day is full |
| Partial search by name or phone. Returns all matches — never guesses |
| Filter by patient, doctor, date and status |
| Intake form plus the ten-second |
| Best FAQ match with a confidence level, or |
| Per-doctor view of a day: appointments, merged free blocks, pending intakes, unsent reminders |
Every write appends a PII-redacted row to audit_log.
Tool | What it does |
| Creates a patient, or returns the existing record for that phone number |
| Validates and books, queues a 24-hour reminder, returns a read-back confirmation |
| Moves the appointment and re-queues the reminder |
| Requires |
| Stores intake and regenerates the doctor brief. Re-submitting replaces it |
| Sends one reminder immediately |
| Sends every reminder that has come due. Run periodically |
| Lets staff grow the FAQ through the agent |
All settings are environment variables, all with defaults — the server starts with no configuration at all.
Variable | Default | Purpose |
|
| SQLite file. Created and seeded on first run |
|
| Name used in confirmations and reminders |
|
| IANA zone. All tool input and output is in this zone |
|
| Load demo data when the database is first created |
|
| Log verbosity (stderr) |
| – | All three needed for SMS; otherwise reminders print to stderr |
| – | |
| – |
Seeding happens only when the database file is created. Restarting never duplicates demo rows
or resurrects deleted records. Set CLINIC_SEED=false to start empty for a real clinic.
caller ──▶ Claude Desktop / Claude Code / your agent ← the brain: language, judgement
│ MCP over stdio
▼
┌───────────────────────┐
│ server.py │ 14 tools, thin — no logic lives here
├───────────────────────┤
│ scheduling patients │ slot maths, conflicts, intake
│ faq notifs │ matching, clinical routing, reminders
├───────────────────────┤
│ db.py → clinic.db │ SQLite on your disk. UTC in, local out
└───────────────────────┘ every write mirrored to a redacted audit_log
│
└─▶ stderr (redacted logs) · Twilio SMS (optional, off by default)Nothing leaves the machine unless you configure the Twilio adapter yourself.
Every timestamp is stored in UTC and every tool input and output is in clinic-local time.
scheduling.py is the single conversion boundary — nothing above it touches UTC, nothing below it
touches local time.
Slots come from a weekly template in schedules, overridden per-day by schedule_exceptions
(a holiday closes the day; a time override replaces that day's windows). Slots that would run past
the end of a window are dropped, so a 10:00–12:30 window in 20-minute slots ends at 12:20.
DST is handled explicitly: a slot at a wall-clock time that does not exist (spring forward) is skipped, and an ambiguous hour (fall back) is offered once. Slot durations are real elapsed time, so consecutive slots never overlap across a transition.
Two layers, because SQLite has no exclusion constraint:
A partial unique index on (doctor_id, starts_at_utc) for active appointments.
An overlap check and the insert inside one BEGIN IMMEDIATE transaction, which closes the
check-then-insert race the index alone cannot cover for partial overlaps.
Routing medical questions to the doctor is a rule, not a similarity score. Scoring failed it in
both directions during development: "I have a bad headache for 3 days" fell below the escalation
floor purely for being a long sentence, while the generic keyword take pulled "do you take
insurance?" toward the medical entry.
A curated CLINICAL_TERMS vocabulary in faq.py now short-circuits to the redirect entry, which
the seed marks with the reserved keyword medical. You can reword that answer for your clinic —
just keep the keyword on it.
uv venv
uv pip install -e '.[dev]'
uv run pytest -q # 248 tests
uv run ruff check . && uv run ruff format --check .
uv run mypy src/Inspect the server with the MCP Inspector, pointing it at the installed entry point — the same command Claude Desktop runs:
# Interactive browser UI
npx @modelcontextprotocol/inspector .venv/bin/clinic-frontdesk-mcp
# Or drive it from the terminal
npx @modelcontextprotocol/inspector --cli .venv/bin/clinic-frontdesk-mcp --method tools/list
npx @modelcontextprotocol/inspector --cli .venv/bin/clinic-frontdesk-mcp \
--method tools/call --tool-name list_doctorsNote that mcp dev src/clinic_frontdesk_mcp/server.py:mcp does not work here: it loads the
file as a standalone module, which breaks the package-relative imports. Point the Inspector at the
entry point instead, as above — it also exercises the real console script rather than a
special-cased import.
src/clinic_frontdesk_mcp/
├── server.py # MCP tool definitions only — thin, delegates everything
├── scheduling.py # slot maths, conflict detection, the local<->UTC boundary
├── patients.py # patient records and intake
├── faq.py # FAQ matching and clinical-question detection
├── notifications.py # reminder delivery adapters
├── db.py # schema, migrations, seeding, redacted audit log
├── models.py # domain dataclasses
└── config.py # environment configurationBusiness logic lives in the domain modules and is testable without MCP. If a tool body in
server.py grows past a screen, the logic belongs somewhere else.
No web UI, no authentication or multi-tenancy, no real WhatsApp integration (the adapter interface is there), no EMR/FHIR integration, no payments, no multi-clinic support.
MIT — see LICENSE.
Add an entry to the clinic FAQ so future callers get a consistent answer.
Use this when staff tell you something the FAQ does not cover yet, or after
answer_faq returns match: "none" and a human supplies the answer.
Only for clinic logistics — timings, fees, policies, facilities. Never add medical guidance; clinical questions must keep routing to the doctor.
Args: question: The question as a caller would ask it. answer: The exact wording to read back. Write it as speech, not a document. keywords: Comma-separated search terms, including likely synonyms and misspellings, e.g. "parking,park,vehicle,two wheeler,car".
Example: add_faq(question="Do you have parking?", answer="Yes, free two-wheeler parking is available at the rear.", keywords="parking,park,vehicle,two wheeler,bike,car")
| Name | Required | Description | Default |
|---|---|---|---|
| answer | Yes | ||
| keywords | No | ||
| question | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full transparency burden. It discloses the action (add), the acceptable content scope, and the required answer format ('Write it as speech, not a document'). However, it does not mention what happens if the question already exists or whether the tool updates or appends, leaving a minor behavioral gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and front-loaded: it states the purpose in the first sentence, then usage triggers, scope constraints, parameter guidance, and a practical example. Every sentence earns its place with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and the presence of an output schema (so return values need no explanation), the description covers all essentials: purpose, when to use, parameter semantics, and content constraints. It is complete enough for an agent to correctly select and invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides only titles and no descriptions (0% coverage), so the description fully compensates. The Args section defines each parameter precisely: 'question' as a caller would ask it, 'answer' as exact speech-ready wording, and 'keywords' as comma-separated synonyms/misspellings with a concrete example. This adds substantial meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Add an entry to the clinic FAQ' – a specific verb and resource. It clearly distinguishes itself from the sibling answer_faq by being the write counterpart, and further clarifies the scope with 'Only for clinic logistics... Never add medical guidance.' This makes the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states when to use the tool: 'when staff tell you something the FAQ does not cover yet, or after answer_faq returns match: "none"'. It also gives a clear exclusion: 'Never add medical guidance; clinical questions must keep routing to the doctor.' Both positive and negative guidance are provided, which is exemplary.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Answer a question about the clinic: timings, fees, location, payment, insurance.
Use this for anything informational rather than transactional.
Read the result carefully before replying:
match: "high" — read the answer back as-is.
match: "medium" — offer it, but check you understood ("did you mean...?").
match: "none" — say you will check with the front desk. Do NOT improvise an
answer about fees, insurance or policy; a confident wrong answer about money
is worse than a short delay.
Medical questions return the clinic's standard redirect to the doctor. Read it as written and offer to book an appointment — never supplement it with clinical information of your own.
Example: answer_faq(question="what are your timings on saturday?")
| Name | Required | Description | Default |
|---|---|---|---|
| question | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It thoroughly explains the match result handling, the medical question redirect, and the caution about never supplementing clinical information. It even explains the reasoning ('a confident wrong answer about money is worse than a short delay'). This is deeply transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: a one-sentence summary, a usage directive, bullet-point instructions for match handling, a special case for medical questions, and an example. Every sentence adds value; the bullet format improves scanability without unnecessary padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (one parameter) and has an output schema, so the description doesn't need to explain return types. It covers the essential runtime behaviors (match handling, medical redirect, no improvisation), includes an example, and provides sufficient detail for an agent to invoke and interpret the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has only a 'question' string with no description (0% coverage). The description compensates by using the parameter in the example (answer_faq(question="...")) and by framing the entire tool as 'Answer a question about the clinic.' However, it doesn't explicitly define the parameter's constraints or format beyond the example, so it's not a perfect 5.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool answers questions about the clinic (timings, fees, location, payment, insurance). It distinguishes itself from sibling tools by explicitly contrasting informational vs. transactional uses, making it easy for an agent to select it.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance is provided: 'Use this for anything informational rather than transactional.' It also details how to handle different match levels (high, medium, none) and instructs against improvising answers for fees/insurance/policy. This gives clear when-to-use and when-not-to-use context, including the alternative of checking with the front desk.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Book an appointment and queue a reminder for 24 hours beforehand.
Call check_availability first and offer the caller a real opening. Read the
returned confirmation back to them.
The slot must be free, inside the doctor's working hours, and aligned to their appointment grid. If it is taken, the error names the nearest alternatives — offer those rather than repeating the request.
Args: patient_id: From find_patient or register_patient. doctor_id: From list_doctors. starts_at: Clinic-local ISO 8601, e.g. '2027-01-25T18:00'. Not UTC. reason: Why they are coming, in the caller's own words.
Example: book_appointment(patient_id=1, doctor_id=1, starts_at="2027-01-25T18:00", reason="diabetes follow-up")
| Name | Required | Description | Default |
|---|---|---|---|
| reason | Yes | ||
| doctor_id | Yes | ||
| starts_at | Yes | ||
| patient_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully carries the burden. It discloses the reminder side effect, validation constraints (free slot, working hours, grid alignment), and error behavior (returns nearest alternatives). It also mentions the confirmation return value, giving a complete behavioral picture.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: one-sentence summary, procedural guidance, validation constraints, parameter list, and example. Each section adds value and is front-loaded with the main purpose. No extraneous content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no annotations, the description covers prerequisites, validation rules, side effects, parameter meanings, and an example. It is comprehensive enough for an agent to invoke the tool correctly, especially since an output schema exists to handle return values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It does so thoroughly: each parameter has a source or format explanation (e.g., patient_id from find_patient, starts_at in clinic-local ISO 8601, not UTC). An example further clarifies usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Book'), resource ('appointment'), and an additional side effect ('queue a reminder for 24 hours beforehand'). It clearly distinguishes from siblings like reschedule_appointment and cancel_appointment by focusing on new bookings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance: 'Call check_availability first', and explains how to handle taken slots by offering nearest alternatives. This tells the agent exactly when and how to use the tool, including a prerequisite step and error recovery.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Cancel an appointment. Requires explicit confirmation.
Call it first WITHOUT confirm to get a preview of exactly what would be
cancelled. Read that back to the caller, and only call again with confirm=True
once they have said yes.
This two-step gate exists because cancelling is not reversible from here — a mistakenly cancelled slot may be taken by someone else within minutes.
Confirming releases the slot and cancels the pending reminder.
Args: appointment_id: From get_appointments. confirm: Must be True to actually cancel.
Example: cancel_appointment(appointment_id=12) # preview cancel_appointment(appointment_id=12, confirm=True) # actually cancel
| Name | Required | Description | Default |
|---|---|---|---|
| confirm | No | ||
| appointment_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully discloses that cancellation is irreversible, that the confirm parameter gates the actual cancellation, and that confirming releases the slot and cancels the pending reminder. The preview behavior is clearly explained, giving the agent a complete safety picture.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized with a clear lead sentence, a rationale for the two-step gate, and a concrete example. Every line adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that the output schema exists and the operation is relatively simple, the description covers the complete workflow, including prerequisites (appointment_id source), safety protocol, and consequences. Nothing critical is missing for an agent to use this correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, yet the description fully explains both parameters: appointment_id comes from get_appointments, and confirm must be True to actually cancel. The example showing preview vs real call makes the semantics unambiguous.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource ('Cancel an appointment') and immediately distinguishes this from sibling tools like reschedule_appointment by emphasizing it is a cancellation, not a rescheduling. The two-step confirmation gate is also part of its identity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit step-by-step instructions (preview first, confirm only after explicit user consent), which is clear guidance. It does not name alternative tools such as reschedule_appointment for when the user wants a different time instead of cancellation, so it falls slightly short of the highest bar.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find open appointment slots for a doctor, in clinic-local time.
Always call this before book_appointment so you offer times that are genuinely free. Slots already in the past are excluded automatically.
If the requested date has nothing open, next_available holds the next three
openings after it, so you can offer an alternative instead of a dead end.
Args:
doctor_id: From list_doctors.
date: Clinic-local 'YYYY-MM-DD'. Defaults to today.
days_ahead: How many days to scan, starting at date. Use 7 for "sometime
next week".
Example: check_availability(doctor_id=1, date="2027-01-25", days_ahead=3)
| Name | Required | Description | Default |
|---|---|---|---|
| date | No | ||
| doctor_id | Yes | ||
| days_ahead | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully discloses key behaviors: past slots are excluded automatically, return includes 'next_available' for alternatives, and time zone is clinic-local. This goes beyond the schema and gives the agent confidence in side-effect-free checking.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Every sentence earns its place—summary, usage rule, behavior note, parameter details, and example. It is compact yet comprehensive, with clear front-loading of purpose and no redundant phrasing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers standard usage (pre-booking), edge cases (no open slots), and all parameters with defaults. It even explains the 'next_available' field, supplementing the output schema. The tool is fully contextualized within the booking workflow.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The Args section compensates for the 0% schema description coverage by explaining each parameter: doctor_id sourced from list_doctors, date format and default, and how days_ahead scans. The example call ties it together, making parameter usage unambiguous.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Find open appointment slots for a doctor, in clinic-local time.' It clearly differentiates from sibling tools by explicitly positioning itself as a pre-booking check ('Always call this before book_appointment').
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit when-to-use guidance ('Always call this before book_appointment') and practical context for the 'days_ahead' parameter ('Use 7 for "sometime next week"'). It also explains the fallback behavior via 'next_available' for handling empty availability.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Give a doctor-by-doctor overview of one day: appointments, free time, and gaps.
Use this for "what does today look like?" or when staff want to know where
attention is needed. pending_intakes and unsent_reminders are the actionable
parts — they are the work the front desk still has to do.
Args: date: Clinic-local 'YYYY-MM-DD'. Defaults to today.
Example: daily_summary(date="2027-01-25")
| Name | Required | Description | Default |
|---|---|---|---|
| date | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses the nature of the output (overview, gaps, actionable intakes/reminders) and the default date behavior. It does not mention side effects or explicit read-only status, but the tool is clearly a read-only summary, so the description is reasonably transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact, front-loaded with purpose, then usage, then parameter details, and an example. Every sentence adds value without redundancy, and formatting improves readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The complexity is low (one optional parameter) and an output schema exists, so the description covers purpose, usage, parameter semantics, and example. It is complete for an agent to select and invoke the tool correctly without further info.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has one parameter with zero description coverage, so the description entirely compensates. It provides format ('YYYY-MM-DD'), context ('clinic-local'), and default behavior ('Defaults to today') along with a concrete example. This is sufficient for a single optional parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Give') and resource ('doctor-by-doctor overview of one day') with clear scope (appointments, free time, gaps). This clearly differentiates it from sibling tools like get_appointments or check_availability, which serve related but distinct purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly provides when to use ('what does today look like?', 'where attention is needed') and highlights actionable elements. However, it does not explicitly mention when not to use it or name alternative tools, so it falls just short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search patients by partial name or phone number.
Use this before booking for someone who says they have been here before.
When count is greater than 1, ask the caller which record is theirs — do not
guess. Two people share a surname far more often than you would like, and
booking the wrong record is worse than asking one extra question. A count of
0 means they are new: use register_patient.
Example: find_patient(query="Shah") or find_patient(query="9876543210")
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses that the tool returns a count, interprets count values (0 = new, >1 = multiple records), and warns against guessing. This is valuable behavioral context beyond the raw schema. It does not discuss edge cases like empty query or authentication, but the core ambiguity resolution behavior is clearly explained.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: purpose in the first sentence, usage context next, count interpretation and real-world rationale, then examples. Every sentence adds value; there is no fluff. The structure flows logically from what to usage to how to interpret results.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one param, output schema exists), the description is complete. It covers when to use, how to interpret the count, and what to do in ambiguous cases. The output schema handles return-value specifics, so the description need not repeat that. The only minor gap is lack of explicit error handling, but that is not critical for this straightforward search tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema only defines 'query' as a string with no description. The description compensates by explaining that query accepts partial name or phone number, and provides concrete examples. It does not specify case sensitivity or phone number formatting, but for a single parameter with 0% schema coverage, this is a solid addition.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with a specific verb and resource: 'Search patients by partial name or phone number.' This clearly differentiates it from siblings like register_patient, book_appointment, or list_doctors. It also states the direct use case: 'Use this before booking for someone who says they have been here before.'
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit when-to-use guidance: use before booking for existing patients. It also provides an alternative: 'A `count` of 0 means they are new: use register_patient.' It further instructs on handling multiple matches: 'When `count` is greater than 1, ask the caller which record is theirs.' This is exactly the when/when-not/alternatives guidance required.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List appointments, filtered by any combination of patient, doctor, date and status.
Use this to answer "when is my appointment?", to find the appointment_id needed by reschedule_appointment or cancel_appointment, or to review a doctor's day.
With no filters it returns everything, so pass at least one for a busy clinic.
Args: patient_id: From find_patient. doctor_id: From list_doctors. date: Clinic-local 'YYYY-MM-DD'. status: One of booked, rescheduled, cancelled, completed, no_show.
Example: get_appointments(patient_id=1, status="booked")
| Name | Required | Description | Default |
|---|---|---|---|
| date | No | ||
| status | No | ||
| doctor_id | No | ||
| patient_id | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full behavioral disclosure. It states that unfiltered calls return everything and advises passing at least one filter for a busy clinic, defines the date as clinic-local, and enumerates valid statuses. It doesn't mention pagination or result limits, but the output schema covers return structure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Every sentence earns its place: main action, use cases, filter warning, parameter explanations, and an example. It is front-loaded and free of fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists and the tool is a query/list operation, the description covers action, filter combinations, usage contexts, parameter provenance, and the unfiltered-query caveat. This is sufficient for an agent to select and invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 0% of parameter semantics; the description compensates fully. It explains each parameter: patient_id from find_patient, doctor_id from list_doctors, date format 'YYYY-MM-DD', and status enum. A concrete example ties the parameters together.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description opens with 'List appointments, filtered by any combination of patient, doctor, date and status', which is a specific verb+resource+scope. It distinguishes itself from siblings by explicitly stating it finds the appointment_id needed by reschedule_appointment and cancel_appointment, and supports reviewing a doctor's day.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear contexts: answering 'when is my appointment?', finding appointment_id for reschedule/cancel, reviewing a doctor's day. It also warns that with no filters it returns everything. However, it does not explicitly exclude alternatives like check_availability for open slots, so it lacks explicit when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve the intake form for an appointment, plus a ready-to-read doctor brief.
doctor_brief is a single paragraph written to be absorbed in about ten
seconds — read that to the doctor rather than reciting every field.
Returns submitted: false when no intake has been taken yet, which is your cue
to collect one with submit_intake.
Example: get_intake(appointment_id=12)
| Name | Required | Description | Default |
|---|---|---|---|
| appointment_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It usefully reveals the meaning of `submitted: false` and characterizes `doctor_brief` as a concise, ready-to-read paragraph. This goes beyond a bare 'retrieve' statement, though it does not cover error cases or explicit read-only confirmation. It adds meaningful behavioral context without contradicting any annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized and front-loaded. The first sentence states the core purpose, followed by two explanatory paragraphs that add valuable detail, and ends with a practical example. Every sentence earns its place, with no fluff. The structure flows logically from purpose to behavioral nuance to usage.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, output schema present), the description is nearly complete. It explains key return behavior (`submitted: false`), the nature of `doctor_brief`, and names the associated `submit_intake` tool. It does not cover error handling or potential exceptions, but for a straightforward retrieval tool with an output schema, it covers the essential context sufficiently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It provides a concrete example (`get_intake(appointment_id=12)`) and mentions 'for an appointment', which helps clarify that `appointment_id` refers to the appointment's identifier. However, it does not elaborate on the parameter's constraints or format. The example is a minimal compensation; the description adds some meaning but not extensive semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a specific verb+resource: 'Retrieve the intake form for an appointment, plus a ready-to-read doctor brief.' This clearly states what the tool does and distinguishes it from siblings like submit_intake, which is the write counterpart. The added detail about the doctor brief further clarifies the tool's unique output.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear when-to-use guidance: it explains the `submitted: false` return value is 'your cue to collect one with submit_intake', explicitly naming an alternative and the condition for using it. It also instructs on how to use the output ('read that to the doctor'), giving practical usage context beyond mere retrieval.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the clinic's doctors with their specialty and usual weekly hours.
Use this first when the caller does not name a doctor, or asks who they can see
for a particular problem. The returned doctor_id is what check_availability
and book_appointment expect.
The availability_summary is the regular weekly pattern, not live openings —
call check_availability for actual free slots.
Example: list_doctors()
| Name | Required | Description | Default |
|---|---|---|---|
| include_inactive | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It usefully discloses that availability_summary is a regular weekly pattern, not live openings, and that doctor_id is used by downstream tools. It does not clarify the effect of include_inactive, but the main behavioral caveat is covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is four short, purposeful sentences plus an example. It is front-loaded with the main action, then provides usage guidance, a caveat, and a usage example with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with an output schema, the description is sufficiently complete. It covers what the tool does, when to use it, the key limitation of availability_summary, and how the result connects to other tools. The missing include_inactive detail is a minor parameter-level issue and does not undermine overall completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter, include_inactive, is not mentioned in the description, and the schema provides no description either. The example call with no arguments implies it is optional, but the active/inactive distinction is left entirely to inference from the parameter name and default. This is a notable gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: list the clinic's doctors with specialty and usual weekly hours. It also differentiates the tool by noting that the returned doctor_id is what check_availability and book_appointment expect, positioning it distinctly among siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says to use this tool first when the caller does not name a doctor, and directs the agent to call check_availability for actual free slots instead of relying on the availability_summary. This provides clear when-to-use and when-not-to-use guidance with an alternative named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send every reminder that has come due. Run this periodically.
Picks up all pending reminders whose send time has passed and whose appointment is still active. Reminders for cancelled appointments are dropped rather than sent. A failed delivery stays pending for the next run.
Args: limit: Maximum to process in one pass.
Example: process_due_reminders()
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It explains that cancelled appointments' reminders are dropped, failed deliveries stay pending for the next run, and the limit controls batch size. This is meaningful behavioral context beyond the bare operation name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact, front-loaded with the core purpose, and uses a clear structure with a short paragraph, Args section, and example. Every sentence contributes useful information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has one optional parameter, an output schema, and moderate complexity. The description covers the core processing behavior, edge cases (cancelled/failed), and usage cadence. It omits return-value details, but the presence of an output schema reduces the need to describe them in prose.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema only lists 'limit' as an integer with a default of 50, but the description defines it as 'Maximum to process in one pass.' This adds clear semantic meaning that the schema alone does not convey.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Send every reminder that has come due' and then elaborates that it picks up all pending reminders with passed send times and active appointments. This clearly identifies the tool as a batch reminder-processing action, distinguishing it from the single-purpose sibling tool 'send_reminder'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'Run this periodically' gives explicit guidance on when to use the tool, and the details about cancelled and failed reminders explain the operational context. However, it does not explicitly mention when to prefer send_reminder over this tool or list exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Register a new patient, or return the existing record for that phone number.
Call find_patient first. If the phone number is already on file this returns
that patient with created: false instead of creating a duplicate — so a repeat
caller keeps one history rather than several.
Confirm the spelling of the name and the phone number with the caller before calling this.
Args: name: Full name as the patient gives it. phone: Any common format; '+91 98765-43210' and '+919876543210' are treated as the same number. dob: 'YYYY-MM-DD', optional but useful for distinguishing same-name patients. notes: Anything the front desk should remember. Not clinical notes.
Example: register_patient(name="Rajesh Shah", phone="+919876543210", dob="1968-04-12")
| Name | Required | Description | Default |
|---|---|---|---|
| dob | No | ||
| name | Yes | ||
| notes | No | ||
| phone | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully carries behavioral disclosure. It reveals idempotent behavior (returns existing record with `created: false`), phone number normalization, the non-clinical nature of notes, and the role of dob in distinguishing same-name patients. This gives the agent critical expectations beyond what a schema could provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear purpose, workflow guidance, Args section, and example. No filler sentences; each part adds value, and the length is appropriate for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the tool's purpose, workflow (call find_patient first), idempotency, parameter details, and an example. Given the output schema exists, it doesn't need to explain return values beyond the `created: false` flag, which it does. It is complete for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description is the only source of parameter meaning. It explains each arg: name, phone (including format normalization), dob (optional, useful for distinguishing patients), and notes (non-clinical). The example call further clarifies usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Register a new patient, or return the existing record for that phone number.' It specifies the resource (patient) and the action (register/return), and distinguishes itself from the sibling find_patient by noting it returns existing records rather than just looking them up.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance is provided: 'Call find_patient first' and 'Confirm the spelling of the name and the phone number with the caller before calling this.' This tells the agent when and how to use the tool, including prerequisites and a step to avoid duplicate registrations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Move an existing appointment to a new time and update its reminder.
Use check_availability first to confirm the new time is free. The old slot is released and the 24-hour reminder is re-queued for the new time.
Cancelled appointments cannot be rescheduled — book a new one instead.
Args: appointment_id: From get_appointments. new_starts_at: Clinic-local ISO 8601, e.g. '2027-01-27T09:30'.
Example: reschedule_appointment(appointment_id=12, new_starts_at="2027-01-27T09:30")
| Name | Required | Description | Default |
|---|---|---|---|
| new_starts_at | Yes | ||
| appointment_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses side effects: 'The old slot is released and the 24-hour reminder is re-queued for the new time.' It also states a behavioral rule: cancelled appointments cannot be rescheduled. This goes beyond basic functionality and helps the agent anticipate consequences.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is tightly structured: a one-line purpose, then usage guidance, behavioral notes, parameter documentation, and an example. Every sentence earns its place with no redundancy. It is both concise and information-dense.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter tool with an output schema, the description covers all necessary context: preconditions (check availability), side effects, exclusions, and argument formats. It is sufficient for an agent to invoke the tool correctly without ambiguity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema description coverage, the description fully explains both parameters: appointment_id is sourced from get_appointments, and new_starts_at requires clinic-local ISO 8601 with a concrete example. This adds meaning beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with 'Move an existing appointment to a new time and update its reminder,' which clearly identifies the action and resource. It distinguishes itself from sibling tools like cancel_appointment and book_appointment by focusing on rescheduling and reminder updates.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance is given: 'Use check_availability first to confirm the new time is free' provides a direct prerequisite and references an alternative tool. 'Cancelled appointments cannot be rescheduled — book a new one instead' gives a clear when-not-to-use condition and suggests an alternative. This is exemplary.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send this appointment's reminder now, ahead of its scheduled time.
Use when a caller asks to be reminded again, or to confirm details in writing. Normal reminders go out on their own via process_due_reminders — you do not need this for routine bookings.
Delivery goes through the configured channel: printed to the server log by default, or SMS when Twilio is configured.
Example: send_reminder(appointment_id=12)
| Name | Required | Description | Default |
|---|---|---|---|
| appointment_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Given no annotations, the description carries the transparency burden. It discloses delivery channel: 'printed to the server log by default, or SMS when Twilio is configured.' Also notes manual trigger ahead of scheduled time. It does not mention error behavior, but that's acceptable for a simple send action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Five short sentences plus example; each sentence adds value. Front-loaded with primary action; no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool is simple (one param, no annotations). Description covers purpose, when-to-use, delivery behavior, and examples. Output schema exists, so return format isn't needed. Adequate for an agent to select and invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema provides only appointment_id as an integer with no description. The description compensates with an example call: 'send_reminder(appointment_id=12)' and contextualizes it as 'this appointment's reminder.' However, it doesn't elaborate on semantics beyond the parameter name, so it's helpful but not exhaustive.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Send this appointment's reminder now, ahead of its scheduled time.' It clearly distinguishes from the automatic process_due_reminders by stating routine reminders go out on their own.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: 'Use when a caller asks to be reminded again, or to confirm details in writing.' Also provides exclusion: 'Normal reminders go out on their own via process_due_reminders — you do not need this for routine bookings.' Names the alternative tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Record pre-visit intake for an appointment and regenerate the doctor brief.
Collect this after booking. Ask about medications and allergies explicitly — both change what the doctor can safely prescribe, and "no answer" is not the same as "none".
Record what the patient says in their own words. Do not interpret symptoms, suggest what they might indicate, or add clinical terminology of your own.
Re-submitting replaces the previous intake, so it is safe to call again if the caller corrects themselves.
Args: appointment_id: From get_appointments or book_appointment. chief_complaint: The main reason for the visit, in one line. symptoms: What they are experiencing, as described. duration: How long it has been going on, e.g. "about 3 weeks". current_medications: What they take now, including dosage if offered. allergies: Known allergies, or "none reported" if they say none. notes: Anything else logistically relevant.
Example: submit_intake(appointment_id=12, chief_complaint="blood sugar review", symptoms="tired in the afternoons", duration="2 months", current_medications="metformin 500mg twice daily", allergies="penicillin")
| Name | Required | Description | Default |
|---|---|---|---|
| notes | No | ||
| duration | No | ||
| symptoms | No | ||
| allergies | No | ||
| appointment_id | Yes | ||
| chief_complaint | Yes | ||
| current_medications | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals that the tool replaces prior intake data and regenerates a doctor brief as a side effect. It also instructs to record patient statements verbatim and avoid interpretation, adding important non-obvious constraints. However, it doesn't discuss error handling or response format, though the output schema may cover that.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: it opens with a clear purpose, then gives usage timing, behavioral guidance, parameter definitions, and an example. Every sentence contributes necessary information, and the format makes it easy to scan. The length is justified by the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 7 parameters, a side effect (regenerating the brief), and no annotations, the description covers all critical aspects: when to use it, what to collect, how to record data, resubmission behavior, and an example. Since an output schema exists, it need not explain return values. The description is fully self-contained for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 0%, so the description must compensate. It does so exceptionally well by providing a dedicated Args section that explains each parameter's meaning and source, e.g., 'appointment_id: From get_appointments or book_appointment,' and gives an illustrative example. This adds significant value beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Record pre-visit intake for an appointment and regenerate the doctor brief.' The verb 'record' and resource 'pre-visit intake for an appointment' are specific, and the additional detail 'regenerate the doctor brief' distinguishes this from sibling tools like get_intake.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description says 'Collect this after booking,' providing clear timing guidance. It also notes that 'Re-submitting replaces the previous intake, so it is safe to call again,' implying a usage pattern. While it doesn't explicitly name alternative tools for exclusions, the context is sufficient for an agent to decide when to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.1.0add_faqanswer_faqbook_appointmentcancel_appointmentcheck_availabilitydaily_summaryfind_patientget_appointmentsget_intakelist_doctorsprocess_due_remindersregister_patientreschedule_appointmentsend_remindersubmit_intakeScored across 15 tools
Each tool targets a distinct entity and action: doctors, availability, patients, appointments (book/reschedule/cancel/list), intake, reminders, FAQ, and daily summary. There is no overlap in purpose, and descriptions clarify any potential boundary cases.
All tool names use snake_case and follow a mostly verb_noun pattern (list_doctors, book_appointment, cancel_appointment). The only minor deviation is daily_summary, but it is still a clear noun phrase and consistent in style.
15 tools is at the upper edge of the recommended range but each tool earns its place by covering a distinct front-desk operation. The set is well-scoped for a clinic front desk, neither too thin nor bloated.
The tool set covers the core lifecycle: patients (find/register), appointments (book/reschedule/cancel/list), intake (get/submit), reminders (send/process), and FAQ (answer/add). Minor gaps exist such as no patient update or explicit completion/no-show status change, but these are not critical for the front-desk purpose.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Hosted MCP server for Cliniko — patients, appointments, availability, and invoices for AI agents.
An AI concierge that turns static forms into adaptive AI conversations. From any MCP client.
Hosted MCP server exposing US hospital procedure cost data to AI assistants
Hosted MCP server for the Healthie EHR & telehealth API: patients, appointments, charting, tasks.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/prashant-cr/Clinic-front-desk-MCP-server'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
