This server provides a comprehensive Model Context Protocol (MCP) interface for athenahealth's clinical data and services, enabling AI-powered clinical decision support and automated healthcare workflows.
Core Capabilities:
Patient Management: Search patients by name, DOB, phone, or email; register new patients with demographic information
Clinical Data Access: Retrieve comprehensive patient summaries including allergies, prescriptions, problems, vitals, labs, and clinical alerts
Medication Management: Check drug interactions and create prescriptions with detailed dosage instructions
Appointment Management: Check available slots by department/date range and schedule appointments
Provider & Department Management: List departments and healthcare providers with specialty filtering
Encounter Management: Access patient encounters and create/update encounter details
AI-Powered Workflows: Generate clinical assessment prompts, medication reviews, and care plans
Technical Features:
Integration Flexibility: Works as MCP server for Claude Desktop or webhook bridge for n8n automation
Robustness: Automatic rate limiting, exponential backoff, comprehensive error handling, and network retry logic
HIPAA Compliance: Data sanitization, audit logging, role-based access controls, and secure encryption
Environment Notes: Patient search, registration, and provider/department listing work in sandbox. Most clinical features (drug interactions, prescriptions, appointments, encounters) require production environment access.
Built on Node.js runtime environment for server execution and dependency management
Uses npm package manager for dependency installation and project management
Implemented in TypeScript for type-safe development and compilation
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., "@athenahealth MCP Server check for drug interactions between amoxicillin and warfarin for patient ID 456"
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 seamless integration with athenahealth's clinical data and services for AI-powered clinical decision support.
Status | Count | Percentage |
✅ Working in Sandbox | 5 | 38% |
❌ Not Working (Sandbox Limitations) | 8 | 62% |
🧪 Total Tools | 13 | 100% |
Related MCP server: Epic Healthcare MCP Server
Patient Data Access: Comprehensive patient information including demographics, medical history, and clinical data
Prescription Management: Medication history, drug interaction checking, and prescription creation (Production only)
Provider Management: Healthcare provider directory and practice information
Clinical Alerts: Real-time clinical decision support alerts and warnings (Production only)
Lab Results: Access to laboratory results and diagnostic reports (Production only)
Vital Signs: Patient vital signs history and trending (Production only)
Data Sanitization: Automatic sanitization of sensitive healthcare data in logs
Audit Logging: Comprehensive audit trails for all data access and modifications
Access Controls: Role-based access controls and authentication
Data Encryption: Secure data transmission and storage
Clinical Assessment: AI-powered clinical assessment prompts
Medication Review: Automated medication review and optimization (handles sandbox limitations)
Care Plan Generation: Evidence-based care plan development
Clinical Summarization: Comprehensive patient clinical summaries
Node.js 18.0.0 or later
athenahealth Developer Account and API credentials
TypeScript 5.0.0 or later
Clone the repository
git clone https://github.com/ophydami/athenahealth-mcp-server.git
cd athenahealth-mcp-serverInstall dependencies
npm installConfigure environment variables
cp config/environment.example .env
# Edit .env with your athenahealth API credentialsBuild the project
npm run buildStart the MCP server
npm startConfigure Claude Desktop
claude mcp add athenahealth-mcpIf you prefer using n8n for workflow automation instead of Claude Desktop, you can use the webhook bridge:
Complete steps 1-4 above
Start the webhook bridge server
npm run webhook-bridgeThe server will start on http://localhost:3000 (configurable via WEBHOOK_PORT env variable)
Use in n8n workflows
In your n8n workflow, add an HTTP Request node with:
Method: GET or POST (depending on endpoint)
URL: http://localhost:3000/[endpoint]
Authentication: None (handled by environment variables)
Body: JSON (for POST requests)
Example n8n HTTP Request nodes:
List Departments:
Method: GET
URL: http://localhost:3000/departmentsSearch Patients:
Method: POST
URL: http://localhost:3000/patients/search
Body: {
"lastname": "Smith",
"firstname": "John"
}Create Patient:
Method: POST
URL: http://localhost:3000/patients
Body: {
"firstname": "John",
"lastname": "Test",
"dob": "05/20/1985",
"sex": "M",
"department_id": "1",
"email": "john.test@example.com",
"mobile_phone": "6179876543"
}Get Clinical Summary:
Method: GET
URL: http://localhost:3000/patients/134/clinical?include_allergies=true&include_prescriptions=trueView available endpoints
Navigate to http://localhost:3000/ in your browser to see all available endpoints and their documentation.
Variable | Description | Required | Default |
| athenahealth API Client ID | Yes | - |
| athenahealth API Client Secret | Yes | - |
| athenahealth API Base URL | Yes | - |
| API Version | No |
|
| Practice ID | Yes | - |
| Webhook bridge server port (n8n mode) | No |
|
| Environment | No |
|
| Log Level | No |
|
Create Developer Account
Create a developer account
Request sandbox access
Create API Application
Create a new application in the developer portal
Note down your Client ID and Client Secret
Configure OAuth 2.0 settings
Get Practice ID
Contact athenahealth support to get your Practice ID
This is required for API access
Status: ✅ Fully Working Description: Lists all departments in the athenahealth practice
Parameters: None required
Example:
// List all departments
const departments = await mcpClient.callTool('list_departments', {});Status: ✅ Fully Working Description: Lists all healthcare providers in the practice
Parameters:
name (optional) - Filter by provider name
specialty (optional) - Filter by specialty
limit (optional) - Maximum results (default: 50)
Example:
// List all providers
const providers = await mcpClient.callTool('list_providers', {
specialty: 'Cardiology',
limit: 20
});Status: ✅ Fully Working Description: Search for patients by name, DOB, phone, or email
Parameters (at least ONE required):
firstname - Patient first name
lastname - Patient last name
dob - Date of birth (MM/DD/YYYY)
phone - Phone number
email - Email address
limit (optional) - Maximum results (default: 10)
Example:
// Search for patients by name
const patients = await mcpClient.callTool('search_patients', {
firstname: 'John',
lastname: 'Smith',
limit: 10
});Status: ✅ Fully Working Description: Register a new patient in the athenahealth system
Parameters (required):
firstname - Patient first name
lastname - Patient last name
dob - Date of birth (MM/DD/YYYY)
sex - Sex (M or F)
department_id - Primary department ID
Parameters (optional):
email, mobile_phone, home_phone, address1, city, state, zip
guarantor_firstname, guarantor_lastname, guarantor_dob, guarantor_relationship
Important:
✅ Valid North American phone numbers required (not 555 area code)
✅ Date format: MM/DD/YYYY or YYYY-MM-DD
Example:
const patient = await mcpClient.callTool('create_patient', {
firstname: 'John',
lastname: 'Test',
dob: '05/20/1985',
sex: 'M',
department_id: '1',
email: 'john.test@example.com',
mobile_phone: '6179876543',
address1: '123 Main St',
city: 'Boston',
state: 'MA',
zip: '02101'
});Status: ✅ Working (returns empty in sandbox) Description: Check available appointment slots for a department and date range
Parameters:
department_id (required) - Department ID
start_date (required) - Start date (YYYY-MM-DD)
end_date (required) - End date (YYYY-MM-DD)
provider_id (optional) - Specific provider ID
appointment_type (optional) - Type of appointment
Note: Returns empty array in sandbox (no scheduling templates configured)
Example:
const availability = await mcpClient.callTool('check_appointment_availability', {
department_id: '1',
start_date: '2025-11-01',
end_date: '2025-11-07',
provider_id: '23'
});These tools require production environment with full clinical access.
Status: ❌ Not Working - 404 Error Reason: Endpoint not available in sandbox, requires scheduling templates
Status: ❌ Not Working - Tool Execution Failed Reason: Requires clinical endpoints and drug interaction database
Status: ❌ Not Working - Clinical Endpoints Unavailable Reason: Clinical data endpoints (allergies, prescriptions, problems, vitals, labs, alerts) return 404
Status: ❌ Not Working - 404 Error Reason: E-prescribing endpoint not available in sandbox
Status: ❌ Not Working - 404 Error Reason: Encounter endpoints not available in sandbox environment
Status: ❌ Not Working - 404 Error Reason: Encounter endpoints not available in sandbox environment
Status: ❌ Not Working - 404 Error Reason: Encounter creation requires production API with clinical documentation access
Status: ❌ Not Working - 404 Error Reason: Encounter endpoints not available in sandbox environment
Note: See athenahealth-mcp-tools-readme.md for detailed information on production requirements for these tools.
Generate clinical assessment prompts with patient data
Parameters:
patient_id (required)
chief_complaint (optional)
Generate medication review prompts (handles sandbox limitations gracefully)
Parameters:
patient_id (required)
Generate care plan development prompts
Parameters:
patient_id (required)
diagnosis (optional)
// Step 1: List departments
const departments = await mcpClient.callTool('list_departments', {});
const departmentId = departments[0].departmentid;
// Step 2: Create a test patient
const patient = await mcpClient.callTool('create_patient', {
firstname: 'John',
lastname: 'Test',
dob: '05/20/1985',
sex: 'M',
department_id: departmentId,
email: 'john.test@example.com',
mobile_phone: '6179876543',
address1: '123 Main St',
city: 'Boston',
state: 'MA',
zip: '02101'
});
// Returns: { patientid: "61378" }
// Step 3: Search for the patient
const searchResults = await mcpClient.callTool('search_patients', {
lastname: 'Test',
dob: '05/20/1985'
});
// Step 4: List providers
const providers = await mcpClient.callTool('list_providers', {
specialty: 'Family Medicine'
});Sandbox Environment:
✅ Patient registration workflows
✅ Demographics and search
✅ Department and provider listing
✅ Appointment availability checking (returns empty)
❌ Clinical data (allergies, prescriptions, problems, vitals, labs)
❌ Encounter management (get, create, update)
❌ Appointment creation
❌ E-prescribing
❌ Drug interaction checking
Production Environment: Requires:
Full athenahealth production API access
Clinical endpoints enabled (allergies, prescriptions, problems, vitals, labs, alerts)
Encounter documentation access
E-prescribing licenses and integrations
Scheduling templates configured
Provider credentials (NPI, DEA numbers)
HIPAA compliance measures
✅ MUST use valid North American area codes (617, 212, 415, etc.)
❌ CANNOT use 555 (reserved for fictional use)
✅ MM/DD/YYYY (e.g., 05/20/1985)
✅ YYYY-MM-DD (e.g., 1985-05-20)
All sensitive healthcare data is automatically sanitized in logs
Patient identifiers are redacted in audit logs
API communications use form-urlencoded for POST requests
Access controls prevent unauthorized data access
All data access is logged with timestamps
User actions are tracked for compliance
Failed access attempts are recorded
Audit logs are stored separately with extended retention
Environment Security: Store credentials in environment variables, never in code
Access Controls: Implement role-based access controls
Data Minimization: Only request necessary data
Regular Audits: Review audit logs regularly
Secure Deployment: Use secure deployment practices
athenahealth API has rate limits:
Production: 1000 requests per minute
Sandbox: 100 requests per minute
The server automatically handles rate limiting and implements exponential backoff for failed requests.
The server provides comprehensive error handling:
Authentication Errors: Automatic token refresh
API Errors: Structured error responses with details
Network Errors: Retry logic with exponential backoff
Validation Errors: Input validation with detailed messages
Sandbox Limitations: Graceful handling with informative error messages
npm run devnpm testnpm run buildThe codebase is modularized for maintainability:
MCP Server Layer:
src/mcp-server.ts - Main MCP server (323 lines)
src/handlers/tool-handlers.ts - Tool implementations (635 lines)
src/handlers/prompt-handlers.ts - Prompt generators (130 lines)
src/handlers/resource-handlers.ts - Resource handlers (189 lines)
src/definitions/tools.ts - Tool schemas (226 lines)
API Client Layer (Service-Oriented):
src/services/athenahealth-client.ts - Unified client interface (130 lines)
src/services/base-client.ts - Authentication & HTTP client (220 lines)
src/services/patient-service.ts - Patient operations (130 lines)
src/services/clinical-service.ts - Clinical data (160 lines)
src/services/encounter-service.ts - Encounter management (100 lines)
src/services/scheduling-service.ts - Appointments & providers (160 lines)
athenahealth-mcp-tools-readme.md - Complete tool reference guide
athenahealth API Documentation - Official API docs
Developer Portal - athenahealth developer resources
For support and questions:
Create an issue in the GitHub repository
Review the comprehensive tool reference guide
Contact the author: Gboyega Ofi at gboyega.ofi@gmail.com
Contact athenahealth Developer Support: developer-support@athenahealth.com
Added encounter management functionality (4 new tools: get_patient_encounters, get_encounter, create_encounter, update_encounter)
Refactored athenahealth client into service-oriented architecture
Separated into base-client, patient-service, clinical-service, encounter-service, scheduling-service
Reduced file sizes from 800 lines to 100-220 lines per module
Total tools increased from 9 to 13
Documented encounter endpoints return 404 in sandbox (require production)
Enhanced architecture documentation with service layer breakdown
Refactored codebase into modular architecture
Fixed form-urlencoded POST request formatting for all endpoints
Added graceful handling of sandbox limitations
Enhanced medication_review prompt with sandbox support
Improved error messages with detailed API responses
Created comprehensive tool reference documentation
Initial release
Basic MCP server implementation
Patient data access
Prescription management
Clinical decision support prompts
HIPAA-compliant logging
OAuth 2.0 authentication
MIT License - see LICENSE file for details.
Copyright (c) 2025 Gboyega Ofi (gboyega.ofi@gmail.com)
⚠️ Important: This software handles sensitive healthcare data. Ensure you comply with all applicable healthcare regulations including HIPAA, HITECH, and other relevant standards in your jurisdiction.
📖 For detailed tool specifications and production requirements, see athenahealth-mcp-tools-readme.md
Acknowledge a clinical alert
| Name | Required | Description | Default |
|---|---|---|---|
| alert_id | Yes | Alert ID | |
| acknowledged_by | Yes | User acknowledging the alert |
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. 'Acknowledge' implies a state change (likely marking an alert as acknowledged), but the description doesn't specify if this is a mutation, what permissions are needed, whether it's reversible, or what the response looks like. For a clinical tool with zero annotation coverage, this is a significant gap in safety and operational 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 a single, efficient sentence with zero waste—it directly states the tool's purpose without fluff. It's appropriately sized for a simple tool and front-loaded, making it easy for an AI agent to parse quickly.
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 clinical context, no annotations, and no output schema, the description is incomplete. It lacks details on behavioral traits (e.g., mutation effects, error handling), return values, or clinical workflow integration. For a tool that likely modifies alert states in a healthcare setting, more context is needed to ensure safe and correct usage by an AI agent.
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 both parameters ('alert_id' and 'acknowledged_by') documented in the schema. The description adds no additional meaning beyond the schema, such as format examples or clinical context (e.g., alert IDs from prior alerts, user identifiers). Baseline 3 is appropriate since the schema handles parameter documentation adequately.
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 ('acknowledge') and resource ('clinical alert'), making the purpose immediately understandable. It doesn't differentiate from sibling tools, but all siblings are distinct operations (create, get, list, update) rather than alternative alert management tools, so differentiation isn't needed. The purpose is specific but could be more detailed about what 'acknowledge' entails.
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. There are no explicit sibling tools for alert management, but it doesn't mention prerequisites (e.g., after receiving an alert), exclusions, or context for acknowledgment. Usage is implied by the name but not elaborated, leaving gaps for an AI agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check available appointment slots for a department and date range
| Name | Required | Description | Default |
|---|---|---|---|
| department_id | Yes | Department ID | |
| provider_id | No | Provider ID (optional - leave empty to check all providers) | |
| appointment_type | No | Appointment type (optional) | |
| start_date | Yes | Start date (YYYY-MM-DD) | |
| end_date | Yes | End date (YYYY-MM-DD) |
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 states what the tool does but lacks details on permissions needed, rate limits, whether results are real-time or cached, pagination, or error handling. For a read operation with no annotation coverage, this is a significant gap in transparency.
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 front-loads the core purpose without unnecessary words. Every part of the sentence earns its place by specifying the action, resource, and key constraints.
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 5 parameters with full schema coverage but no annotations or output schema, the description is minimally adequate. It covers the basic purpose but lacks behavioral context (e.g., response format, limitations), which is important for a tool with multiple optional parameters and no structured output documentation.
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 schema already documents all 5 parameters thoroughly. The description adds no additional parameter semantics beyond implying date-range and department filtering, which is already covered in the schema. Baseline 3 is appropriate when the schema does the heavy lifting.
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 'check' and the resource 'available appointment slots', specifying the scope with 'for a department and date range'. It distinguishes from siblings like 'create_appointment' or 'list_departments', but doesn't explicitly differentiate from similar tools (e.g., if there were a 'search_appointments' sibling).
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 finding available slots before creating appointments, but doesn't explicitly state when to use this vs. alternatives like 'create_appointment' or other scheduling tools. No exclusions or prerequisites are mentioned, leaving usage context somewhat open-ended.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check for drug interactions for a patient
| Name | Required | Description | Default |
|---|---|---|---|
| patient_id | Yes | Patient ID | |
| medications | Yes | List of medication names or RxNorm codes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden but only states the basic action without behavioral details. It doesn't disclose critical traits like whether this is a read-only check (likely, but not confirmed), if it requires specific permissions, potential rate limits, or what happens on errors (e.g., invalid patient ID). This leaves gaps for safe agent invocation.
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 directly states the tool's purpose without fluff. It's appropriately sized for a simple tool, though it could be slightly more informative (e.g., adding context on output) without losing 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 no annotations and no output schema, the description is incomplete for a tool that likely returns critical clinical data. It doesn't explain what the check entails (e.g., interaction severity, recommendations) or the return format, leaving the agent uncertain about behavioral outcomes. For a 2-parameter tool with high schema coverage, it compensates poorly for missing structured 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%, so the schema already documents both parameters (patient_id and medications). The description adds no extra meaning beyond implying the parameters are used together for interaction checking, but doesn't clarify semantics like medication format expectations (e.g., brand vs. generic names) beyond the schema's 'medication names or RxNorm codes'.
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 'Check for drug interactions for a patient' clearly states the action (check) and resource (drug interactions), but it's vague about scope (e.g., severity levels, interaction types) and doesn't differentiate from potential siblings like 'create_prescription' or 'get_clinical_summary' that might involve medication safety. It avoids tautology by not restating the tool name, but lacks specificity.
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., 'create_prescription' for prescribing, 'get_clinical_summary' for broader patient data). The description implies usage in medication safety contexts but offers no explicit when/when-not rules or prerequisites, such as needing patient consent or prior medication lists.
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 for a patient
| Name | Required | Description | Default |
|---|---|---|---|
| patient_id | Yes | Patient ID | |
| provider_id | Yes | Provider ID | |
| department_id | Yes | Department ID | |
| appointment_type | Yes | Appointment type | |
| date | Yes | Appointment date (YYYY-MM-DD) | |
| start_time | Yes | Start time (HH:MM) | |
| duration | No | Duration in minutes (optional) | |
| reason | No | Reason for visit (optional) | |
| notes | No | Appointment notes (optional) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It states 'Create a new appointment' which implies a write operation, but doesn't address permissions, side effects, error conditions, or what happens on success. This is inadequate for a mutation tool with zero annotation coverage.
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 directly states the tool's purpose without unnecessary words. It's appropriately sized and front-loaded with the essential 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 mutation tool with 9 parameters, no annotations, and no output schema, the description is insufficient. It doesn't explain what happens after creation, error handling, or how this differs from similar tools. The agent would need to guess about behavioral aspects and usage 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%, so the schema already documents all 9 parameters thoroughly. The description adds no additional parameter information beyond what's in the schema, meeting the baseline expectation but not providing 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 clearly states the verb 'Create' and the resource 'appointment for a patient', making the purpose specific and understandable. However, it doesn't differentiate from sibling tools like 'create_encounter' or 'check_appointment_availability', which could cause confusion in tool selection.
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 like 'create_encounter' or 'check_appointment_availability'. There's no mention of prerequisites, constraints, or typical use cases, leaving the agent without contextual usage information.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new encounter for a patient
| Name | Required | Description | Default |
|---|---|---|---|
| patient_id | Yes | Patient ID | |
| department_id | Yes | Department ID | |
| provider_id | No | Provider ID (optional) | |
| encounter_date | Yes | Encounter date (YYYY-MM-DD) | |
| encounter_type | No | Type of encounter (optional) | |
| chief_complaint | No | Chief complaint (optional) | |
| appointment_id | No | Associated appointment ID (optional) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. While 'Create' implies a write operation, it doesn't mention permission requirements, whether the encounter becomes immediately active, what happens on duplicate creation, or what the response contains. For a mutation tool with zero annotation coverage, this is inadequate.
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 states the core purpose without unnecessary words. It's appropriately sized for a tool with good schema documentation and gets straight to the point.
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 mutation tool with 7 parameters, no annotations, and no output schema, the description is insufficient. It doesn't explain what constitutes a successful creation, what data is returned, or how this tool relates to other encounter management tools in the sibling list. The schema handles parameter documentation, but behavioral context 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?
The schema description coverage is 100%, so all parameters are documented in the schema. The description adds no additional parameter information beyond what's already in the schema, maintaining the baseline score of 3 where the schema does the heavy lifting.
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 ('Create') and resource ('new encounter for a patient'), making the purpose immediately understandable. However, it doesn't differentiate from sibling tools like 'create_appointment' or 'create_patient' by specifying what makes an encounter distinct in this medical context.
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 like 'create_appointment' or 'update_encounter', nor does it mention prerequisites such as needing an existing patient record. It simply states what the tool does without contextual usage information.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Register a new patient in the system
| Name | Required | Description | Default |
|---|---|---|---|
| firstname | Yes | Patient first name | |
| lastname | Yes | Patient last name | |
| dob | Yes | Date of birth (MM/DD/YYYY or YYYY-MM-DD) | |
| sex | Yes | Sex (M or F) | |
| department_id | Yes | Primary department ID | |
| No | Email address (optional) | ||
| mobile_phone | No | Mobile phone number (optional) | |
| home_phone | No | Home phone number (optional) | |
| address1 | No | Street address (optional) | |
| city | No | City (optional) | |
| state | No | State (optional) | |
| zip | No | ZIP code (optional) | |
| guarantor_firstname | No | Guarantor first name (optional) | |
| guarantor_lastname | No | Guarantor last name (optional) | |
| guarantor_dob | No | Guarantor date of birth (optional) | |
| guarantor_relationship | No | Relationship to patient: 1=Self, 2=Spouse, 3=Child, 4=Other (optional) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. 'Register a new patient' implies a write operation, but it doesn't specify permissions required, whether duplicates are allowed, what happens on success (e.g., returns patient ID), or error handling. This is a significant gap for a mutation tool with 16 parameters.
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 with zero waste—'Register a new patient in the system' is front-loaded and directly conveys the core action. Every word earns its place, making it easy for an agent to parse quickly without unnecessary elaboration.
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 complex mutation tool with 16 parameters, no annotations, and no output schema, the description is inadequate. It doesn't explain what the tool returns (e.g., patient ID), error conditions, or dependencies like valid department_id. Given the richness needed for such a tool, this leaves major gaps in understanding.
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 all parameters well-documented in the schema (e.g., dob formats, optional fields, guarantor relationship codes). The description adds no additional parameter semantics beyond implying patient registration, so it meets the baseline of 3 where the schema does the heavy lifting.
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 ('Register') and resource ('new patient in the system'), making the purpose immediately understandable. It distinguishes from siblings like 'search_patients' or 'get_patient_encounters' by focusing on creation rather than retrieval. However, it doesn't specify what 'register' entails beyond creation, missing some nuance.
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 like 'search_patients' for existing patients or 'create_appointment' for scheduling. There's no mention of prerequisites, such as needing department_id from 'list_departments', or exclusions, leaving the agent to infer usage from context alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new prescription for a patient
| Name | Required | Description | Default |
|---|---|---|---|
| patient_id | Yes | Patient ID | |
| medication_name | Yes | Medication name | |
| dosage | Yes | Dosage (e.g., "10mg") | |
| route | Yes | Route of administration (e.g., "oral") | |
| frequency | Yes | Frequency (e.g., "twice daily") | |
| quantity | Yes | Quantity to dispense | |
| refills | Yes | Number of refills | |
| days_supply | Yes | Days supply | |
| pharmacy_id | No | Pharmacy ID (optional) | |
| notes | No | Additional notes (optional) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions 'Create' which implies a write operation, but fails to specify critical details like required permissions, whether it's idempotent, error handling, or what the response contains (e.g., prescription ID). This leaves significant gaps for an AI agent.
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 directly states the tool's purpose without any unnecessary words. It's front-loaded and wastes no space, making it easy for an AI agent to parse quickly.
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 10 parameters, no annotations, and no output schema, the description is insufficient. It doesn't explain behavioral aspects like side effects, authorization needs, or return values, leaving the AI agent with incomplete context for safe and effective 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?
The schema description coverage is 100%, with all parameters clearly documented in the schema itself (e.g., 'dosage' described as 'Dosage (e.g., "10mg")'). The description adds no additional parameter information beyond what's in the schema, so it meets the baseline score of 3 for high schema 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?
The description clearly states the verb ('Create') and resource ('a new prescription for a patient'), making the purpose immediately understandable. However, it doesn't differentiate from sibling tools like 'create_appointment' or 'create_patient' beyond the resource name, which is why it doesn't reach a score of 5.
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 like 'check_drug_interactions' or 'create_encounter', nor does it mention prerequisites such as needing an existing patient record. It simply states what the tool does without context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a comprehensive clinical summary for a patient
| Name | Required | Description | Default |
|---|---|---|---|
| patient_id | Yes | Patient ID | |
| include_allergies | No | Include allergies | |
| include_problems | No | Include problems | |
| include_prescriptions | No | Include prescriptions | |
| include_vitals | No | Include vitals | |
| include_labs | No | Include lab results | |
| include_alerts | No | Include clinical alerts |
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. While 'Get' implies a read-only operation, it doesn't specify authentication requirements, rate limits, error conditions, or what constitutes a 'comprehensive clinical summary' (e.g., format, data sources, or time range). For a tool with 7 parameters and no annotation coverage, this is a significant gap in transparency.
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 front-loads the core purpose ('Get a comprehensive clinical summary for a patient') with zero wasted words. It's appropriately sized for the tool's complexity, making it easy for an agent to parse quickly without unnecessary elaboration.
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 complexity (7 parameters, no output schema, and no annotations), the description is incomplete. It lacks details on behavioral aspects (e.g., permissions, errors), output format, or how parameter choices impact the summary. While schema coverage is high, the absence of annotations and output schema means the description should compensate more to guide effective tool 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 description coverage is 100%, with all parameters clearly documented in the input schema (e.g., 'patient_id' as Patient ID, booleans for including allergies, problems, etc.). The description adds no additional parameter semantics beyond what the schema provides, such as explaining how these inclusions affect the summary output. Baseline 3 is appropriate when the schema does the heavy lifting.
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 resource ('comprehensive clinical summary for a patient'), making the purpose specific and understandable. However, it doesn't explicitly differentiate this tool from sibling tools like 'get_encounter' or 'get_patient_encounters', which might also retrieve patient-related clinical data, leaving some ambiguity about scope boundaries.
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. It doesn't mention prerequisites (e.g., patient must exist), exclusions, or comparisons to sibling tools like 'get_encounter' or 'search_patients', leaving the agent to infer usage context solely from the tool name and parameters.
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 encounter
| Name | Required | Description | Default |
|---|---|---|---|
| encounter_id | Yes | Encounter ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states it 'gets details' but doesn't specify whether this is a read-only operation, what permissions are required, error handling, or response format. For a tool with zero annotation coverage, this leaves significant gaps in understanding how it behaves.
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 with zero waste. It's appropriately sized for a simple retrieval tool and front-loads the essential action. Every word earns its place without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and no output schema, the description is incomplete for a tool that likely returns detailed encounter data. It doesn't explain what 'details' include, potential errors, or response structure. For a healthcare context with siblings like 'get_clinical_summary', more context is needed to distinguish functionality.
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 schema already documents the 'encounter_id' parameter. The description adds no additional meaning beyond what the schema provides—it doesn't clarify format, source, or constraints for the ID. Baseline 3 is appropriate when the schema does the heavy lifting.
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 'details of a specific encounter', making the purpose unambiguous. It distinguishes from siblings like 'get_patient_encounters' (which lists multiple encounters) by specifying retrieval of a single encounter. However, it doesn't explicitly mention what details are included, which prevents a perfect score.
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. It doesn't mention prerequisites (e.g., needing an encounter ID), exclusions, or comparisons to siblings like 'get_clinical_summary' or 'get_patient_encounters'. The agent must infer usage from the name and context alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get all encounters for a patient
| Name | Required | Description | Default |
|---|---|---|---|
| patient_id | Yes | Patient ID | |
| department_id | No | Filter by department ID (optional) | |
| start_date | No | Start date filter (YYYY-MM-DD) (optional) | |
| end_date | No | End date filter (YYYY-MM-DD) (optional) | |
| status | No | Filter by status: OPEN, CLOSED, SIGNED (optional) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It states it 'gets' data (implying read-only), but doesn't address permissions needed, rate limits, pagination, error conditions, or what 'all encounters' means in practice (e.g., historical limits). For a tool with 5 parameters and no annotation coverage, this leaves significant behavioral 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?
The description is a single, clear sentence that efficiently conveys the core function. It's appropriately sized for a straightforward retrieval tool and front-loads the essential information. There's no wasted verbiage, though it could benefit from slightly more detail given the lack of 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?
For a tool with 5 parameters, no annotations, and no output schema, the description is inadequate. It doesn't explain what constitutes an 'encounter', the format or structure of returned data, pagination behavior, error handling, or authentication requirements. The description alone leaves too many operational questions unanswered for effective agent 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 description coverage is 100%, so all parameters are documented in the schema. The description adds no additional parameter semantics beyond implying filtering capability through 'for a patient'. It doesn't explain relationships between parameters (e.g., that department_id, dates, and status are filters applied to the patient's encounters) or provide usage examples. Baseline 3 is appropriate when schema does the heavy lifting.
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') and resource ('all encounters for a patient'), making the purpose immediately understandable. It distinguishes from siblings like 'get_encounter' (singular) and 'create_encounter', but doesn't explicitly differentiate from 'get_clinical_summary' which might include encounter data. The description is specific but could be more precise about scope.
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. It doesn't mention when to choose this over 'get_encounter' (singular), 'get_clinical_summary', or 'search_patients' which might retrieve similar data. There are no prerequisites, exclusions, or context about appropriate use cases beyond the basic function.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all departments in the practice
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but offers minimal behavioral insight. It implies a read operation ('List') but doesn't disclose permissions, rate limits, pagination, or return format. This is inadequate for a tool with zero annotation coverage.
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 with zero waste. It's front-loaded with the core action and resource, making it highly efficient and easy to parse.
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 no annotations, no output schema, and a simple list operation, the description is incomplete. It lacks details on return values (e.g., department fields), behavioral constraints, or integration context, leaving significant gaps for an agent to use it effectively.
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 0 parameters with 100% coverage, so no parameter documentation is needed. The description appropriately doesn't mention parameters, aligning with the schema. Baseline is 4 for zero parameters, as it avoids unnecessary details.
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') and resource ('all departments in the practice'), making the purpose unambiguous. However, it doesn't differentiate from sibling tools like 'list_providers' or 'search_patients' beyond the resource name, so it's not fully sibling-aware.
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. It doesn't mention prerequisites, context (e.g., for administrative tasks), or comparisons to siblings like 'list_providers' or 'search_patients', leaving usage entirely implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all healthcare providers in the practice
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of results | |
| name | No | Filter by provider name | |
| specialty | No | Filter by specialty |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states it's a list operation, implying read-only behavior, but doesn't cover aspects like pagination, rate limits, authentication needs, or what 'all' entails (e.g., active only, includes archived). This leaves significant gaps for a tool with parameters.
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, direct sentence that efficiently conveys the core purpose without any fluff or redundancy. It's appropriately sized and front-loaded, making it easy to parse quickly.
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 parameters and no output schema, the description is too minimal. It doesn't explain return values, filtering behavior, or how parameters interact (e.g., if 'name' and 'specialty' are combined). With no annotations and incomplete behavioral context, it falls short for effective agent 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?
The input schema has 100% description coverage, fully documenting the three parameters (limit, name, specialty) with clear descriptions. The tool description adds no additional parameter information beyond what the schema provides, so it meets the baseline for high schema 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?
The description clearly states the action ('List') and resource ('healthcare providers in the practice'), making the purpose immediately understandable. However, it doesn't distinguish this tool from potential sibling tools like 'list_departments' or 'search_patients' that might also list entities, missing full 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 provides no guidance on when to use this tool versus alternatives like 'search_patients' or 'list_departments', nor does it mention any prerequisites or exclusions. It's a basic statement of function without contextual usage advice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for patients by name, DOB, phone, or email
| Name | Required | Description | Default |
|---|---|---|---|
| firstname | No | Patient first name | |
| lastname | No | Patient last name | |
| dob | No | Date of birth (YYYY-MM-DD) | |
| phone | No | Phone number | |
| No | Email address | ||
| limit | No | Maximum number of results |
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 states the tool searches but doesn't clarify if it's read-only, requires authentication, has rate limits, returns partial matches, or handles errors. For a search tool with zero annotation coverage, this leaves critical 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, efficient sentence that front-loads the core functionality. It wastes no words and directly communicates the tool's purpose without redundancy or fluff, making it easy for an agent to parse quickly.
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 moderate complexity (6 parameters, no output schema, no annotations), the description is adequate but incomplete. It covers the basic search scope but lacks details on behavioral traits, usage context, and output expectations. This leaves gaps that could hinder an agent's effective 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 description coverage is 100%, with each parameter clearly documented in the input schema. The description adds minimal value by listing searchable fields (name, DOB, phone, email) but doesn't explain parameter interactions, optionality, or the 'limit' parameter. Baseline 3 is appropriate since the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Search for patients by name, DOB, phone, or email.' It specifies the verb ('search') and resource ('patients'), and lists searchable fields. However, it doesn't explicitly distinguish this from potential sibling search tools (though none exist in the provided list), keeping it from a perfect score.
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. It doesn't mention prerequisites, limitations, or how it compares to other patient-related tools like 'get_patient_encounters' or 'create_patient'. Without such context, an agent might struggle to choose appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing encounter
| Name | Required | Description | Default |
|---|---|---|---|
| encounter_id | Yes | Encounter ID | |
| chief_complaint | No | Chief complaint (optional) | |
| diagnosis_codes | No | Comma-separated ICD-10 diagnosis codes (optional) | |
| procedure_codes | No | Comma-separated CPT procedure codes (optional) | |
| status | No | Status: OPEN, CLOSED, SIGNED (optional) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states 'update' implies a mutation, but it doesn't disclose critical traits like required permissions, whether changes are reversible, side effects, or response format. For a mutation tool with zero annotation coverage, this leaves significant gaps in understanding its behavior.
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—a single, clear sentence with no wasted words. It's front-loaded with the core action, making it easy to parse quickly. This efficiency is ideal for a tool name that already implies its function.
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 complexity of a mutation tool with no annotations and no output schema, the description is incomplete. It doesn't address behavioral aspects like permissions, side effects, or return values, which are crucial for safe and effective use. The high schema coverage helps with 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 description coverage is 100%, so the input schema fully documents all parameters (encounter_id, chief_complaint, diagnosis_codes, procedure_codes, status). The description adds no additional meaning beyond what's in the schema, such as explaining parameter interactions or constraints. Baseline 3 is appropriate when the schema does the heavy lifting.
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 'Update an existing encounter' clearly states the action (update) and resource (encounter), but it's quite generic. It doesn't specify what aspects can be updated or differentiate it from sibling tools like 'get_encounter' or 'create_encounter' beyond the basic verb. While it's not tautological, it lacks the specificity needed for a higher score.
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. It doesn't mention prerequisites (e.g., needing an existing encounter ID), exclusions, or comparisons to siblings like 'create_encounter' or 'get_encounter'. Without such context, users must infer usage from the name alone, which is insufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Each tool has a clearly distinct purpose targeting specific resources and actions in the healthcare domain, such as patient management, appointments, clinical alerts, and prescriptions. There is no significant overlap; for example, create_appointment and check_appointment_availability serve different functions, and get_encounter vs. get_patient_encounters are clearly differentiated by scope.
All tool names follow a consistent verb_noun pattern using snake_case, such as acknowledge_alert, create_appointment, and list_departments. This uniformity makes the tool set predictable and easy for an agent to navigate without confusion from mixed naming conventions.
With 14 tools, the server is well-scoped for a healthcare practice management system, covering essential operations like patient registration, appointment scheduling, clinical workflows, and data retrieval. Each tool appears necessary for the domain, avoiding bloat or thin coverage.
The tool set provides strong coverage for core healthcare workflows, including patient CRUD (create, search), appointment management, clinical encounters, and prescriptions. A minor gap exists in update/delete operations for resources like patients or prescriptions, but agents can likely work around this with the available tools.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Physician-reviewed medical opinions and prescriptions for AI agents.
HIPAA compliance AI agent — scan, grade, SRA, and generate compliance docs.
Guardrailed FHIR access for AI agents: PHI redaction, audit trail, step-up auth, tenant isolation
Your MedNode health vault in your AI assistant — records, summaries, labs, appointments.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/ophydami/Athenahealth-MCP'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
