Optional Gmail integration for sending welcome and notification emails to employees and managers using a Gmail account with app password.
Click on "Deploy 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., "@HR Assist MCP Server Onboard a new employee named Riya reporting to Sarah Johnson"
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.
Agentic HR assistant that exposes employee, leave, meeting, ticket, and email tools over the Model Context Protocol (MCP). Designed to automate onboarding workflows via an MCP client such as Claude Desktop.
Use these when creating a new employee (manager_id can be ID or name):
ID | Name | Role | Department |
E001 | Sarah Johnson | VP Engineering | Engineering |
E002 | Michael Chen | VP Product | Product |
E003 | David Wilson | Engineering Manager | Engineering |
E006 | Emily Kim | Product Manager | Product |
E009 | Priya Nair | HR Manager | HR |
Other sample staff: Tony Sharma (E004), James Rodriguez (E005), Carlos Mendez (E007), Lisa Wong (E008), Aisha Khan (E010), Rohan Mehta (E011), Neha Kapoor (E012).
Examples:
add_employee("Riya Shah", manager_id="E001", email="riya.shah@atliq.com")
add_employee("Riya Shah", manager_id="Sarah Johnson")
add_employee("Riya Shah") # defaults manager to E001Call list_managers or list_employees tools to see the full directory.
Related MCP server: HR-ASSIST
Add / look up employees
Leave balance, apply leave, leave history
Schedule / list / cancel meetings
Create and manage IT/HR tickets
Optional Gmail sending for welcome / manager notifications
Built-in onboarding prompt: onboard_new_employee
Install uv (recommended) or use pip.
From this directory:
uv syncOr with pip:
python -m venv .venv
.venv\Scripts\activate
pip install -e .Copy env values:
copy sample.env .envOptional (for real email):
CB_EMAIL=your@gmail.com
CB_EMAIL_PWD=your_gmail_app_passwordLeave blank to run without email (send_email will skip and report what it would send).
uv sync
uv run streamlit run streamlit_app.pyOpens at http://localhost:8501 with tabs for Directory, Onboard, Leave, Tickets, Meetings, Email, and Lookup.
Local .env:
CB_EMAIL=yourgmail@gmail.com
CB_EMAIL_PWD=your_16_char_app_passwordStreamlit Cloud → Settings → Secrets:
CB_EMAIL = "yourgmail@gmail.com"
CB_EMAIL_PWD = "your_16_char_app_password"Use a Gmail App Password (not your normal password).
Push this folder to a GitHub repo (include streamlit_app.py and requirements.txt).
Go to share.streamlit.io → New app.
Select the repo, set Main file path to streamlit_app.py.
Deploy. You’ll get a public URL like https://your-app.streamlit.app.
uv run python run_local.pyThis seeds dummy HR data and runs an onboarding-style flow through the same managers used by the MCP tools.
uv run python server.pystdio transport waits for an MCP client. To inspect tools interactively:
npx @modelcontextprotocol/inspector uv run python server.pyEdit Claude Desktop claude_desktop_config.json and point command / --directory at this project folder:
{
"mcpServers": {
"hr-assist": {
"command": "uv",
"args": [
"--directory",
"C:\\Users\\omkar\\Documents\\Project\\AI\\HR Assist (MCP Server)",
"run",
"python",
"server.py"
],
"env": {
"CB_EMAIL": "YOUR_EMAIL",
"CB_EMAIL_PWD": "YOUR_APP_PASSWORD"
}
}
}
}In Claude Desktop, use the onboard_new_employee prompt or ask naturally, for example:
Onboard a new employee named Riya reporting to Sarah Johnson
What is Tony Sharma's leave balance?
Create a laptop ticket for E009
server.py MCP tools + onboarding prompt
run_local.py Local demo without MCP client
emails.py SMTP helper
utils.py Dummy data seeder
hrms/ Employee, leave, meeting, ticket managers + schemasAdd a new employee to the HRMS system.
:param emp_name: New employee full name :param manager_id: Manager employee ID OR manager name. Examples: "E001", "Sarah Johnson", "David Wilson". Defaults to E001 (Sarah Johnson) if omitted. :param email: Employee email. If empty, auto-generated as name@atliq.com :return: Confirmation message with new employee ID
| Name | Required | Description | Default |
|---|---|---|---|
| No | |||
| emp_name | Yes | ||
| manager_id | No | E001 |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries full burden. It discloses auto-generation of email, default values for manager_id, and acceptable formats. However, it lacks details on permissions, error handling, or 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 concise and well-structured, with a clear purpose sentence followed by parameter documentation and return value. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers basic functionality, parameter semantics, and return value. However, it lacks information on error conditions, prerequisites (e.g., manager existence), or any constraints (e.g., duplicate names), leaving gaps for a mutation 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?
Schema description coverage is 0%, but the description fully compensates by providing clear descriptions for each parameter, including examples for manager_id and auto-generation rule for email. This adds significant meaning beyond the schema's type/default.
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 'Add a new employee to the HRMS system,' specifying the action (add) and the resource (employee). It distinguishes from sibling tools like list_employees and get_employee_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 is given on when to use this tool versus alternatives like create_ticket or when not to use it. The description only states the action 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.
Apply for leave for an employee. :param emp_id: Employee ID :param leave_dates: List of leave dates :return: Leave application status message
| Name | Required | Description | Default |
|---|---|---|---|
| emp_id | Yes | ||
| leave_dates | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description alone must disclose behavioral traits. It only states the action and return value, without mentioning whether the operation checks leave balance, requires permissions, is reversible, or triggers notifications. For a mutation tool, this lacks necessary behavioral 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 extremely concise, front-loading the purpose in the first sentence and adding param documentation without any fluff. Every sentence earns its place, and the structure is clear and scannable.
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 tool with two parameters and an output schema, the description covers purpose, parameters, and return value adequately. However, it lacks context about practical usage, such as prerequisites (e.g., sufficient leave balance) or side effects, but given the tool's simplicity and existing output schema, this is acceptable.
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 description provides :param lines for both parameters, adding semantics to the otherwise empty schema descriptions. 'Employee ID' and 'List of leave dates' clarify the parameters' meanings, though the format of dates (e.g., date range vs individual dates) is not specified. This partly compensates for the 0% 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 states 'Apply for leave for an employee' clearly, specifying the verb (apply) and resource (leave) with a target (employee). It is unambiguous and distinct from all sibling tools, including leave balance and history queries, which serve different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied from the purpose: this is the tool to apply for leave. However, no explicit guidance is given about when to use it versus checking leave balance first or any approval workflow. Alternatives are not mentioned, and no exclusions are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Cancel a scheduled meeting for an employee. :param employee_id: Employee ID :param meeting_datetime: Date and time of the meeting in python datetime format :param topic: Topic of the meeting (optional) :return: Confirmation message
| Name | Required | Description | Default |
|---|---|---|---|
| topic | Yes | ||
| employee_id | Yes | ||
| meeting_datetime | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of disclosing behavioral traits. It mentions that a confirmation message is returned, but does not disclose side effects (e.g., whether participants are notified, whether the cancellation is permanent), permission requirements, or error handling. 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 concise: a single sentence followed by parameter docstrings. It is front-loaded with the primary action and includes no fluff. The structure is readable and efficient, though the docstring style could be more integrated.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values don't need explanation. However, the description lacks context about prerequisites (e.g., meeting must exist), behavior when the meeting is not found, and the contradictory 'optional' topic flag introduces ambiguity. For a cancellation tool with no annotations, 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 description adds some meaning to parameters (e.g., employee_id, meeting_datetime format, topic optional), which helps given the schema has 0% description coverage. However, it directly contradicts the schema by marking 'topic' as optional while the schema lists it as required. This misleading information undermines the value of the parameter documentation.
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 ('Cancel a scheduled meeting') and the target resource ('an employee'), making it distinct from sibling tools like schedule_meeting and get_meetings. The verb+resource combination is specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives (e.g., schedule_meeting, get_meetings). It lacks any explicit conditions, prerequisites, or exclusions, leaving the agent to infer usage solely from the tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a ticket for buying required items for an employee. :param emp_id: Employee ID :param item: Item requested (Laptop, ID Card, etc.) :param reason: Reason for the request :return: Confirmation message
| Name | Required | Description | Default |
|---|---|---|---|
| item | Yes | ||
| emp_id | Yes | ||
| reason | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
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 only mentions creating a ticket and returning a confirmation message, but does not disclose side effects, permissions, reversibility, or any other behavioral traits. For a mutation operation, 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 concise and front-loaded with the main purpose in the first sentence. The parameter documentation is clear and directly follows the purpose, with no unnecessary content. It efficiently conveys all essential information in four short statements.
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 ticket-creation tool, the description covers the primary purpose, all parameters, and the return type (confirmation message). It also provides examples for the item field. However, it lacks mention of prerequisites (e.g., employee must exist) or error conditions, but the simplicity of the tool makes these omissions minor.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has no descriptions for its parameters (0% coverage), so the description must compensate. It does so thoroughly by providing meanings for all three parameters: emp_id (Employee ID), item (Item requested with examples), and reason (Reason for the request). This fully clarifies the required inputs.
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 'Create a ticket for buying required items for an employee,' which uses a specific verb ('create') and resource ('ticket') with a clear purpose. This differentiates it from sibling tools like update_ticket_status and list_tickets, which handle other ticket operations.
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 the use case (creating a ticket for employee purchases) but does not explicitly state when to use this tool versus alternatives. There are no exclusions or comparisons with sibling tools like list_tickets or update_ticket_status, so the usage guidance is only implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get employee details by name (or partial name). :param name: Name of the employee, e.g. "Tony" or "Sarah Johnson" :return: Employee details
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. Description only states 'Get employee details' without specifying what details are returned, whether it's case-sensitive, or behavior on no match. Output schema exists but description doesn't reference it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Very short and front-loaded. Two lines cover purpose and parameter. However, docstring style adds a bit of redundancy with the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one param and an output schema, the description is adequate but not thorough. Missing behavioral context like null returns or fuzzy matching. Siblings like list_employees hint at a different use case.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%. Description adds meaning by explaining the 'name' parameter as employee name (full or partial) with examples, but lacks details on matching rules or format.
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 verb 'Get', resource 'employee details', and specifies searching by name or partial name. This distinguishes it from siblings like list_employees (which lists all) and add_employee.
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?
Implies use when you have a name/partial name to look up, but lacks explicit guidance on when not to use (e.g., comparing with list_employees) or prerequisites. No alternatives mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the leave balance of an employee. :param emp_id: Employee ID :return: Leave balance message
| Name | Required | Description | Default |
|---|---|---|---|
| emp_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
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 only states that the tool returns a 'leave balance message', which is vague and does not clarify side effects, error behavior, permission requirements, or whether the result is structured or plain text. The verb 'get' implies read-only, but the description does not explicitly confirm this or provide any additional 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 highly concise and well-structured. It uses a single sentence to describe the action, followed by explicit :param and :return lines for the important contract points. There is no fluff, and the information is front-loaded in the opening sentence.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple, but the description has clear gaps: it does not explain when to use it over 'get_leave_history', does not describe the exact return format beyond 'message', and gives no behavioral details. Given the missing annotations and zero schema coverage, the description is minimally adequate but lacks the context needed for an agent to reliably distinguish and invoke this tool in all scenarios.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. The :param line clarifies that 'emp_id' stands for 'Employee ID', which adds slight meaning beyond the schema's property name and title. However, it does not specify the format or constraints for the ID, and it is nearly redundant with the parameter name. The compensation is minimal but 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 clearly states the tool's function: 'Get the leave balance of an employee.' It uses a specific verb ('get') and resource ('leave balance') and distinguishes from siblings like 'get_leave_history' which covers historical records, not current balance. The :param and :return lines further clarify the tool's 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?
There is no guidance on when to use this tool versus alternatives like 'get_leave_history' or 'apply_leave'. The description does not mention prerequisites, exclusions, or any preference for which sibling to choose. The only context is the name and a basic description, leaving the agent to infer from the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the leave history of an employee. :param emp_id: Employee ID :return: Leave history message
| Name | Required | Description | Default |
|---|---|---|---|
| emp_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
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 only indicates a read operation ('get') but does not specify the scope of history (e.g., date range, statuses), any side effects, required permissions, or the exact return structure beyond a vague 'Leave history message.' No additional behavioral traits are disclosed.
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 concise, with the main purpose front-loaded in the first sentence. However, the ':return: Leave history message' line is vague and adds little value, making it somewhat less effective than it could be. Overall, it is not overly verbose and maintains a clear structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple, but the description lacks completeness by not explaining what 'leave history' includes or how it differs from the sibling tool get_employee_leave_balance. No behavior beyond the basic action is described, and the vague return statement does not help. Given no annotations and no output schema visible, more context is needed for a confident invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% coverage for parameter descriptions, so the description must compensate. The ':param emp_id: Employee ID' line provides a basic definition but adds little beyond the parameter name itself. It does not detail the format, constraints, or how emp_id relates to the leave history query, but for a single simple parameter, it is minimally sufficient.
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 the leave history of an employee' with a specific verb and resource, distinguishing it from sibling tools like get_employee_leave_balance (which focuses on balance) and apply_leave. The purpose is unambiguous and immediately understandable.
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 does not mention that leave history differs from leave balance, nor does it explain any context or exclusions. The agent is left to infer usage solely from the tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the list of meetings scheduled for an employee. :param employee_id: Employee ID :return: List of meetings
| Name | Required | Description | Default |
|---|---|---|---|
| employee_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description must carry the behavioral transparency burden. However, it only states the basic action and return type, without disclosing any behavioral traits such as whether cancelled meetings are excluded, ordering, pagination, or required permissions. This leaves the agent guessing about important operational details.
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 concise and front-loaded with the primary purpose in the first sentence. It follows a standard docstring style with ':param' and ':return' lines that are brief and conventional. There is no wasted content or 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?
The tool is straightforward with a single parameter and an output schema (not shown, but indicated), which reduces the need for descriptions of return values. However, the lack of usage guidelines and behavioral transparency makes the description only minimally adequate for reliable agent decision-making.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has a single parameter 'employee_id' with no description (coverage 0%). The description merely repeats the parameter name as 'Employee ID' without adding format, constraints, or examples. It does not meaningfully compensate for the lack of schema documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Get the list of meetings scheduled for an employee.' This uses a specific verb ('Get') and resource ('list of meetings') with a defined scope (per employee). It distinguishes itself from siblings like 'schedule_meeting' and 'cancel_meeting' by indicating it is a read-only retrieval operation.
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 by stating its purpose, but it does not explicitly say when to use this tool versus alternatives, nor does it mention any exclusions or prerequisites. For example, there is no note about whether to use this for future meetings only or for historical ones, and no mention of alternatives like 'schedule_meeting'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all sample employees with IDs, roles, departments, and managers. Use this before creating a new employee so you know valid manager IDs/names.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must cover behavior. It states it lists all sample employees, which is transparent. However, it doesn't disclose potential limitations (e.g., pagination) or that it's a read-only operation. But for a simple list with no parameters, this is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: one for purpose, one for usage. Every word earns its place. No unnecessary 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?
Given zero parameters and an output schema exists, the description is largely complete. It covers purpose and usage. However, it could briefly mention the output format or refer to the schema for return details. Siblings like list_managers suggest a subtle distinction not addressed.
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 zero parameters, so schema description coverage is 100%. The description adds value by specifying the fields returned (IDs, roles, departments, managers), which is not in the schema. This compensates for the lack of parameter 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?
Description explicitly states it lists all sample employees with specific fields (IDs, roles, departments, managers). This clearly distinguishes from siblings like list_managers and get_employee_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?
Explicitly advises using the tool before creating an employee to get valid manager IDs/names. While it doesn't explicitly list when not to use, the provided context is helpful. Missing exclusion of alternatives like list_managers.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List managers you can assign when creating a new employee. Preferred manager IDs: E001 (Sarah Johnson), E002 (Michael Chen), E003 (David Wilson), E006 (Emily Kim), E009 (Priya Nair).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description adds value by listing preferred manager IDs and names, but doesn't disclose authentication requirements or whether list is exhaustive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded purpose, no fluff. 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 list tool with output schema present, description adequately conveys expected return values. Could optionally mention output structure, but output schema fills gap.
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; schema coverage 100% trivially. Description adds concrete manager names and IDs, exceeding baseline of 4 for zero-parameter tools.
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 verb 'list' and resource 'managers', with specific context 'when creating a new employee'. Distinguished from sibling list_employees by 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?
Explicitly says when to use (assigning a manager during employee creation), providing clear context without explicit exclusions or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List tickets for an employee with optional status filter. :param employee_id: Employee ID (optional) :param status: Ticket status (optional) :return: List of tickets
| Name | Required | Description | Default |
|---|---|---|---|
| status | No | ||
| employee_id | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must carry the burden. It implies read-only listing but does not confirm safety, mention pagination, or disclose any side effects. The return type is noted but not detailed.
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 short and to the point, with a clear sentence for purpose and a docstring for parameters. However, the docstring repeats schema information without adding significant value, making it slightly redundant.
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?
Minimal for a simple list tool: covers purpose and param names, but lacks context on scope (all vs employee tickets), pagination, ordering, or differentiation from other list siblings. Output schema exists, so return details are not needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description adds some value by labeling parameters and marking them optional, but it only repeats the name and optionality. No values, formats, or constraints are provided for status or employee_id.
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 the verb 'list' and resource 'tickets', but is vague about the scope: 'for an employee' with an optional employee_id implies either all tickets or a filtered set. It distinguishes from create/update siblings but not from other list tools like list_employees.
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 vs alternatives. The name and basic purpose suggest listing tickets, but no differentiation from list_employees or list_managers, and no prerequisites for effective use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Schedule a meeting for an employee. :param employee_id: Employee ID :param meeting_datetime: Date and time of the meeting in python datetime format :param topic: Topic of the meeting :return: Confirmation message
| Name | Required | Description | Default |
|---|---|---|---|
| topic | Yes | ||
| employee_id | Yes | ||
| meeting_datetime | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
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 only states that a meeting is scheduled and a confirmation message is returned, but omits important details like conflict handling, validation of employee_id, timezone assumptions, or whether any notifications are sent. This could lead to misuse or unexpected 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 concise and front-loaded with the main action, followed by a compact parameter list and return note. No wasted sentences; every element serves a purpose.
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 tool with 3 required string parameters, the description covers the basic parameters and return type, but lacks critical behavioral context such as meeting conflict resolution, employee validation, and timezone handling. The presence of an output schema partially covers return details, but the absence of annotations and behavioral clarifications leaves 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?
The description includes :param lines that explain each parameter, adding 'python datetime format' for meeting_datetime which is helpful. However, most explanations are redundant with property titles, and with 0% schema coverage, the description only partially compensates. It doesn't clarify constraints like required formats or uniqueness.
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 'Schedule a meeting for an employee' uses a specific verb and resource, clearly distinguishing it from sibling tools like 'cancel_meeting', 'get_meetings', and 'apply_leave'. No ambiguity about the tool's primary action.
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 purpose statement gives clear context that this tool is for creating meetings, and the sibling tools provide implicit alternatives (cancel, view, etc.). It doesn't explicitly mention when not to use it or name alternatives, but the context is strong enough for an agent to select it appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
| Name | Required | Description | Default |
|---|---|---|---|
| body | Yes | ||
| html | No | ||
| subject | Yes | ||
| to_emails | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
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?
Tool has no description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has no description.
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?
Tool has no description.
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?
Tool has no description.
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?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update the status of a ticket. :param ticket_id: Ticket ID :param status: New status of the ticket :return: Confirmation message
| Name | Required | Description | Default |
|---|---|---|---|
| status | Yes | ||
| ticket_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must carry the burden of behavioral disclosure. It only states the action and return value ('Confirmation message') but does not mention permissions, side effects, error handling, or valid status transitions. 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 very short and front-loaded, with a clear one-sentence purpose statement and structured param docs. However, the param lines add little value beyond the schema, making some parts redundant.
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 update operation, the description covers the basic action and return, but lacks critical context such as valid status values, potential errors, or prerequisites. The presence of an output schema does not compensate for the missing behavioral and usage guidance.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. The param lines ':param ticket_id: Ticket ID' and ':param status: New status of the ticket' are nearly tautological and provide no extra context about allowed values, formats, or constraints.
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 'Update the status of a ticket,' which is a specific verb+resource phrase that clearly identifies the action. It distinguishes itself from sibling tools like create_ticket and list_tickets by focusing on status modification.
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?
There is no explicit guidance on when to use this tool or how it differs from alternatives. Usage is implied by the name and action, but no exclusions or alternative tool references are provided.
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.
v0.1.0add_employeeapply_leavecancel_meetingcreate_ticketget_employee_detailsget_employee_leave_balanceget_leave_historyget_meetingslist_employeeslist_managerslist_ticketsschedule_meetingsend_emailupdate_ticket_statusScored across 14 tools
Each tool targets a distinct function (employee, ticket, meeting, leave, email) with clear boundaries. Even send_email, despite lacking a description, is presumably for email sending and doesn't overlap with others.
Tools follow verb_noun snake_case consistently, like create_ticket, list_employees, schedule_meeting. Minor inconsistency: get_employee_leave_balance vs get_leave_history, and list_tickets vs get_meetings, but overall pattern is clear.
14 tools cover employee management, ticketing, meetings, and leave—reasonable for an HR assist server. Not too many or too few.
Covers core HR operations: CRUD for employees (add, get, list), ticketing, meetings, and leave. Missing update/delete for employees, but the set is functional for common tasks.
Build and manage AI-native customer support agents from Claude or any MCP client.
An agent-first office suite Claude & ChatGPT read and write over one MCP URL.
One MCP endpoint for Claude, GPT & Gemini: 100+ tools + no-code connectors + agent workers.
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
