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., "@mcp-cliniko show me today's appointments"
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.
A Model Context Protocol (MCP) server that provides integration with the Cliniko API for healthcare practice management.
Patient Management
list_patients - Search and list patients
get_patient - Get patient by ID
create_patient - Create new patient
update_patient - Update patient details
delete_patient - Archive patient
Appointment Management
list_appointments - Search and list appointments
get_appointment - Get appointment by ID
create_appointment - Book new appointment
update_appointment - Modify appointment
cancel_appointment - Cancel appointment
delete_appointment - Delete appointment
get_available_times - Get practitioner availability
Invoice Management
list_invoices - List and filter invoices
get_invoice - Get invoice details
create_invoice - Create new invoice
update_invoice - Update invoice status or details
delete_invoice - Delete draft invoice
Invoice Items
list_invoice_items - List items on an invoice
add_invoice_item - Add item to invoice
update_invoice_item - Modify invoice item
delete_invoice_item - Remove item from invoice
Payment Processing
list_payments - List payments with filtering
create_payment - Record a payment
delete_payment - Delete payment record
Products & Services
list_products - List billable products/services
get_product - Get product details
create_product - Create new product/service
Tax Configuration
list_taxes - List available tax rates
get_tax - Get tax details
Complex Workflows
create_invoice_from_appointments - Generate invoices from appointments
bulk_invoice_generation - Bulk create invoices for date range
list_patient_cases - List patient cases
list_invoices_for_case - Get invoices for a case
Supporting Tools
list_practitioners - List all practitioners
list_appointment_types - List appointment types
list_businesses - List businesses
Test Data
generate_test_data - Generate synthetic Australian healthcare data
cleanup_test_data - Remove test patients
patient://{id} - Individual patient data
patients://list - All patients
appointment://{id} - Individual appointment
appointments://list - All appointments
appointments://today - Today's appointments
practitioners://list - All practitioners
businesses://list - All businesses
appointment-types://list - All appointment types
openapi://spec - Cliniko API OpenAPI specification (YAML format)
Related MCP server: Cliniko MCP Server
Clone the repository:
git clone https://github.com/yourusername/mcp-cliniko.git
cd mcp-clinikoInstall dependencies:
npm installSet up your Cliniko API key:
cp .env.example .env
# Edit .env and add your Cliniko API keyBuild the project:
npm run buildCLINIKO_API_KEY - Your Cliniko API key (required)
Log into your Cliniko account
Go to Settings → Integrations → API Keys
Create a new API key
Copy the key to your .env file
npm run devnpm startnpm run inspectAdd to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json):
{
"mcpServers": {
"cliniko": {
"command": "node",
"args": ["/path/to/mcp-cliniko/dist/index.js"],
"env": {
"CLINIKO_API_KEY": "your-api-key-here"
}
}
}
}List Patients:
{
"tool": "list_patients",
"arguments": {
"q": "Smith",
"per_page": 10
}
}Create Patient:
{
"tool": "create_patient",
"arguments": {
"first_name": "John",
"last_name": "Doe",
"email": "john.doe@example.com",
"phone_number": "0412345678",
"date_of_birth": "1980-01-15",
"medicare_number": "1234567890"
}
}Book Appointment:
{
"tool": "create_appointment",
"arguments": {
"starts_at": "2024-01-20T10:00:00Z",
"patient_id": 123,
"practitioner_id": 456,
"appointment_type_id": 789,
"business_id": 101
}
}Generate Test Data:
{
"tool": "generate_test_data",
"arguments": {
"num_patients": 5,
"num_appointments": 10,
"days_ahead": 7
}
}Resources provide read-only access to Cliniko data:
patient://123 - Get patient with ID 123
patients://list - List all patients
appointments://today - Get today's appointments
Cliniko API has a rate limit of 200 requests per minute. The server does not implement rate limiting internally, so be mindful of this limit when making bulk operations.
The server uses standard HTTP error conventions:
400 - Bad Request
401 - Unauthorized (check API key)
404 - Resource not found
429 - Rate limit exceeded
500 - Internal server error
mcp-cliniko/
├── src/
│ ├── index.ts # Main server
│ ├── cliniko-client.ts # API client
│ ├── types.ts # TypeScript types
│ ├── tools/ # MCP tools
│ │ ├── patients.ts
│ │ ├── appointments.ts
│ │ └── synthetic-data.ts
│ └── resources/ # MCP resources
│ └── index.ts
├── dist/ # Compiled JavaScript
├── package.json
├── tsconfig.json
└── .envnpm run buildnpx tsc --noEmitMIT
For Cliniko API documentation, visit: https://docs.api.cliniko.com/
For MCP documentation, visit: https://modelcontextprotocol.io/# mcp-cliniko
Cancel an appointment
| Name | Required | Description | Default |
|---|---|---|---|
| appointment_id | Yes | Appointment ID | |
| cancellation_reason | No | Reason for cancellation |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, and the description does not disclose behavioral traits such as whether cancellation is reversible, what side effects occur, or required permissions. For a mutation tool, this is insufficient.
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 a single sentence, which is concise but omits important details that could be included without substantial length. It is minimally adequate but not optimized for value.
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 lack of annotations and output schema, the description fails to provide sufficient context about the tool's effect, prerequisites, or post-conditions. For a cancellation tool, this is incomplete.
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 already provides clear descriptions for both parameters (appointment_id and cancellation_reason), achieving 100% coverage. The tool description adds no additional meaning beyond what the schema offers.
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 verb 'cancel' and resource 'appointment', but does not differentiate from sibling tool 'delete_appointment', which likely has different semantics. This ambiguity lowers clarity.
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?
No guidance is provided on when to use cancel vs. other appointment management tools (e.g., delete_appointment). The description lacks context for decision-making.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Clean up all test data with granular control and dry-run option
| Name | Required | Description | Default |
|---|---|---|---|
| delete_patients | No | ||
| delete_appointments | No | ||
| delete_invoices | No | ||
| delete_products | No | ||
| delete_all_test_data | No | ||
| test_domain | No | test.cliniko.com | |
| dry_run | No | Preview what would be deleted without actually deleting |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description discloses the dry-run capability and implies destructiveness through 'clean up,' but it fails to mention that deletion is irreversible (unless dry-run), required permissions, or the test_domain scoping.
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 very concise (11 words) and front-loads the action, but it omits important details that could be added without significant verbosity, such as the list of deletable entities.
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 tool with 7 parameters, no output schema, and no annotations, the description does not explain return behavior, the effect of 'delete_all_test_data,' or the test_domain parameter, making it incomplete.
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 only 14% (only dry_run has a description). The description adds 'granular control' and 'dry-run' but does not explain the individual boolean toggles or the test_domain parameter, leaving most parameters underdocumented.
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 action ('clean up all test data') with modifiers ('granular control and dry-run option'), but it does not explicitly differentiate from the sibling tool 'cleanup_test_data' or specify what 'all test data' entails beyond the schema parameters.
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 no guidance on when to use this tool vs alternatives like 'cleanup_test_data' or other test data tools, nor does it mention any prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete all test patients (patients with emails ending in @gmail.com, @outlook.com, etc)
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description should disclose behavioral traits like irreversibility, permissions, or logging. It only states the deletion criteria, missing important safety context for a destructive 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?
The description is a single concise sentence (12 words) that is front-loaded and efficient. Every word is necessary.
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 having no parameters or output schema, the description lacks completeness for a destructive tool. It does not explain what 'test patients' fully entails, whether the operation is reversible, or what the outcome is. More context would be helpful.
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 are no parameters, and the schema coverage is 100%. Per scoring rules, zero parameters baseline is 4. The description adds no param info, which is acceptable because none exist.
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 action (delete), resource (test patients), and selection criteria (emails ending in @gmail.com, @outlook.com, etc). It distinguishes from the sibling 'cleanup_comprehensive_test_data' by being more specific.
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 implies usage for cleaning up test patients but does not explicitly state when to use this tool versus the sibling 'cleanup_comprehensive_test_data' or provide exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new appointment
| Name | Required | Description | Default |
|---|---|---|---|
| starts_at | Yes | Appointment start time (ISO 8601) | |
| patient_id | No | Patient ID (optional for walk-ins) | |
| practitioner_id | Yes | Practitioner ID | |
| appointment_type_id | Yes | Appointment type ID | |
| business_id | Yes | Business ID | |
| notes | No | Appointment notes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description fully bears the burden of behavioral disclosure. It only states 'Create', implying a write operation, but does not mention any side effects, required permissions, or error conditions. This is insufficient for a mutation tool.
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 a single, efficient sentence that conveys the core purpose. It is front-loaded and wastes no words, though it could be slightly more informative without harming 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?
Given the tool has 6 parameters (4 required) and no output schema, the description is overly minimal. It does not explain what the tool returns, any constraints on inputs, or how it behaves under failure. A more complete description would include return value or side effects.
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?
With 100% schema description coverage, the structured schema already documents all parameters. The description adds no additional meaning beyond the schema, so a baseline score of 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?
The description 'Create a new appointment' clearly states the action and resource, but does not distinguish this tool from siblings like 'update_appointment' or 'delete_appointment'. It is concise and direct, earning a 4 for clear purpose without differentiation.
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?
No guidance is provided on when to use this tool versus alternatives such as 'cancel_appointment' or 'get_appointment'. The description lacks any context about prerequisites or use cases, leaving the agent without decision support.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new patient
| Name | Required | Description | Default |
|---|---|---|---|
| first_name | Yes | Patient first name | |
| last_name | Yes | Patient last name | |
| title | No | Title (Mr, Ms, Dr, etc) | |
| preferred_name | No | Preferred name | |
| date_of_birth | No | Date of birth (YYYY-MM-DD) | |
| sex | No | Biological sex | |
| No | Email address | ||
| phone_number | No | Primary phone number | |
| address_line_1 | No | Address line 1 | |
| address_line_2 | No | Address line 2 | |
| suburb | No | Suburb/City | |
| postcode | No | Postcode | |
| state | No | State/Province | |
| country | No | Country | |
| medicare_number | No | Medicare number | |
| medicare_reference_number | No | Medicare reference number |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and description fails to disclose behavioral traits like success response, error conditions, or side effects beyond the bare 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?
Extremely concise (one sentence) but too terse; lacks essential information for a tool with 16 parameters and no 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?
Given 16 parameters, no output schema, and no annotations, the description is severely incomplete, omitting return values, prerequisites, and behavioral details.
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% with descriptions for all parameters; description adds no extra meaning, defaulting to 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?
Description clearly states 'Create a new patient', with a specific verb and resource, differentiating from siblings like update_patient or delete_patient.
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?
No guidance on when to use this tool versus alternatives such as update_patient or create_appointment; lacks context for appropriate use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete an appointment completely
| Name | Required | Description | Default |
|---|---|---|---|
| appointment_id | Yes | Appointment ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description should disclose behavioral traits such as irreversibility, required permissions, or side effects. 'Delete an appointment completely' only implies deletion but provides no further context.
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 extremely concise with a single sentence. It is front-loaded and wastes no words, but could be slightly more structured with additional context.
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 low complexity (1 parameter, no output schema), the description is minimally adequate but lacks behavioral context (e.g., whether deletion is permanent). It does not fully compensate for missing annotations.
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% (appointment_id is described). The description adds no additional meaning beyond the schema, so a baseline score of 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?
The description clearly states the verb 'Delete' and resource 'appointment', making the purpose unambiguous. However, it does not distinguish from the sibling tool 'cancel_appointment', which might have a similar effect.
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?
No guidance is provided on when to use this tool versus alternatives like 'cancel_appointment'. No conditions or exclusions are mentioned, leaving the agent to guess.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete (archive) a patient
| Name | Required | Description | Default |
|---|---|---|---|
| patient_id | Yes | Patient ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description indicates that the deletion is actually an archival action ('archive'), which is a behavioral trait. However, it does not disclose side effects, permissions needed, or impact on related data. Without annotations, more transparency would be beneficial.
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 extremely concise, front-loaded, and contains no unnecessary words. Every part earns its place for a simple delete operation.
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 one-parameter tool with no output schema, the description provides essential information about the action. It could mention permanence or reversibility, but overall it is adequately complete given the tool's simplicity.
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 fully describes the only parameter (patient_id) with a description 'Patient ID'. The description adds no additional meaning beyond the schema, so baseline score of 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?
The description clearly states the action 'Delete' and resource 'patient', with the parenthetical '(archive)' adding nuance. It distinctively identifies the tool among siblings as the only patient deletion tool.
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?
No guidance is provided on when to use this tool versus alternatives like update_patient or delete_appointment. There is no mention of prerequisites, when not to use, or context such as irreversible actions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Demo: Generate test patients and appointments, then show how to create invoices. NOTE: Cliniko API is READ-ONLY for invoices - they must be created via the web interface.
| Name | Required | Description | Default |
|---|---|---|---|
| target_date | No | Target date for appointments (YYYY-MM-DD format). Defaults to today | |
| num_patients | No | Number of test patients to generate (max 10 for rate limits) | |
| num_appointments | No | Number of appointments to generate (max 20 for rate limits) | |
| clear_existing | No | Clear existing test data before generating new data | |
| display_format | No | How to display the results | detailed |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must disclose all behaviors. It mentions generating test data and the invoice limitation, but fails to state that clear_existing defaults to true, which could delete existing data. The demo nature is implicit, but side effects are not fully 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 extremely concise with two short sentences, no filler, and front-loads the purpose. Every part is necessary and immediately informative.
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 demo tool with no output schema and no annotations, the description covers the core purpose and key limitation. It lacks detail on return value format or expected output, but the demo context makes this acceptable. It is sufficiently complete for its intended use.
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 baseline is 3. The description adds no parameter-specific meaning beyond the schema. It repeats the general demo context but does not elaborate on how parameters affect the outcome.
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 it generates test patients/appointments and demonstrates invoice creation, noting the API's read-only limitation. This distinguishes it as a demo tool, but its purpose overlaps with sibling generate_test_data tools, lacking explicit differentiation.
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 indicates it's a demo for invoice generation, but provides no guidance on when to use this tool vs. alternatives like generate_test_data or how_to_create_invoices. Context from sibling tools suggests overlap, but no exclusions or recommendations are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Display all existing invoices for a specific date (READ-ONLY). Invoices must be created manually in Cliniko.
| Name | Required | Description | Default |
|---|---|---|---|
| target_date | Yes | Date to display invoices for (YYYY-MM-DD format) | |
| display_format | No | How to display the invoices | detailed |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Declares the tool as READ-ONLY, providing clarity on its safety profile. Also mentions that invoices must be created manually, implying it does not create them. However, no annotations exist, so the description carries the full burden; it lacks details on auth requirements, rate limits, or behavior for missing dates.
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?
Extremely concise: two sentences with no redundancy. The main action and key constraint are front-loaded. Every sentence adds unique value.
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 read-only tool with two parameters and no output schema, the description covers the core purpose and a prerequisite. However, it does not explain the output format or error handling (e.g., no invoices on that date). Slightly above average due to the READ-ONLY note.
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% with descriptions for both parameters (target_date format and display_format enum). The description adds no additional meaning beyond the schema, so baseline score of 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?
Clearly states it displays invoices for a specific date and is read-only. The description uses specific verb 'display' and resource 'invoices' with a date filter. However, it does not explicitly differentiate from sibling tools like list_invoices or get_invoice, which have overlapping functionality.
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 one usage note ('Invoices must be created manually in Cliniko') but offers no guidance on when to use this tool versus alternatives like list_invoices or get_invoice. No when-not-to-use or explicit selection criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate comprehensive synthetic test data across all Cliniko categories
| Name | Required | Description | Default |
|---|---|---|---|
| num_patients | No | ||
| num_contacts | No | ||
| num_relationships | No | ||
| num_appointments | No | ||
| num_past_appointments | No | ||
| num_group_appointments | No | ||
| num_treatment_notes | No | ||
| num_medical_alerts | No | ||
| num_patient_cases | No | ||
| num_invoices | No | ||
| num_products | No | ||
| num_payments | No | ||
| days_ahead | No | ||
| days_past | No | ||
| test_domain | No | test.cliniko.com |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description does not disclose side effects (e.g., that it creates real records requiring cleanup), auth needs, or rate limits. Only states it generates test data.
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?
One efficient sentence, no wasted words; but lacks crucial details, making it feel under-specified rather than concise.
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 15 parameters, no output schema, and no annotations, description is extremely incomplete. Fails to explain return values, categories covered, side effects, or relationship to cleanup tools.
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%, but description adds no parameter information. Parameter names are self-explanatory, but description should compensate for lack of schema descriptions.
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 clearly states the tool generates comprehensive synthetic test data across all Cliniko categories, distinguishing it from siblings like generate_test_data which may be less comprehensive.
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?
No explicit guidance on when to use this vs. generate_test_data or other tools. Implies usage for comprehensive test generation but lacks when not to use or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate synthetic test data for Cliniko (Australian healthcare data)
| Name | Required | Description | Default |
|---|---|---|---|
| num_patients | No | Number of patients to create (max 50) | |
| num_appointments | No | Number of appointments to create (max 100) | |
| days_ahead | No | Days ahead to schedule appointments |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It only mentions 'synthetic test data' and the context, but does not indicate whether the tool is destructive, requires cleanup, or has side effects like creating real records. Given sibling tools like 'cleanup_test_data', this is a significant 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 a single, front-loaded sentence that efficiently conveys the core purpose. While concise, it could include more details without becoming verbose.
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 lack of annotations and output schema, the description should provide more context about what is actually generated (patients, appointments, etc.), whether it is safe for production use, and potential side effects. The current description is incomplete for a bulk data generation 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 input schema has 100% description coverage with clear min/max/default for each parameter. The tool description adds no extra meaning beyond the schema, so the baseline score of 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?
The description clearly states the verb 'generate' and the resource 'synthetic test data' with a specific context (Cliniko, Australian healthcare). It distinguishes itself from sibling tools that create individual entities like patients or appointments.
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 implies usage for generating test data but provides no explicit guidance on when to use this tool versus the more comprehensive sibling 'generate_comprehensive_test_data' or individual create tools. The context is implied, not explicitly stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a specific appointment by ID
| Name | Required | Description | Default |
|---|---|---|---|
| appointment_id | Yes | Appointment ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It does not mention whether the operation is read-only, if authentication is required, what happens if the ID does not exist (e.g., returns null or error), or any side effects.
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 very concise (one sentence), but it sacrifices valuable information. It is not overly verbose, but it could include more context without becoming lengthy.
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 simplicity of the tool and the lack of output schema, the description should clarify what data is returned (e.g., full appointment details) and any error handling. It fails to provide this, making it incomplete for an agent to understand the full behavior.
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 covers the single parameter (appointment_id) with 100% coverage, so the baseline is 3. The description only repeats 'by ID', adding no additional meaning or context 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 clearly states the verb 'Get', the resource 'appointment', and the lookup method 'by ID'. It distinguishes from sibling tools like list_appointments (which returns multiple) and create_appointment (which creates). However, it does not specify the scope of data returned.
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 no guidance on when to use this tool versus alternatives such as list_appointments (to find an ID) or get_appointment_invoices (for invoices). There is no mention of prerequisites or exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get invoices for a specific appointment (READ-ONLY)
| Name | Required | Description | Default |
|---|---|---|---|
| appointment_id | Yes | Appointment ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It correctly states 'READ-ONLY', signaling no mutation. However, it does not disclose whether the tool returns a list or single invoice, pagination behavior, or error handling. The minimal disclosure meets basic needs but lacks completeness.
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?
Extremely concise at 6 words, front-loaded with the key purpose. Every word earns its place with no redundancy or 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 simple one-parameter tool and no output schema, the description is minimally sufficient but does not explain the return value (list of invoices, summary vs full details). The presence of siblings like 'list_invoices' and 'get_invoice' creates a need for slightly more precision, yet the description barely differentiates beyond the appointment scope.
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 already fully describes the single parameter 'appointment_id' as 'Appointment ID'. The description adds no extra meaning about format, range, or how to obtain the ID. Per guidelines, with 100% schema coverage, baseline is 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 clearly states the action 'Get invoices' and the specific resource 'for a specific appointment'. The '(READ-ONLY)' suffix adds behavioral clarity. It distinguishes from siblings like 'list_invoices' (unfiltered) and 'get_patient_invoices' (by patient).
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?
No explicit guidance on when to use this tool versus alternatives like 'list_invoices' or 'get_patient_invoices'. The context is implied by the name and description, but explicit when-to-use or when-not-to-use instructions are missing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get available appointment times for a practitioner
| Name | Required | Description | Default |
|---|---|---|---|
| business_id | Yes | Business ID | |
| practitioner_id | Yes | Practitioner ID | |
| from | Yes | Start date for availability check (YYYY-MM-DD) | |
| to | Yes | End date for availability check (YYYY-MM-DD) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description bears full responsibility. It discloses no behavioral traits such as side effects (none expected from a 'get' operation), return format, or any constraints. The single sentence provides minimal behavioral context.
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 one short, front-loaded sentence with no wasted words. It efficiently conveys the core action and resource, appropriate for this simple tool.
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 4 required parameters, no output schema, and numerous sibling tools, the description is incomplete. It does not explain what the output represents (e.g., list of time slots) or how to interpret results, limiting its standalone usefulness.
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 100% parameter description coverage, so the foundation is adequate. The description does not add any additional meaning beyond what the schema already provides; thus, it meets the baseline without extra value.
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 ('Get') and resource ('available appointment times'), which is clear. However, it does not differentiate from sibling tools like 'list_appointments' that also deal with appointments, leaving some ambiguity about the distinct purpose.
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?
No guidance is provided on when to use this tool versus alternatives (e.g., 'list_appointments' for existing appointments, 'create_appointment' after finding times). There are no prerequisites or context cues for usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get details of a specific invoice (READ-ONLY)
| Name | Required | Description | Default |
|---|---|---|---|
| invoice_id | Yes | Invoice ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description solely bears the burden. It notes the tool is READ-ONLY, a key behavioral trait. However, it lacks details on authorization, error conditions, or the scope of 'details' returned.
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 a single, front-loaded sentence of 8 words with no extraneous information. Every word 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?
For a simple single-parameter retrieval tool, the description is adequate but could be improved by indicating what fields are returned (no output schema). It lacks completeness regarding the response structure.
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 only parameter 'invoice_id' is clearly described in the schema. The description does not add semantics beyond the schema, earning the baseline score.
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 clearly states 'Get details of a specific invoice (READ-ONLY)', specifying the verb, resource, and read-only nature. It distinguishes from sibling tools like list_invoices (which lists multiple) and get_appointment_invoices (which retrieves invoices by 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?
No guidance is provided on when to use this tool versus alternatives. It does not mention when not to use it, prerequisites, or context for selection among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a specific patient by ID
| Name | Required | Description | Default |
|---|---|---|---|
| patient_id | Yes | Patient ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It only states 'Get' implying idempotent read, but does not mention error behavior (e.g., if ID not found), authentication requirements, or whether the response is a full patient object. Minimal disclosure.
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 a single sentence with no extraneous words, front-loaded with the verb and resource. Efficient and clear.
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 is simple (single required parameter, no output schema), the description should still specify what is returned (e.g., patient details). It fails to mention the response format, leaving the agent uncertain about the tool's output.
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 covers 100% of parameters with description 'Patient ID'. The description echoes 'by ID' but adds no additional meaning beyond the schema. Baseline score 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?
The description clearly states the verb 'Get' and the resource 'specific patient by ID'. It is unambiguous, but does not differentiate from sibling tools like 'get_appointment' or 'get_invoice', which have similar structure.
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?
No guidance on when to use this tool vs alternatives such as 'list_patients' or 'create_patient'. No when-not-to-use or preconditions provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get invoices for a specific patient (READ-ONLY)
| Name | Required | Description | Default |
|---|---|---|---|
| patient_id | Yes | Patient ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It explicitly marks the operation as READ-ONLY, which is good for transparency. However, beyond that, it does not disclose any other behavioral traits (e.g., no pagination, ordering, or data format details). For a read-only list tool, this is adequate but not rich.
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 a single sentence with five words plus a parenthetical. It is extremely concise with no redundant information, earning its place without wasting tokens.
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, no output schema, read-only), the description is adequate but lacks context on what the returned invoices contain or any filtering capabilities. There is no mention of return format or how it differs from similar siblings like 'get_appointment_invoices' or 'list_invoices', leaving some gaps.
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% as the input schema documents the only parameter 'patient_id' with a brief description. The tool description does not add any extra meaning or context beyond what the schema already provides (e.g., format or source of patient_id). 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 clearly states 'Get invoices for a specific patient' with a verb ('Get'), resource ('invoices'), and scope ('for a specific patient'). The '(READ-ONLY)' qualifier further clarifies the operation's nature, and it implicitly distinguishes from sibling tools like 'get_appointment_invoices' or 'list_invoices'.
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 does not explicitly specify when to use this tool over alternatives such as 'get_invoice' (single invoice) or 'list_invoices' (all invoices). While it is implied that this tool filters by patient, no explicit when-to-use or when-not-to-use guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get instructions on how to create invoices in Cliniko (manual process)
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It correctly implies a read-only informational operation (manual process), but does not explicitly state side effects or auth requirements. For a help tool, this is acceptable but could be improved.
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 a single, clear sentence of 12 words. It is appropriately concise for the tool's simplicity, though it could be slightly more structured (e.g., 'Provides step-by-step instructions on manually creating invoices.').
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 no parameters, no output schema, and is a simple help text function, the description is complete enough. It conveys the purpose and nature (manual process) sufficiently for an AI agent to select 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?
No parameters exist, so the description does not need to add semantic meaning. Baseline score of 4 is appropriate as the description is not required to compensate for any schema gaps.
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 it provides instructions on creating invoices, distinguishing it from action-oriented siblings. However, the word 'get instructions' is a bit vague; specifying it as a guide would improve clarity.
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?
No explicit guidance on when to use this tool versus alternatives like demo_invoice_generation or create_appointment. The context implies it's for manual process information, but this is not stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List or search for appointments
| Name | Required | Description | Default |
|---|---|---|---|
| patient_id | No | Filter by patient ID | |
| practitioner_id | No | Filter by practitioner ID | |
| business_id | No | Filter by business ID | |
| starts_at | No | Filter appointments starting from (ISO 8601) | |
| ends_at | No | Filter appointments ending before (ISO 8601) | |
| status | No | Filter by status (Active, Cancelled, Did not arrive) | |
| page | No | Page number | |
| per_page | No | Results per page (max 100) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden for behavioral disclosure. It only says 'list or search,' omitting key traits like read-only nature, pagination behavior, sorting, or rate limits. The description adds minimal behavioral context beyond the 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 minimal and front-loaded, but it is arguably too short. It gets the point across but lacks structure or additional helpful details, failing to earn its place fully.
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 8 parameters, no output schema, and many sibling tools, the description is incomplete. It does not explain return values, pagination behavior, or how to perform a broad list vs. filtered search. The schema covers parameters, but overall context is lacking.
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 the description doesn't need to add much. It reiterates 'list or search,' which implies parameter combinations (filtered search vs. unfiltered list), but this is a minor semantic addition 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 clearly states the verb (list/search) and resource (appointments), distinguishing it from siblings like get_appointment (single) or cancel_appointment. However, it lacks specificity about the scope of listings (e.g., all appointments or filtered) and could be more precise.
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?
No guidance on when to use this tool vs. alternatives like get_appointment or other list tools. Missing explicit context for when to use list vs search, or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all appointment types
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number | |
| per_page | No | Results per page |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It only states 'List all appointment types' without revealing pagination behavior, default sorting, or other traits like response limits, which are critical for agent usage.
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 a single sentence, front-loaded with the key action and object, containing no unnecessary words. It perfectly balances brevity and clarity.
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 presence of two pagination parameters, the description is adequate but incomplete. It does not explain the return format or default behavior (e.g., all results vs paginated), which would be helpful without an output schema.
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 baseline is 3. The description adds no extra meaning beyond the schema's definitions for 'page' and 'per_page', remaining neutral.
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 'List all appointment types' uses a specific verb and resource, clearly indicating the tool's function. It is distinct from sibling tools like 'list_appointments' which list appointments, not 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?
No guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites, context, or exclusions, leaving the agent without direction for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all businesses
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden. It only states 'list all businesses' with no disclosure of behavioral traits such as read-only nature, authentication requirements, pagination, or side effects. This is insufficient for safe tool selection.
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 extremely concise at two words. Every word is necessary and the purpose is front-loaded. No waste.
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-all tool with no parameters and no output schema, the description is minimally adequate. It lacks any explanation of what a 'business' is or what the return format looks like, but the simplicity reduces the need. Still, it could be improved.
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 are no parameters, so the description adds no parameter-level information. Per the rubric, 0 parameters yields a baseline of 4. The description does not contradict the empty 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 action (list) and the resource (businesses). It distinguishes from siblings because each sibling tool targets a different entity type (appointments, patients, etc.). However, it lacks any qualifiers or scope details.
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?
No guidance on when to use this tool versus alternatives. There is no mention of use cases, prerequisites, or exclusions. The agent must infer usage solely from the resource name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List items in an invoice (READ-ONLY)
| Name | Required | Description | Default |
|---|---|---|---|
| invoice_id | Yes | Invoice ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must cover behavioral traits. '(READ-ONLY)' indicates no side effects, but lacks details on pagination, sorting, error handling, or whether it returns all items or a subset.
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?
Extremely concise—one short phrase. No wasted words, but could be structured as a full sentence to improve readability. Efficient for simple tool.
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 single parameter, no output schema, and no annotations, the description is minimal but adequate. Lacks details on return value structure, error cases, or usage hints. Could be improved with one or two more sentences.
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% (parameter 'invoice_id' documented). Description adds '(READ-ONLY)' but no additional param meaning. Baseline 3 for high coverage.
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 clearly states 'List items in an invoice' with a specific verb and resource, and the '(READ-ONLY)' suffix distinguishes it from mutation tools like create/update/delete. It differentiates from sibling 'list_invoices' by specifying granularity.
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?
No guidance on when to use this tool versus alternatives. Does not mention prerequisites (e.g., must have invoice_id from get_invoice) or context where it is appropriate or not.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List invoices with filtering options (READ-ONLY - invoices must be created in Cliniko web interface)
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number | |
| per_page | No | Results per page | |
| patient_id | No | Filter by patient ID | |
| practitioner_id | No | Filter by practitioner ID | |
| issued_at_from | No | Filter from date (YYYY-MM-DD) | |
| issued_at_to | No | Filter to date (YYYY-MM-DD) | |
| status | No | Filter by status |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Notes READ-ONLY but no annotations provided; description omits pagination behavior, default limits, ordering, or response structure, leaving significant gaps.
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?
Single sentence with front-loaded purpose. Efficient but could benefit from bullet points or clearer separation of read-only constraint.
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?
No output schema; description fails to mention return structure, pagination details, or error handling. Incomplete for a list operation with many optional filters.
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 100% of parameters with descriptions. Description adds only generic 'filtering options' without enhancing parameter understanding beyond 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?
Description clearly states it lists invoices with filtering options and notes read-only nature. However, it does not differentiate from sibling list_invoice_items or display_invoices_for_date.
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?
Mentions invoices must be created elsewhere, implying no create via this tool, but lacks explicit when-to-use vs. other invoice-related tools like get_invoice or get_patient_invoices.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List or search for patients
| Name | Required | Description | Default |
|---|---|---|---|
| q | No | Search query (searches name, email, phone) | |
| page | No | Page number | |
| per_page | No | Results per page (max 100) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries full burden. It offers no behavioral details such as pagination behavior, default ordering, authentication requirements, or what happens when no query is provided. Only states 'List or search' without elaboration.
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?
Extremely concise at 4 words, but lacks necessary information. While it is brief, it sacrifices completeness. A good concise description would include key details like pagination or search scope.
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 list/search tool with 3 parameters and no output schema, the description is incomplete. It does not mention pagination behavior, search field specifics, or any constraints. Sibling tools exist that provide more context.
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?
Input schema has 100% description coverage, so the schema already explains the parameters. The description adds no extra meaning beyond the schema. Baseline score of 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?
Description clearly states 'List or search for patients' which identifies the action and resource. It implies listing all patients or searching by query, but does not explicitly differentiate from sibling tools like get_patient (single patient) or list_appointments. However, the verb-resource combination is specific enough.
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?
No guidance on when to use this tool versus alternatives (e.g., get_patient, list_invoices). The description does not provide context on optimal use cases or limitations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all practitioners
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number | |
| per_page | No | Results per page |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and the description does not disclose behavioral traits such as pagination, authentication requirements, or that 'all' may be limited by pagination. Description carries full burden and is insufficient.
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?
Extremely concise, no superfluous text, but could be improved with a front-loaded structure that includes key details.
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 simple schema and lack of output schema, the description omits pagination context and return format, leaving the agent uncertain about the full scope of 'all' and the response structure.
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 describes both parameters (page, per_page) with 100% coverage, so description adds no additional meaning beyond what is already present.
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 'List all practitioners' clearly states the action and resource, but fails to differentiate from sibling list tools like 'list_patients' or 'list_appointments', which have similar phrasing.
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?
No guidance on when to use this tool versus alternatives; no context about prerequisites or filtering capabilities.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing appointment
| Name | Required | Description | Default |
|---|---|---|---|
| appointment_id | Yes | Appointment ID | |
| starts_at | No | New start time (ISO 8601) | |
| notes | No | Updated notes | |
| patient_id | No | New patient ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description should disclose update behavior (e.g., partial vs full update, validation, return value). It only says 'update', leaving important behavioral traits unspecified.
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 a single, concise sentence with no unnecessary words. It is appropriately sized and 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?
Given the tool has 4 parameters (1 required) and no output schema, the description fails to provide essential context about what fields get updated, error handling, or return values. It is insufficient for an AI agent to use 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%, so the description doesn't need to add param details. It adds no additional meaning beyond what the schema already provides, earning the baseline score of 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 clearly states the tool updates an existing appointment, which distinguishes it from create and delete siblings. However, it doesn't specify which fields can be updated or differentiate from cancel_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?
No guidance on when to use this tool versus alternatives like cancel_appointment or create_appointment. No prerequisites or context provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing patient
| Name | Required | Description | Default |
|---|---|---|---|
| patient_id | Yes | Patient ID | |
| first_name | No | Patient first name | |
| last_name | No | Patient last name | |
| title | No | Title (Mr, Ms, Dr, etc) | |
| preferred_name | No | Preferred name | |
| date_of_birth | No | Date of birth (YYYY-MM-DD) | |
| sex | No | Biological sex | |
| No | Email address | ||
| phone_number | No | Primary phone number | |
| address_line_1 | No | Address line 1 | |
| address_line_2 | No | Address line 2 | |
| suburb | No | Suburb/City | |
| postcode | No | Postcode | |
| state | No | State/Province | |
| country | No | Country | |
| medicare_number | No | Medicare number | |
| medicare_reference_number | No | Medicare reference number |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided. The description 'update' implies mutation but does not disclose side effects, permissions needed, or whether partial updates are allowed. For a write operation with 17 parameters, more transparency is needed.
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 a single sentence with no waste. It front-loads the core purpose. Every word 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?
Given 17 parameters, no output schema, and no annotations, the description is too brief. It lacks constraints (e.g., required fields beyond patient_id, validation rules, idempotency). The high parameter count demands more behavioral context.
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% (all 17 parameters have descriptions). The tool description adds no extra meaning beyond the schema, so 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?
The description is clear: 'Update an existing patient' specifies the verb (update) and resource (patient). It distinguishes from sibling tools like create_patient or delete_patient, though it could be more specific about what fields are updatable.
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?
No guidance on when to use this tool versus alternatives like create_patient or list_patients. No exclusions, prerequisites, or context provided. The agent must infer usage from the name.
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.
v1.0.0cancel_appointmentcleanup_comprehensive_test_datacleanup_test_datacreate_appointmentcreate_patientdelete_appointmentdelete_patientdemo_invoice_generationdisplay_invoices_for_dategenerate_comprehensive_test_datagenerate_test_dataget_appointmentget_appointment_invoicesget_available_timesget_invoiceget_patientget_patient_invoiceshow_to_create_invoiceslist_appointment_typeslist_appointmentslist_businesseslist_invoice_itemslist_invoiceslist_patientslist_practitionersupdate_appointmentupdate_patientMost tools target distinct resources (patients, appointments, invoices) with clear purposes. However, cleanup_test_data and cleanup_comprehensive_test_data are very similar, and demo_invoice_generation overlaps with how_to_create_invoices in providing guidance.
All tool names follow a consistent verb_noun pattern in snake_case (e.g., create_patient, list_appointments, delete_patient). No mixing of styles or ambiguous verbs.
27 tools is slightly high for a healthcare practice server. Multiple test data generation and cleanup tools add redundancy, and several invoice tools are read-only due to API limitations, reducing effective utility. A more streamlined set (around 15-20) would be better.
CRUD operations are covered for patients and appointments, along with listings and searches. Invoice operations are read-only but acknowledged. Missing features like appointment notes or patient tags are minor given the domain focus.
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.
Read appointments, types, calendars and availability; create, cancel or reschedule bookings.
Scheduling, availability, clients, billing and CRM for appointment-based services.
Operate the Plixana CRM from any AI: contacts, deals, quotes, WhatsApp and metrics.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/andymillar84-cyber/mcp-cliniko'
If you have feedback or need assistance with the MCP directory API, please join our Discord server