See your clinic's free slots, doctors, rooms, service prices and how busy each day is.
Scored across 19 tools
Each tool is written with explicit 'Not for…' boundaries, so an agent can distinguish booking vs. rescheduling vs. cancelling, or patient records vs. appointment lists. The only soft spot is a cluster of clinic-level read tools (get_clinic, list_clinics, get_clinic_schedule_summary, get_clinic_availability, show_clinic_overview) whose payloads partially overlap, though the descriptions do enough to separate them.
All 19 names follow a snake_case verb_noun pattern with a small, predictable verb set (get_, list_, create_, update_, find_, book_, cancel_, reschedule_, set_). 'show_clinic_overview' is the only verb outside the core set, but it is still clear and consistent in style.
19 tools is on the heavy side but each maps to a real sub-domain of a clinic back office: patients, appointments, providers, rooms, procedures, inventory, availability and subscription. Nothing looks redundant enough to remove outright, though the count sits just below the 'feels heavy' threshold.
Appointment and patient lifecycles are mostly covered (book/cancel/reschedule/list, create/find/update), but there is no get-patient-by-id, no appointment detail/update for providers or procedures, and no delete for patients or inventory items. Supporting catalogs (providers, rooms, procedures, clinics) are read-only with creation and editing entirely absent.
Use this when someone asks to book a patient in at their clinic. Returns the new appointment with its time, providers and number of procedures; it takes the clinic's usual length, room and reminders, so the clinic's reminder messages go to the patient. Not for finding free slots.
| Name | Required | Description | Default |
|---|---|---|---|
| clinicId | No | Id of the clinic, from list_clinics. Leave it out when the user has one clinic. | |
| patientId | Yes | Id of the patient, from find_patient or create_patient. | |
| requestId | Yes | A unique id you choose for this booking, such as a UUID. Calling again with the same requestId returns the first booking instead of booking twice. | |
| startTime | Yes | Start as an ISO 8601 time with the clinic's UTC offset, such as 2026-11-20T10:00:00+01:00. | |
| providerIds | No | Ids of the doctors, nurses or assistants who take it, from list_providers. Leave it out when the clinic has one provider or the user is the provider. | |
| procedureIds | No | Ids of the procedures booked, from list_procedures. | |
| durationMinutes | No | Length in minutes. Leave it out for the clinic's usual length. |
| Name | Required | Description |
|---|---|---|
| status | Yes | |
| appointment | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, destructiveHint=true, idempotentHint=true and openWorldHint=true, so the safety profile is covered. The description contributes real extra context: the tool fills in the clinic's usual length, room and reminders, and reminder messages are sent to the patient. It never addresses conflict/double-booking behavior or what happens when a requested slot is unavailable, which matters most for a write tool flagged destructive.
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?
Three compact sentences with the use condition front-loaded, then the return value, then the exclusion — a sensible order with little waste. The clause 'so the clinic's reminder messages go to the patient' is slightly awkward but conveys a genuine side effect rather than 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?
With an output schema present and annotations covering safety and idempotency, the description is close to sufficient: it covers purpose, trigger, defaults and the reminder side effect. The remaining gap is failure semantics — nothing says how slot conflicts or validation errors surface, which is notable for a booking tool marked destructive.
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 100%, so every parameter (including the requestId idempotency contract and omission defaults for clinicId, providerIds and durationMinutes) is already documented. The description only echoes the defaulting behavior at a high level ('takes the clinic's usual length, room and reminders') without adding format or constraint detail. Baseline 3 applies where the schema carries the load.
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?
States a specific verb and resource ('book a patient in at their clinic') and immediately names what is returned ('the new appointment with its time, providers and number of procedures'), so the agent knows the outcome shape as well as the action. The closing exclusion ('Not for finding free slots') separates it from the availability/slot 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?
Gives an explicit trigger ('when someone asks to book a patient in') and an explicit exclusion ('Not for finding free slots'), which routes slot discovery elsewhere in the sibling set. It does not name the alternative tool or cover adjacent cases such as rescheduling or cancelling, so it falls short of full routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when someone asks to cancel a patient's appointment. Returns the canceled appointment and whether the clinic's cancellation message goes to the patient; the appointment is kept with status CANCELED, never deleted. Not for moving it to another time.
| Name | Required | Description | Default |
|---|---|---|---|
| appointmentId | Yes | Id of the appointment, from list_appointments. | |
| expectedLastEditTime | Yes | The lastEditTime from list_appointments. An appointment changed since then is refused. |
| Name | Required | Description |
|---|---|---|
| status | Yes | |
| appointment | Yes | |
| clientNotification | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations: it discloses soft-delete semantics ('kept with status CANCELED, never deleted'), which clarifies what destructiveHint=true actually means here, and pre-announces the return payload including the patient-notification flag. This is exactly the context an agent needs before invoking a mutation.
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?
Three short clauses, front-loaded with the action and followed by the non-deletion guarantee and the exclusion. No filler, nothing repeated from the title.
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?
An output schema exists, so return values need not be detailed, and the mutation semantics plus the concurrency guard are covered between description and schema. The only gap is that no prerequisites (e.g., permissions or subscription state, given the presence of get_subscription_status) are mentioned for this mutation.
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 100%, and both parameters (appointmentId, expectedLastEditTime) are already documented in-schema including the optimistic-concurrency refusal behavior. The description adds no meaning beyond that, so the baseline of 3 applies.
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?
States a specific verb+resource (cancel a patient's appointment) and immediately delimits it against reschedule_appointment with 'Not for moving it to another time.' An agent can distinguish it from the similar-sounding sibling without reading any schema.
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?
Gives an explicit trigger ('when someone asks to cancel') and an explicit exclusion ('Not for moving it to another time'), which routes the moving-to-another-time case to reschedule_appointment. Both when-to-use and when-not are present, with the alternative identified functionally.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when someone asks to add a new patient to their clinic. Returns the patient's id, name, clinic and language; the phone and email given are stored but never returned. Not for a patient already on file.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | The patient's full name. | |
| No | Email address. | ||
| phone | No | Mobile number, with the country code when known. | |
| clinicId | No | Id of the clinic, from list_clinics. Leave it out when the user has one clinic. | |
| language | No | Language for their messages, as a code such as en or it. Leave it out for the clinic language. | |
| requestId | Yes | A unique id you choose for this patient, such as a UUID. Calling again with the same requestId returns the first patient instead of adding a second. |
| Name | Required | Description |
|---|---|---|
| status | Yes | |
| patient | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations cover readOnly=false, destructive=true, idempotent=true and openWorld=false. The description goes beyond them by disclosing the return shape (id, name, clinic, language) and a non-obvious side effect: phone and email are stored but never returned. It does not restate the idempotency contract, though the requestId schema already explains it.
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?
Three short sentences, each doing distinct work: trigger, return/persistence contract, and exclusion. The usage trigger is front-loaded with zero 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?
With an output schema and 100% parameter coverage, most burden is already carried elsewhere; the description still adds the persistence caveat and the scope exclusion. Minor gaps remain, such as permission requirements or what happens on a duplicate name, but nothing that blocks a correct call.
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 100%, so all six parameters are already documented, including the requestId dedupe behavior and clinicId/language defaults. The description adds one useful fact about phone/email persist-but-not-returned, but supplies no field-level detail beyond the schema, matching the baseline for fully documented schemas.
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 ('add a new patient to their clinic') and adds a boundary ('Not for a patient already on file') that separates it from update_patient and find_patient. It stops short of naming those siblings explicitly, so the agent must infer which tool handles existing patients.
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?
Both a when-to-use trigger ('when someone asks to add a new patient') and a when-not condition ('Not for a patient already on file') are stated. No alternative tool is named, so routing for the existing-patient case is left to inference from the sibling list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when someone names a patient to book, move, cancel or update. Returns up to 5 patients whose name contains every word given, with their ids and clinic; the last two phone digits appear only to tell namesakes apart. Not for browsing, counting or reading patient records.
| Name | Required | Description | Default |
|---|---|---|---|
| search | Yes | The patient's name as the user gave it, or part of it. Every word must appear in the stored name, in any order, ignoring case and accents. | |
| clinicId | No | Only patients of this clinic; every clinic of the account when absent |
| Name | Required | Description |
|---|---|---|
| count | Yes | |
| patients | Yes | The patients whose name matches, with the ids the other tools take. Contact details, dates of birth, notes and clinical records are never returned. |
| tooManyMatches | Yes | More than 5 patients match: none are returned; ask the user for more of the name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the safe-read profile (readOnly, idempotent, non-destructive, closed world), and the description still adds meaningful behavior beyond them: a hard cap of 5 results, AND-matching over name words in any order, and a privacy rule that phone digits are only partially exposed to disambiguate namesakes. That result-truncation and masking detail is not derivable from the annotations or schema.
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?
Three tight sentences: trigger condition first, result contract second, exclusions last. Every clause carries information and none of it repeats the title or annotations.
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?
With an output schema present, the description need not detail return values, yet it still sketches the shape (ids, clinic, partial phone) enough to set expectations about truncation and masking. For a 2-parameter lookup tool this is fully sufficient to call 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 100%, and the schema's own description already covers the 'every word must appear, any order, ignoring case and accents' semantics, which the description largely restates. The description adds the truncation behavior implicit in the search (only 5 hits) but says nothing about clinicId, so it neither extends nor detracts from 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 names a specific verb (find) and resource (patient) and immediately narrows the scope: 'Returns up to 5 patients whose name contains every word given, with their ids and clinic.' The closing clause 'Not for browsing, counting or reading patient records' separates it from the list_* and record-reading 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?
It gives an explicit triggering condition ('when someone names a patient to book, move, cancel or update') and explicit exclusions ('Not for browsing, counting or reading patient records'). What it lacks is naming the concrete alternatives to reach for instead, e.g. list_appointments or show_clinic_overview, so the when-not is stated as a category rather than a route.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when someone asks about one medical practice's setup, such as its currency, language or timezone. Returns the practice's name, currency, default language, timezone and last edit time. Not for free consultation times.
| Name | Required | Description | Default |
|---|---|---|---|
| clinicId | Yes | Practice id: 24 lowercase hexadecimal characters |
| Name | Required | Description |
|---|---|---|
| clinic | Yes | Administrative practice metadata only; opening hours, staff, patient and appointment data are not included. Null when not found. |
| status | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false and destructiveHint=false, so the safety profile is fully covered externally. The description adds the single-practice scope and enumerates return fields, but says nothing about failure modes, permissions, or behavior when the practice id is unknown.
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?
Three compact sentences, trigger condition front-loaded, no filler. The return-field enumeration is somewhat redundant given an output schema exists, so it is efficient but not perfectly trimmed.
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 single-parameter read tool with rich annotations and a declared output schema, the description covers when to use it and what it is not for. The remaining gap is un-named alternatives for the excluded case.
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 100% for the sole clinicId parameter, including its 24-hex-character pattern, so the schema carries full burden. The description adds no format or lookup guidance beyond what the schema states.
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?
States a specific verb and resource ('Get medical practice details') and scopes it to a single practice's setup, which separates it from list_clinics. The exclusion 'Not for free consultation times' gestures at get_clinic_availability but never names it, so sibling differentiation is partial.
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?
Gives a concrete trigger ('when someone asks about one medical practice's setup, such as its currency, language or timezone') plus one explicit negative case. It stops short of naming the alternative tool an agent should use instead.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when someone asks when their doctor's practice has free appointment or consultation times. Returns each open online-booking slot's start and end, grouped by day, for the next days with openings: up to 7 days and 100 slots (no patient or doctor details). Not for booking a visit.
| Name | Required | Description | Default |
|---|---|---|---|
| clinicId | Yes | Practice id: 24 lowercase hexadecimal characters |
| Name | Required | Description |
|---|---|---|
| days | Yes | One row per day with open online-booking slots, in date order, holding at most 100 slots in total. Slot times only; patients, doctors, services and clinical data are never included. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the read-only/idempotent/non-destructive safety profile, so the description rightly focuses on behavior it alone can convey: day-grouped slots, the 7-day/100-slot caps, and the privacy guarantee that no patient or doctor details are returned. The only minor gap is that the caps are stated as fixed without noting what happens if openings exceed them.
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?
Three sentences, no filler, with the trigger condition front-loaded, the return shape and limits in the middle, and the exclusion last. Every sentence earns its place.
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?
An output schema exists so return-value internals need not be spelled out, yet the description still summarizes the shape (start/end per slot, grouped by day) and the caps. Combined with annotations, nothing needed to call the tool correctly is missing.
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?
There is only one parameter (clinicId) and schema description coverage is 100%, so the schema already fully documents its format and pattern. The description adds no new meaning about the parameter, so the baseline of 3 applies.
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?
States a specific verb and resource (find/return free appointment or consultation slots for a practice) and scopes it clearly as availability lookup. An agent can distinguish it from booking flows and the list_* siblings without opening the schema.
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 opening clause gives an explicit trigger ('when someone asks when their doctor's practice has free appointment times') and the closing clause excludes the alternative action ('Not for booking a visit'). Both when-to-use and when-not are covered.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when someone asks how busy their medical practice is or how many patient visits are booked each day. Returns appointment counts per UTC day for one practice, whatever their status, for the next 7 days by default and at most 31 days; counting stops at 100. Not for counting cancellations or seeing which patients are booked.
| Name | Required | Description | Default |
|---|---|---|---|
| endTime | No | End of the range as an ISO 8601 date-time, after startTime and at most 31 days later; defaults to 7 days after the start | |
| clinicId | Yes | Practice id: 24 lowercase hexadecimal characters | |
| startTime | No | Start of the range as an ISO 8601 date-time; defaults to now |
| Name | Required | Description |
|---|---|---|
| days | Yes | One row per UTC day that has appointments, canceled ones included. Aggregate counts only: appointment identifiers and times, patient information, services, diagnoses and notes are never returned. |
| range | Yes | |
| appointmentCount | Yes | |
| appointmentCountIsLowerBound | Yes | True when more than 100 appointments fall in the range |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description still adds real behavioral detail the annotations cannot: UTC-day bucketing, status-agnostic counting, a 7-day default with a 31-day maximum, and a silent truncation cap at 100 counts. It does not, however, explain what happens when the cap is hit (partial day? error? omitted days).
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?
Three sentences, each doing distinct work: usage trigger first, then output/behavior bounds, then exclusions. No filler and the most decision-relevant information (when to reach for it) is front-loaded.
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?
An output schema exists, so return shape need not be described. For a three-parameter read with full schema coverage, the description supplies everything an agent needs to select and call it correctly: the trigger, the date-range bounds and the sibling-excluding boundaries.
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 100%, so startTime, endTime and clinicId are all documented in the schema itself; the baseline is 3. The description restates the default window and the 31-day ceiling, which is consistent with the schema but adds no syntax or format information beyond it.
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?
States a specific verb and resource ('Returns appointment counts per UTC day for one practice') and fixes the scope to a single practice and a bounded date window. It is readily distinguishable from siblings like list_calendar_events or show_clinic_overview, which return events or aggregate summaries rather than per-day counts.
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?
Opens with an explicit trigger ('Use this when someone asks how busy their medical practice is or how many patient visits are booked each day') and closes with an explicit exclusion ('Not for counting cancellations or seeing which patients are booked'). Both the when and the when-not are handed to the agent with no inference required.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when someone asks which DoctoFam plan a practice is on, whether it is active, or how many appointments, patients, rooms or users it allows. Returns the plan name, status, billing frequency and plan caps, or the default Free plan when none is active. Not for invoices or amounts billed.
| Name | Required | Description | Default |
|---|---|---|---|
| clinicId | Yes | Practice id: 24 lowercase hexadecimal characters |
| Name | Required | Description |
|---|---|---|
| subscription | Yes | The practice's active or past-due plan, or the default Free plan (isDefaultFreePlan) when neither exists. Seats are rooms; caps are limits, not usage. Billing identifiers, payment-provider data, amounts, currencies, patient records and clinical data are never returned. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so safety is covered. The description adds genuine behavioral context by stating the fallback: it returns the default Free plan when none is active, which an agent would not infer from annotations or schema.
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?
Three sentences, no waste, and the usage trigger is front-loaded before the return description and the exclusion. Every clause earns its place.
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?
An output schema exists so return values need not be enumerated, and the annotations cover the safety/idempotency profile. The description supplies the remaining missing piece (the Free-plan fallback), making the definition complete for a single-parameter read 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?
There is one parameter with 100% schema description coverage, including a hex pattern, so the schema fully documents it. The description adds no extra meaning about clinicId beyond what the schema provides, which is the expected baseline-3 case when structured data already carries the load.
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?
Specific verb+resource: retrieves a practice's DoctoFam plan, its status, billing frequency and plan caps. It also explicitly carves out sibling territory ('Not for invoices or amounts billed'), so the agent can distinguish it from billing-related tools without opening any schema.
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?
Strong when-to-use triggers are given ('when someone asks which plan a practice is on, whether it is active, or how many appointments, patients, rooms or users it allows'), plus one exclusion for invoices. It does not name a specific alternative tool for the billing case, so it stops short of full routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when someone asks when a patient is booked, or what is booked at the clinic on a given day. Returns appointment ids with patient, clinic and provider ids, times, status, edit time and how many procedures each has, latest first, up to 100. Not for counting how busy days are, nor for procedure names, notes or any medical detail.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of appointments to return (default 20, maximum 100) | |
| endTime | No | Only appointments ending before this ISO 8601 time | |
| clinicId | No | Only appointments at this clinic, by an id from list_clinics; every clinic when absent | |
| patientId | No | Only appointments of this patient, by an id from find_patient | |
| startTime | No | Only appointments starting at or after this ISO 8601 time. Without a patientId, give a startTime and endTime at most one day apart |
| Name | Required | Description |
|---|---|---|
| count | Yes | |
| hasMore | Yes | |
| appointments | Yes | Appointments, latest start first. Procedure names, notes, reminders, patient names and contact details are never returned. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the read-only annotations, it discloses returned fields, ordering ('latest first'), a cap of 100, and that procedure counts are included but medical detail is not. It does not discuss permissions or pagination, but those are minor for this read-only list operation.
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?
Three sentences are front-loaded with the use case, then return shape, then exclusions. There is no redundant wording and every sentence adds useful selection or behavioral information.
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 read-only list tool with rich annotations, full schema coverage, and an output schema, the description covers when to call it, what comes back, ordering, limits, and what it must not be used for. Nothing essential for correct invocation is missing.
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 100%, so the input schema already documents limit, time range, clinicId, and patientId thoroughly. The description confirms the two main query modes but adds little parameter-level meaning beyond what the schema provides.
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 and resource: listing appointments by patient or by clinic/day. It also clearly separates this tool from related needs such as counting busy days and retrieving procedure names or medical detail.
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 gives explicit when-to-use guidance ('when someone asks when a patient is booked, or what is booked at the clinic on a given day') and clear exclusions. It does not name the specific alternative tools, so an agent still has to infer which sibling handles counting or procedure details.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when someone asks when their medical practice is closed, or when a doctor or room is blocked for holidays, sick leave, courses, meetings or maintenance. Returns each block or extra opening with start, end, all-day flag, scope and type (no titles or notes). Not for patient appointments.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Blocks per page, from 1 to 100; defaults to 20 | |
| cursor | No | The nextCursor of the previous page with the same filters; absent for the first page | |
| endTime | No | Only blocks ending before this ISO 8601 date-time | |
| clinicId | No | Only this practice (24 lowercase hexadecimal characters); every practice when absent | |
| startTime | No | Only blocks starting at or after this ISO 8601 date-time |
| Name | Required | Description |
|---|---|---|
| nextCursor | Yes | Cursor for the next page; null on the last page |
| calendarEvents | Yes | Non-appointment calendar blocks, earliest first. Event identifiers, staff and room references, titles, notes and patient links are never returned. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint/idempotentHint/destructiveHint, so the safety profile is covered. The description adds useful substance beyond that: what fields come back (start, end, all-day flag, scope, type) and the notable absence of titles/notes. It does not mention pagination mechanics, though the cursor param implies it.
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?
Three sentences, front-loaded with the usage trigger, followed by return shape and the exclusion. No filler or restatement of the tool name.
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?
With 0 required params, a 100%-documented schema, rich annotations and an output schema, the remaining burden on the description is trigger and scope — both supplied. An agent has everything needed to select and call it.
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 100%, so all five parameters (limit, cursor, startTime, endTime, clinicId) are already documented in the schema. The description adds no parameter-level syntax or defaults beyond that, so the baseline 3 applies.
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?
States a specific verb and resource (list calendar closures/holidays/blocked time) and names the sibling domain it is not for (patient appointments). The title and description together let an agent distinguish it from appointment-related siblings without opening the schema.
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?
Gives an explicit trigger ('Use this when someone asks when their medical practice is closed, or when a doctor or room is blocked...') and an explicit exclusion ('Not for patient appointments'). Both when-to-use and when-not are stated outright.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when someone asks which medical practices or doctor's offices they run in DoctoFam, or a practice's id is needed. Returns each practice's id, name, currency, default language and timezone, 20 per page by default. Not for finding a patient or a visit.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Practices per page, from 1 to 100; defaults to 20 | |
| cursor | No | The nextCursor of the previous page of this listing; absent for the first page |
| Name | Required | Description |
|---|---|---|
| clinics | Yes | Medical practices in the signed-in organization, administrative metadata only. Patient, appointment and clinical records are never returned. |
| nextCursor | Yes | Cursor for the next page; null on the last page |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful context beyond that: the returned field set (id, name, currency, default language, timezone) and the default page size of 20.
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?
Three tightly packed sentences: trigger first, then return contents, then exclusion. No filler and nothing that could be cut without losing information.
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?
A read-only listing tool with a full output schema, complete parameter documentation, and an explicit sibling exclusion. Everything an agent needs to select and correctly invoke it is present.
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 100%, so both limit and cursor are already documented with ranges and meaning. The description only restates the 20-per-page default, adding nothing about cursor semantics or pagination chaining. Baseline 3 applies.
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?
States a specific verb (list) and resource (medical practices/doctor's offices) and enumerates the returned fields. It also explicitly carves out what it is not for (finding a patient or a visit), so an agent can separate it from get_clinic and the other siblings without opening schemas.
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?
Gives an explicit trigger ('Use this when someone asks which medical practices...or a practice's id is needed') and an explicit exclusion ('Not for finding a patient or a visit'). When-to-use and when-not-to-use are both present.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when someone asks how much of a supply is left in the clinic's stock or what is running low. Returns up to 100 stock items with unit, quantity, minimum and a low-stock flag. Not for procedure prices.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of items (default 50, maximum 100). | |
| search | No | Only items whose name contains these words. | |
| clinicId | No | Id of the clinic, from list_clinics. Leave it out when the user has one clinic. | |
| lowStockOnly | No | Only items at or below their minimum quantity. |
| Name | Required | Description |
|---|---|---|
| count | Yes | |
| items | Yes | |
| hasMore | Yes | |
| clinicId | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds value beyond them by disclosing the result surface — up to 100 items carrying unit, quantity, minimum and a low-stock flag — which tells the agent this is a bounded, non-paginated list rather than a writable or streaming endpoint.
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?
Three short sentences, front-loaded with the triggering intent before the return shape and the exclusion. No filler, no restatement of the title, and each sentence carries distinct information.
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?
An output schema exists, so the description need not define return values, and all four optional parameters are fully documented in the schema. Combined with annotations covering safety, an agent has what it needs; only the sibling routing for the excluded case is left implicit.
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 100%, with limit, search, clinicId and lowStockOnly each documented including defaults, bounds and the list_clinics provenance for clinicId. The description only indirectly gestures at lowStockOnly via "what is running low" and adds no syntax or format meaning beyond the schema, so the baseline 3 applies.
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?
States a specific resource (clinic stock items) and the exact question it answers — "how much of a supply is left" or "what is running low". The closing exclusion "Not for procedure prices" separates it from list_procedures, so an agent can pick between them without opening either schema.
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?
Gives an explicit natural-language trigger plus one exclusion, which is more than most definitions offer. It stops short of naming the sibling to use for the excluded case (list_procedures) and never mentions set_inventory_quantity as the write counterpart, so the routing is implied rather than spelled out.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when someone asks what their medical practice charges for a consultation, check-up, vaccination or other service, or which procedure to book. Returns catalog service ids and names with price and last edit time, alphabetically, 50 per page by default. Not for a patient's medical history or the care they received.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Services per page, from 1 to 100; defaults to 50 | |
| cursor | No | The nextCursor of the previous page with the same filters; absent for the first page | |
| clinicId | No | Only this practice (24 lowercase hexadecimal characters); every practice when absent |
| Name | Required | Description |
|---|---|---|
| nextCursor | Yes | Cursor for the next page; null on the last page |
| procedures | Yes | Service catalog entries in name order, with the ids a booking takes. Patient-linked treatments, diagnoses and prescriptions are never returned. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds useful behavior beyond that: results are alphabetical, paginated at 50 per page by default, and each row carries price and last edit time. Auth/clinic-scoping behavior is left to the schema's clinicId field rather than explained here.
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?
Three compact sentences: trigger first, return shape and pagination second, exclusion last. Every sentence carries information and nothing is repeated from the title or schema.
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?
With three optional parameters, full schema coverage, and an output schema that documents the response, the description covers everything an agent needs: when to pick it, what comes back, ordering, page size, and what it is not for.
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 100%, so limit, cursor, and clinicId are already fully documented, which sets the baseline at 3. The description only reinforces the default page size and adds the alphabetical ordering, which isn't captured in the schema but is minor.
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 and resource ('Look up ... what their medical practice charges for a consultation, check-up, vaccination or other service') and returns catalog service ids/names with price and last edit time. It is clearly distinguishable from siblings like list_inventory_items, list_providers, or get_clinic, which cover other catalog types.
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 gives an explicit trigger ('Use this when someone asks what their ... charges ... or which procedure to book') and an explicit exclusion ('Not for a patient's medical history or the care they received'). It stops short of naming the alternative sibling tool to use for history, but the when/when-not framing is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when someone asks which doctors, nurses or assistants patients can book at their practice, or who takes an appointment. Returns up to 100 staff ids and display names for one practice (no contact details or roles). Not for staff holidays or sick days.
| Name | Required | Description | Default |
|---|---|---|---|
| clinicId | Yes | Practice id: 24 lowercase hexadecimal characters |
| Name | Required | Description |
|---|---|---|
| providers | Yes | Ids and display names of staff with a doctor, nurse or assistant role, the ones the public booking page offers. Contact details, role records and clinical data are never returned. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely useful behavioral context: results are capped at 100 and deliberately omit contact details and roles, which prevents an agent from promising fields that never come back. It does not discuss ordering or how to page past the 100 cap.
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?
Two sentences, both front-loaded: the trigger condition comes first, then the return contract, then the exclusion. Nothing is redundant with the title or the schema, and there is no 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?
For a single-parameter read tool with full annotation coverage and an output schema, the description supplies the trigger, the scope, the cap and the omissions. Nothing an agent needs in order to call it or set caller expectations is missing.
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 100% and the single clinicId parameter is fully documented (24-char lowercase hex), so the schema carries the syntax burden. The description still adds meaning by stressing 'for one practice', clarifying that the id scopes the call to exactly one clinic rather than aggregating across a group.
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?
States a specific verb (list) and resource (providers = doctors, nurses, assistants who take bookings), scoped to one practice, and explicitly bounds the payload (ids and display names, no contact details or roles). An agent can distinguish it from sibling tools such as list_rooms or get_clinic_availability without opening a schema.
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?
Gives a concrete triggering condition ('when someone asks which doctors, nurses or assistants patients can book at their practice, or who takes an appointment') and a negative scope ('Not for staff holidays or sick days'). It stops short of naming the alternative tool an agent should use for holiday/absence questions, so it is not a full when/when-not/alternatives statement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when someone asks which consultation or exam rooms their medical practice has. Returns room names with last edit time for one practice, alphabetically, 50 per page by default. Not for room schedules or which patient uses a room.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Rooms per page, from 1 to 100; defaults to 50 | |
| cursor | No | The nextCursor of the previous page with the same filters; absent for the first page | |
| clinicId | Yes | Practice id: 24 lowercase hexadecimal characters |
| Name | Required | Description |
|---|---|---|
| rooms | Yes | Rooms in name order. Record identifiers, appointment links, patient information and clinical content are never returned. |
| nextCursor | Yes | Cursor for the next page; null on the last page |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, idempotent, non-destructive behavior, so the description's added value is the result shape and ordering: alphabetical results, 50-per-page default paging, and last-edit-time metadata. It does not discuss auth requirements or what happens on an invalid/stale cursor, which is a minor remaining 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?
Three tight sentences: use-case first, result/paging behavior second, exclusions last. No filler and the routing constraint is front-loaded.
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?
With an output schema present, return values needn't be detailed, and the description still summarizes them. For a simple read-only list tool with full schema coverage and safety annotations, nothing an agent needs to call it correctly is missing.
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 100%, so limit, cursor, and clinicId are already documented in the schema. The description only restates the page-size default ('50 per page by default'), adding nothing beyond the schema's own parameter descriptions. Baseline 3 applies.
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 names a specific verb and resource (list consultation/exam rooms for a practice) and further specifies the payload ('room names with last edit time'). The closing exclusion clause separates it from schedule-oriented siblings such as get_clinic_schedule_summary.
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 states the triggering condition explicitly ('Use this when someone asks which consultation or exam rooms their medical practice has') and gives negative guidance ('Not for room schedules or which patient uses a room'), routing the agent away from the schedule and patient-assignment tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when someone asks to move a patient's appointment to another day or time. Returns the appointment with its new and previous start; it keeps the patient, providers, procedures and length unless a new length is given, and its reminders move with it. Not for cancelling.
| Name | Required | Description | Default |
|---|---|---|---|
| startTime | Yes | New start as an ISO 8601 time with the clinic's UTC offset, such as 2026-11-20T10:00:00+01:00. | |
| appointmentId | Yes | Id of the appointment, from list_appointments. | |
| durationMinutes | No | New length in minutes. Leave it out to keep the current length. | |
| expectedLastEditTime | Yes | The lastEditTime from list_appointments. An appointment changed since then is refused. |
| Name | Required | Description |
|---|---|---|
| status | Yes | |
| appointment | Yes | |
| previousStartTime | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, idempotentHint=true and openWorldHint=true; the description goes beyond them by stating which fields are preserved (patient, providers, procedures, length), that reminders migrate with the appointment, and that the result includes both new and previous start. It does not discuss the concurrency-refusal behaviour or permission requirements, which the schema partly covers via expectedLastEditTime.
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 usage trigger is front-loaded in the first clause, and the remaining clauses pack preservation rules, reminder behaviour and return shape into one sentence with no filler or repetition.
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 destructive mutation tool this covers what an agent needs: when to call it, what is preserved, what happens to reminders, and what comes back. Since an output schema exists, the return description is a bonus rather than a requirement; only failure modes and permissions are left implicit.
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 100%, so every parameter is already documented in the schema, including the ISO 8601/UTC-offset format and the expectedLastEditTime refusal rule. The description reinforces one parameter's semantics (length is kept unless a new length is given) but adds no syntax or constraint detail beyond that baseline.
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?
"Move a patient's appointment to another day or time" gives a specific verb (move) plus resource (patient appointment) with the scope of change stated. It distinguishes itself from cancellation ("Not for cancelling") but does not explicitly contrast with book_appointment, the other sibling that creates rather than moves an 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?
The opening clause gives an explicit trigger (someone asks to move an appointment to another day or time) and closes with a clear exclusion ("Not for cancelling"), which routes the agent away from cancel_appointment. No guidance is given on the create-vs-move boundary against book_appointment, so it stops short of full alternative routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when someone asks to correct or update how much of a stock item the clinic has. Returns the item with its previous and new quantity; the number given replaces the stored one. Not for adding a new stock item.
| Name | Required | Description | Default |
|---|---|---|---|
| quantity | Yes | The quantity now in stock, in the item unit. It replaces the stored quantity; work out the total first when the user gives a change. | |
| inventoryItemId | Yes | Id of the stock item, from list_inventory_items. | |
| expectedLastEditTime | Yes | The lastEditTime from list_inventory_items. An item changed since then is refused. |
| Name | Required | Description |
|---|---|---|
| item | Yes | |
| status | Yes | |
| previousQuantity | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is carried by structured data. The description adds useful semantics that the write is a replacement rather than an increment and that previous/new quantity are returned, but it does not cover the concurrency-refusal behavior (only the schema's expectedLastEditTime field does).
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?
Three short sentences, front-loaded with the trigger and the replacement semantics, with the exclusion at the end. No filler or repetition beyond the useful restatement that the value replaces rather than adjusts the stored quantity.
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?
Output schema exists, so return values need not be explained, yet the description still names them helpfully. For a three-parameter mutation with full annotation and schema coverage, this is close to complete; the only minor gap is not warning that a stale expectedLastEditTime causes rejection, which the schema covers on its own.
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 100%, so all three parameters are fully documented in the schema, including the 'work out the total first' derivation and the stale-edit refusal. The description only echoes the replacement semantics for quantity, adding little beyond structured fields; baseline 3 is appropriate.
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?
States a specific verb (correct/update) and resource (quantity of a stock item in the clinic), and adds a scope exclusion ('Not for adding a new stock item'). It is unambiguous, though it does not name a real sibling tool (there is no create-inventory sibling in the list), so the differentiation is by concept rather than by tool name.
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?
Gives an explicit trigger ('Use this when someone asks to correct or update how much of a stock item the clinic has') and one explicit exclusion (creating a new stock item). It does not say what to do instead when the item is unknown or missing, which would be needed for a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when someone wants a quick overview or dashboard of one medical practice. Returns an overview card with the practice's details, appointment counts for the next 7 days, staff and room counts, open online-booking slots, up to 12 service prices and the current plan (no patient or clinical data). Not for a single patient or visit.
| Name | Required | Description | Default |
|---|---|---|---|
| clinicId | Yes | Practice id: 24 lowercase hexadecimal characters |
| Name | Required | Description |
|---|---|---|
| clinic | Yes | Administrative practice metadata; null when the practice was not found. The overview never includes individual appointment records, patient information, diagnoses, treatment details, notes or other clinical data. |
| roomCount | Yes | |
| procedures | Yes | |
| scheduleDays | Yes | |
| subscription | Yes | |
| providerCount | Yes | |
| scheduleRange | Yes | |
| procedureCount | Yes | |
| appointmentCount | Yes | |
| availabilityDays | Yes | |
| availableDayCount | Yes | |
| availableSlotCount | Yes | |
| roomCountIsLowerBound | Yes | |
| providerCountIsLowerBound | Yes | |
| procedureCountIsLowerBound | Yes | |
| appointmentCountIsLowerBound | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered. The description adds real behavioral context beyond that: the exact scope of the returned card (7-day window, cap of 12 service prices) and the important caveat 'no patient or clinical data', which bounds what an agent may claim from the result.
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?
Two tight sentences, front-loaded with the trigger and then the return scope; no filler. The enumerated return list is somewhat long given an output schema exists, keeping it just short of maximal conciseness.
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 single-parameter read tool with full schema coverage, annotations and an output schema, the description supplies everything an agent needs: when to reach for it, what the card contains, how far ahead it looks, and the explicit exclusion of patient/clinical data. No material gap remains.
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 100% and the single clinicId parameter is fully documented with its hex pattern, so the schema carries the burden. The description adds only the implicit notion of a single practice; it contributes no extra syntax or format meaning beyond the schema. Baseline 3.
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 names a specific verb and resource ('quick overview or dashboard of one medical practice') and enumerates the payload: practice details, 7-day appointment counts, staff/room counts, booking slots, up to 12 service prices, and plan. It also carves out its boundary ('Not for a single patient or visit'), so an agent can distinguish it from get_clinic_schedule_summary and list_clinics without opening schemas.
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?
'Use this when someone wants a quick overview or dashboard of one medical practice' gives an explicit trigger, and 'Not for a single patient or visit' supplies an exclusion. It stops short of naming which sibling to use for those adjacent needs, so it is strong but not fully prescriptive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when someone asks to change a patient's name, phone, email or language. Returns the patient's id, name, clinic and which fields changed; contact details are never returned. Not for medical history or any other patient detail.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | New full name. | |
| No | New email address. | ||
| phone | No | New mobile number, with the country code when known. | |
| language | No | New language for their messages, as a code such as en or it. | |
| patientId | Yes | Id of the patient, from find_patient. | |
| expectedLastEditTime | Yes | The lastEditTime from find_patient. A patient changed since then is refused. |
| Name | Required | Description |
|---|---|---|
| status | Yes | |
| patient | Yes | |
| changedFields | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, destructiveHint=true and idempotentHint=true, so the safety profile is carried structurally. The description adds genuinely new behavioral context: the response shape (id, name, clinic, changed fields) and the privacy rule that contact details are never returned. It omits what happens to fields not supplied, which is the remaining 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?
Three short sentences with zero filler: trigger first, return behavior second, exclusion third. Every sentence carries distinct information.
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?
An output schema exists, so the description need not explain return values, yet it usefully does. The one missing piece for a mutation tool is whether a call with no optional contact fields is valid and whether omitted fields are preserved, which matters given the destructiveHint.
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 100% and each parameter carries its own description, including the optimistic-concurrency meaning of expectedLastEditTime. The description adds nothing about parameters beyond echoing which fields are editable, so the baseline 3 applies.
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?
Names a specific verb ('change') plus the exact resource fields it touches (name, phone, email, language) and explicitly excludes medical history and other patient details. An agent can distinguish this from create_patient and find_patient without opening any schema.
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 opening clause gives an explicit trigger condition ('when someone asks to change a patient's name, phone, email or language') and the closing sentence states a negative boundary. It stops short of naming that create_patient is the alternative for new records, but the trigger and exclusion are clear.
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.
book_appointmentcancel_appointmentcreate_patientfind_patientlist_appointmentslist_inventory_itemslist_procedures3 fields changedOutput schema / properties / procedures / descriptionPrevious value: -"Service catalog entries in name order. Patient-linked treatments, diagnoses, prescriptions and record identifiers are never returned."New value: +"Service catalog entries in name order, with the ids a booking takes. Patient-linked treatments, diagnoses and prescriptions are never returned."Output schema / properties / procedures / items / properties / idAdded value: +{
+ "anyOf": [
+ {
+ "pattern": "^[0-9a-f]{24}$",
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "Id to book with, as book_appointment takes it"
+}Output schema / properties / procedures / items / requiredPrevious value: -[
- "name",
- "price",
- "duration",
- "lastEditTime"
-]New value: +[
+ "id",
+ "name",
+ "price",
+ "duration",
+ "lastEditTime"
+]list_providers3 fields changedOutput schema / properties / providers / descriptionPrevious value: -"Display names of staff with a doctor, nurse or assistant role. Staff identifiers, contact details, role records and clinical data are never returned."New value: +"Ids and display names of staff with a doctor, nurse or assistant role, the ones the public booking page offers. Contact details, role records and clinical data are never returned."Output schema / properties / providers / items / properties / idAdded value: +{
+ "description": "Id to book with, as book_appointment takes it",
+ "pattern": "^[0-9a-f]{24}$",
+ "type": "string"
+}Output schema / properties / providers / items / requiredPrevious value: -[
- "displayName"
-]New value: +[
+ "id",
+ "displayName"
+]reschedule_appointmentset_inventory_quantityupdate_patientget_clinic2 fields changedInput schema / properties / clinicId / descriptionPrevious value: -"Clinic id (24-character hex)"New value: +"Practice id: 24 lowercase hexadecimal characters"Output schema / properties / clinic / descriptionAdded value: +"Administrative practice metadata only; opening hours, staff, patient and appointment data are not included. Null when not found."get_clinic_availability2 fields changedInput schema / properties / clinicId / descriptionPrevious value: -"Clinic id (24-character hex)"New value: +"Practice id: 24 lowercase hexadecimal characters"Output schema / properties / days / descriptionAdded value: +"One row per day with open online-booking slots, in date order, holding at most 100 slots in total. Slot times only; patients, doctors, services and clinical data are never included."get_clinic_schedule_summary5 fields changedInput schema / properties / clinicId / descriptionPrevious value: -"Clinic id (24-character hex)"New value: +"Practice id: 24 lowercase hexadecimal characters"Input schema / properties / endTime / descriptionPrevious value: -"Range end as an ISO 8601 value; defaults to seven days later"New value: +"End of the range as an ISO 8601 date-time, after startTime and at most 31 days later; defaults to 7 days after the start"Input schema / properties / startTime / descriptionPrevious value: -"Range start as an ISO 8601 value; defaults to now"New value: +"Start of the range as an ISO 8601 date-time; defaults to now"Output schema / properties / appointmentCountIsLowerBound / descriptionAdded value: +"True when more than 100 appointments fall in the range"Output schema / properties / days / descriptionAdded value: +"One row per UTC day that has appointments, canceled ones included. Aggregate counts only: appointment identifiers and times, patient information, services, diagnoses and notes are never returned."get_subscription_status2 fields changedInput schema / properties / clinicId / descriptionPrevious value: -"Clinic id (24-character hex)"New value: +"Practice id: 24 lowercase hexadecimal characters"Output schema / properties / subscription / descriptionAdded value: +"The practice's active or past-due plan, or the default Free plan (isDefaultFreePlan) when neither exists. Seats are rooms; caps are limits, not usage. Billing identifiers, payment-provider data, amounts, currencies, patient records and clinical data are never returned."list_calendar_events10 fields changedInput schema / properties / clinicId / descriptionPrevious value: -"Filter by clinic id"New value: +"Only this practice (24 lowercase hexadecimal characters); every practice when absent"Input schema / properties / cursor / descriptionPrevious value: -"Opaque cursor from a prior result"New value: +"The nextCursor of the previous page with the same filters; absent for the first page"Input schema / properties / endTime / descriptionPrevious value: -"Only events ending before this ISO 8601 time"New value: +"Only blocks ending before this ISO 8601 date-time"Input schema / properties / limit / descriptionAdded value: +"Blocks per page, from 1 to 100; defaults to 20"Input schema / properties / startTime / descriptionPrevious value: -"Only events starting at or after this ISO 8601 time"New value: +"Only blocks starting at or after this ISO 8601 date-time"Output schema / properties / calendarEvents / descriptionAdded value: +"Non-appointment calendar blocks, earliest first. Event identifiers, staff and room references, titles, notes and patient links are never returned."Output schema / properties / calendarEvents / items / properties / effect / descriptionAdded value: +"BLOCK removes bookable time; OPEN adds hours on a normally closed time"Output schema / properties / calendarEvents / items / properties / scope / descriptionAdded value: +"CLINIC: the whole practice; PROVIDER: one or more staff; SEAT: one room"Output schema / properties / calendarEvents / items / properties / type / descriptionAdded value: +"Label such as COURSE, MEETING, VACATION, SICK, HOLIDAY, MAINTENANCE or OTHER"Output schema / properties / nextCursor / descriptionAdded value: +"Cursor for the next page; null on the last page"list_clinics4 fields changedInput schema / properties / cursor / descriptionPrevious value: -"Opaque cursor from a prior result"New value: +"The nextCursor of the previous page of this listing; absent for the first page"Input schema / properties / limit / descriptionAdded value: +"Practices per page, from 1 to 100; defaults to 20"Output schema / properties / clinics / descriptionAdded value: +"Medical practices in the signed-in organization, administrative metadata only. Patient, appointment and clinical records are never returned."Output schema / properties / nextCursor / descriptionAdded value: +"Cursor for the next page; null on the last page"list_procedures7 fields changedInput schema / properties / clinicId / descriptionPrevious value: -"Filter by clinic id"New value: +"Only this practice (24 lowercase hexadecimal characters); every practice when absent"Input schema / properties / cursor / descriptionPrevious value: -"Opaque cursor from a prior result"New value: +"The nextCursor of the previous page with the same filters; absent for the first page"Input schema / properties / limit / descriptionAdded value: +"Services per page, from 1 to 100; defaults to 50"Output schema / properties / nextCursor / descriptionAdded value: +"Cursor for the next page; null on the last page"Output schema / properties / procedures / descriptionAdded value: +"Service catalog entries in name order. Patient-linked treatments, diagnoses, prescriptions and record identifiers are never returned."Output schema / properties / procedures / items / properties / duration / descriptionAdded value: +"Configured duration, or null when none was recorded"Output schema / properties / procedures / items / properties / price / descriptionAdded value: +"Price in the practice's currency"list_providers2 fields changedInput schema / properties / clinicId / descriptionPrevious value: -"Clinic id (24-character hex)"New value: +"Practice id: 24 lowercase hexadecimal characters"Output schema / properties / providers / descriptionAdded value: +"Display names of staff with a doctor, nurse or assistant role. Staff identifiers, contact details, role records and clinical data are never returned."list_rooms5 fields changedInput schema / properties / clinicId / descriptionPrevious value: -"Clinic id (24-character hex)"New value: +"Practice id: 24 lowercase hexadecimal characters"Input schema / properties / cursor / descriptionPrevious value: -"Opaque cursor from a prior result"New value: +"The nextCursor of the previous page with the same filters; absent for the first page"Input schema / properties / limit / descriptionAdded value: +"Rooms per page, from 1 to 100; defaults to 50"Output schema / properties / nextCursor / descriptionAdded value: +"Cursor for the next page; null on the last page"Output schema / properties / rooms / descriptionAdded value: +"Rooms in name order. Record identifiers, appointment links, patient information and clinical content are never returned."show_clinic_overview2 fields changedInput schema / properties / clinicId / descriptionPrevious value: -"DoctoFam clinic id to render"New value: +"Practice id: 24 lowercase hexadecimal characters"Output schema / properties / clinic / descriptionAdded value: +"Administrative practice metadata; null when the practice was not found. The overview never includes individual appointment records, patient information, diagnoses, treatment details, notes or other clinical data."get_clinicget_clinic_availabilityget_clinic_schedule_summaryget_subscription_statuslist_calendar_eventslist_clinicslist_procedureslist_providerslist_roomsshow_clinic_overviewSee your dental clinic's free slots, dentists, treatment prices and how busy each day is.
See your vet clinic's free slots, vets, service prices, payments and how busy each day is.
See your gym's open slots, services, how busy each day is and your payment totals.
See your salon's free slots, appointments, stylists, services, clients, quotes and payments.
Add one secure layer between your agents and this server.