Allows sending emails over SMTP using a Gmail App Password, enabling HR workflows such as onboarding notifications and employee communication.
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 Onboard Jane Doe as a Software Engineer starting 2025-01-06."
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.
HR-ASSIST automates routine HR workflows, mainly employee onboarding: adding the employee, sending emails, raising equipment tickets and scheduling the first meeting.
This repo is the MCP server. Claude Desktop is the MCP client that calls its tools.
Employee management (add, search, manager lookup)
Leave management (balance, apply, history)
Meeting scheduling with conflict detection
Equipment ticketing
Email sending over SMTP
Ready-made onboard_new_employee prompt
Related MCP server: hr-assist
Install dependencies:
uv syncCopy sample.env to .env and fill in your details:
CB_EMAIL=YOUR_EMAIL
CB_EMAIL_PWD=YOUR_APP_PASSWORDUse a Gmail App Password, not your normal password. Never commit .env.
Add this to claude_desktop_config.json (Claude Desktop → Settings → Developer → Edit Config):
{
"mcpServers": {
"hr-assist": {
"command": "C:\\Users\\<your-username>\\.local\\bin\\uv.exe",
"args": [
"--directory",
"C:\\path\\to\\HR-ASSIST_Agentic_AI_System",
"run",
"server.py"
],
"env": {
"CB_EMAIL": "YOUR_EMAIL",
"CB_EMAIL_PWD": "YOUR_APP_PASSWORD"
}
}
}
}Restart Claude Desktop.
Click the + icon and select Add from hr-assist.
Choose onboard_new_employee, fill in the details and send.
You can also write your own prompt, for example "Apply leave for E004 on 2025-12-25", and the agent will pick the right tools.
Data is stored in memory and re-seeded with dummy data on every start (see utils.py).
Add a new employee to the HRMS system.
:param emp_name: Full name of the new employee
:param email: Email address of the new employee
:param manager_id: Employee ID of the manager, e.g. "E003" (optional; use get_employee_details to find it)
:return: Confirmation message that includes the new employee ID
| Name | Required | Description | Default |
|---|---|---|---|
| Yes | |||
| emp_name | Yes | ||
| manager_id | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the behavioral burden; it does disclose the outcome (a confirmation message containing the new employee ID), which is useful. It says nothing about required permissions, validation failures (e.g. duplicate email), or whether the write is reversible — meaningful gaps 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 purpose statement is front-loaded and each :param line adds real information rather than restating the field name. The docstring markup is marginally verbose, but no sentence is waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, making the :return line somewhat redundant, and the remaining space is not used for error behavior or prerequisites. For a simple three-parameter create, the essentials are present but a reader still doesn't know what happens on failure or duplicate input.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description has to compensate and largely does: it explains emp_name as full name, email as the employee's address, and manager_id as an employee ID with a concrete example ("E003") plus an explicit note that it is optional and where to find it. Only minor gaps remain (no email format or uniqueness 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?
States a specific verb and resource — "Add a new employee to the HRMS system" — which is unmistakable against siblings like get_employee_details or update_ticket_status. No sibling performs an equivalent insert, so differentiation is implicit rather than stated, which keeps it just below a 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?
Usage is implied by the verb and the single routing hint: it points the agent to get_employee_details to obtain the manager ID. There is no explicit statement of when to use this tool versus alternatives, nor any prerequisite or duplicate-handling guidance.
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 in YYYY-MM-DD format
: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 carries the full behavioral burden, and it discloses almost nothing: it does not say whether the application is auto-approved or pending, whether it fails when balance is insufficient, whether duplicate or overlapping dates are rejected, or whether the write is reversible. The only signal is the bare word "Apply", which implies mutation but describes none of its consequences.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
It is short, but it is an unedited docstring dump with ':param:'/':return:' markup rather than prose written for an agent. The ':return:' line is wasted space because an output schema already exists, and the useful format detail is buried mid-line after a near-tautological param gloss.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, omitting return detail is fine, but this is a mutation tool with zero annotations and only two lines of description. Key context an agent needs—approval behavior, balance validation, date-range rules, error conditions—is absent, leaving the definition too thin for a write operation.
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, and it partially does by specifying the YYYY-MM-DD format for leave_dates and giving an example date. The emp_id entry just restates "Employee ID" with no format or source, and no constraints (must the list be contiguous? sorted? max length?) are added.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ("Apply for leave for an employee") so the agent can tell this is the write counterpart to the read-only siblings get_employee_leave_balance and get_leave_history. It does not explicitly name those siblings as alternatives, so sibling differentiation is only implied by name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no when-to-use guidance, no prerequisites, and no mention of the adjacent tools. An agent is never told to check get_employee_leave_balance first or how this relates to get_leave_history; usage must be inferred entirely 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.
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 | No | ||
| employee_id | Yes | ||
| meeting_datetime | 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 carries the full behavioral burden. It says nothing about irreversibility of the cancellation, required permissions, behavior when the meeting is not found or when multiple meetings match, or how the optional topic disambiguates. Only the return value ('Confirmation message') is 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 lead sentence is well front-loaded, but the raw ':param'/':return' Sphinx syntax is machine-unfriendly boilerplate that largely restates schema fields rather than adding meaning. It is short, but a chunk of it does not earn its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return-value explanation is not needed, and all three parameters are at least named. Still, for an unannotated destructive mutation the description omits failure modes and safety context, leaving gaps an agent would want before invoking it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the docstring lines are the only parameter documentation. They cover all three parameters, but 'employee_id: Employee ID' is a tautology and 'python datetime format' only marginally extends the schema's format: date-time; the topic parameter's disambiguation role is left unexplained.
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 opening sentence gives a specific verb and resource ('Cancel a scheduled meeting for an employee'), so the intent is unmistakable. It does not, however, distinguish this from siblings like schedule_meeting or get_meetings, which share the same meeting domain.
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 versus schedule_meeting or get_meetings, nor any prerequisites (e.g., must the meeting exist, must it be in the future). The agent must infer usage entirely from the one-line purpose.
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?
No annotations are provided, so the description carries the full behavioral burden. It only mentions that a confirmation message is returned; it says nothing about required permissions, whether the ticket can be modified or cancelled afterward, or any side effects on the employee record.
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?
Short and front-loaded, with the core purpose in the first sentence. The Sphinx-style :param: lines partially duplicate the schema but are justified given the 0% schema coverage.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need not be explained. Parameters are minimally covered, but for a mutation tool with no annotations the description leaves behavioral gaps (permissions, reversibility, downstream effects on the ticket lifecycle).
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's param notes are the only semantics available, and they do add value — especially 'item' with examples like Laptop and ID Card. However, emp_id and reason are restated almost verbatim from their titles, so the added meaning is thin.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Create a ticket') plus the domain scope ('for buying required items for an employee'). It does not differentiate from siblings like list_tickets or update_ticket_status, but the creation intent is 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?
No guidance on when to use this versus list_tickets or update_ticket_status, and no prerequisites (e.g., must the employee already exist). Usage must be inferred purely from the purpose statement.
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 employee ID (e.g. "E003") or by name (full or partial).
:param name: Employee ID or name of the employee
:return: emp_id, name, manager_id (None if the employee has no manager) and email
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden, and it does disclose the return shape including the manager_id = None case, plus that name matching can be partial. It omits what happens on ambiguous partial matches (multiple hits?), what happens when nothing matches, and any auth/scope requirements, which matters for a lookup with fuzzy matching.
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 short lines, front-loaded with the verb and lookup modes, no filler. The reST :param:/:return: markup is slightly noisy for a one-parameter tool but the content is informative rather than padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values needn't be explained, yet the description still adds the useful None-manager detail. What's missing for a fuzzy-matching lookup is the ambiguity/not-found behavior and result cardinality, which an agent needs to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and the schema says only "Name: string", so the description does real work: it defines the single parameter as either an employee ID (with the "E003" format example) or a name, and allows partial name matching. It doesn't say how partial matches are resolved, which keeps it from a 5.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ("Get employee details") and both lookup keys (employee ID or name, full or partial), which separates it from add_employee and the leave-balance/history siblings. It does not explicitly name a sibling or state a boundary, so it stops short of a 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?
Usage is only implied by the wording — an agent can infer this is the lookup tool for employee records, but there is no explicit when-to-use/when-not guidance relative to siblings like get_employee_leave_balance or add_employee, and no prerequisites (e.g. permissions, whether the employee must exist).
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?
No annotations are provided, so the description must carry the full behavioral burden. It does not disclose permissions, rate limits, data freshness, or whether the operation is read-only, beyond the weak implication from the verb 'Get'. The ':return:' line mentions a message but adds no 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 short, front-loaded with the main purpose, and free of filler. The docstring-style ':param' and ':return' lines are compact, though somewhat redundant given the input and output schemas.
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 getter with one parameter and an output schema, the description covers the basic purpose, parameter meaning, and return nature. However, it omits usage guidance and behavioral details, and the parameter documentation is minimal, leaving gaps in a no-annotation 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 0%, and the only parameter description is ':param emp_id: Employee ID', which merely restates the schema title 'Emp Id' without adding format, source, or validation details. With low coverage, the description fails to compensate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Get') and resource ('leave balance of an employee'), which clearly distinguishes it from siblings like apply_leave and get_leave_history. However, it does not explicitly name or contrast with those alternatives, so it falls short of a 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 gives no guidance on when to use this tool versus alternatives such as get_leave_history or apply_leave. It only states what the tool does, with no context or exclusions.
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?
No annotations are provided, so the description carries the full behavioral burden. It does not say whether this is a read-only query, what the history includes (leave types, date ranges, statuses), whether it is scoped to the current user or requires elevated permissions, or how results are ordered. The 'read' nature is only implied by the verb 'Get'.
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 core sentence is front-loaded and short, but the definition leaks raw docstring artifacts (':param', ':return') that add noise rather than value. It is adequately sized but not cleanly structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need not be explained, yet the description still spends its budget on a vague ':return: Leave history message'. Combined with zero annotation coverage and an undocumented parameter, the definition leaves meaningful gaps for even a simple single-parameter read tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% with one required parameter, so the description must compensate, and it barely does: the ':param emp_id: Employee ID' line only restates the parameter name. There is no format, source, or lookup guidance for obtaining a valid 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?
States a specific verb and resource ('Get the leave history of an employee'), which is unambiguous on its own. However, it offers no differentiation from the closely related sibling get_employee_leave_balance, leaving the agent to guess which one answers a balance versus a history question.
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 get_employee_leave_balance or apply_leave, and no prerequisites or preconditions are stated. Usage must be inferred entirely from the 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?
No annotations are provided, so the description carries the full disclosure burden, and it discloses almost nothing: no pagination behavior, no ordering, no time-window scope, no permission requirements. Only the bare fact that a list is returned is conveyed.
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?
It is short and front-loaded with the purpose, but the Sphinx-style ':param'/':return' lines are redundant boilerplate given the input and output schemas, so the bytes spent add little.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return shape need not be explained, but for a read tool with zero annotation coverage the description should still clarify scope (time range, ownership, ordering). Those gaps leave the agent guessing about what the list actually contains.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With one parameter at 0% schema description coverage, the description must compensate, but ':param employee_id: Employee ID' merely restates the schema field name. No format, source, or constraints for the ID are given.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: retrieving the list of meetings for an employee. It is unambiguous on its own, but it never distinguishes itself from related siblings such as schedule_meeting or cancel_meeting, which an agent must still separate by name alone.
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 call this versus siblings, no preconditions, and no indication of what the result covers (past vs. upcoming, recurring instances). Usage is only inferable 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.
List tickets, optionally filtered by employee and/or status.
:param employee_id: Employee ID (optional)
:param status: Ticket status: Open, In Progress, Closed or Rejected (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?
With no annotations, the description carries the full burden; 'List tickets' implies a non-destructive read, which is the main safety signal. However, it never says whether the result is paginated, ordered, permission-scoped, or what happens when no filter is supplied (all tickets vs. none).
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 purpose sentence is front-loaded and every part of the :param: block adds documentation the schema lacks. The ':return: List of tickets' line is mildly redundant given an output schema exists, but it costs little.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-optional-parameter read tool with an output schema, the essentials are covered: purpose, filter semantics, and valid status values. What's missing is behavior when filters are omitted and result-set characteristics (volume, ordering), which matters because this tool can return the entire ticket table with no arguments.
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 is doing real work: it names both parameters, marks them optional, and enumerates the valid status values (Open, In Progress, Closed, Rejected), which the schema does not do. It lacks any hint on employee_id format, but overall compensation is strong.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource ('List tickets') plus optional filtering dimensions, which is clear on its own. It doesn't explicitly distinguish itself from siblings like create_ticket or update_ticket_status, though the read-vs-write contrast is implicit.
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 only implied by 'optionally filtered by employee and/or status' – the agent can infer that filters narrow the result set, but there is no explicit when-to-use guidance or mention of alternatives such as get_employee_details for per-employee views.
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, the description carries the full behavioral burden but only says a 'confirmation message' is returned. It doesn't state whether conflicting meetings are rejected, whether attendees are notified (send_email exists), or what permissions are needed for a mutation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
It's short and the purpose comes first, but the ':param'/':return' Sphinx tags duplicate what the input schema already declares, so a chunk of the text doesn't earn its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so the return description isn't strictly needed. Still, for a mutation tool with no annotations, missing conflict/notification semantics leaves an agent uncertain about what 'scheduling' actually does.
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 only restates employee_id and topic verbatim ('Employee ID', 'Topic of the meeting'). Its one addition, 'in python datetime format' for meeting_datetime, is useful guidance beyond the schema's format field, but leaves two of three parameters underexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Schedule a meeting for an employee'), which is enough for an agent to distinguish it from get_meetings and cancel_meeting. It stops short of explicitly naming those siblings, so it doesn't reach a 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 never says when to use this versus alternatives: it doesn't mention that get_meetings lists, cancel_meeting cancels, or what preconditions exist (e.g., whether the employee must already exist from add_employee). Usage is only inferred from the verb.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send an email.
:param to_emails: List of recipient email addresses
:param subject: Subject line
:param body: Email text
:param html: True if the body is HTML
:return: Confirmation message
| 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?
No annotations are provided, so the description carries the full behavioral burden, and it discloses almost nothing: not whether the message is actually dispatched externally, who the sender is, whether sends are rate-limited, or whether the action is irreversible. The single ':return: Confirmation message' line is the only behavioral hint, and an output schema already exists.
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?
Front-loaded with the purpose sentence, then one line per parameter; there is no filler. The Sphinx-style ':param:' markup is docstring residue rather than agent-facing prose, which costs a little readability but no real length.
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 real external side effects and zero annotation coverage, the description is thin: nothing about delivery behavior, sender identity, permissions, or failure modes. An output schema does exist, so the return-value line being minimal is acceptable, but that does not offset the missing behavioral context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% (properties carry only titles), so the description must compensate, and it does: all four parameters are documented with meaning beyond the schema — notably that html flags whether body is HTML. The explanations are terse (e.g. no format hints for to_emails) but semantically complete.
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 first line states a specific verb and resource ('Send an email'), which is enough to distinguish it from every sibling tool in the set, none of which are email-related. It is clear but not differentiated from any alternative, since no alternative exists.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no when-to-use guidance, no prerequisites, and no exclusions. There is no mention of when email is the appropriate channel versus e.g. create_ticket or schedule_meeting, even though those siblings compete for the same notification-style intent.
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 carries full burden of disclosure. It only states 'Update the status' without revealing side effects, validation, or behavior on invalid IDs. A mutation tool needs more detail.
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 docstring-style, with no unnecessary words. It efficiently conveys the core action but could benefit from a cleaner non-docstring format.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of parameter details, no annotations, and an output schema that is not described, the description is too minimal. It omits valid statuses, behavior on failure, and output structure, making it incomplete for confident agent 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?
Schema description coverage is 0%. The description repeats parameter names ('Ticket ID', 'New status') but adds no meaningful constraints or allowed values. It provides minimal clarification beyond the schema titles.
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' with a specific verb and resource. It distinguishes from sibling tools like create_ticket and list_tickets, as none of them update ticket status.
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 updating status but provides no explicit guidance on when to use versus alternatives, nor does it mention prerequisites or when not to use.
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_ticketsschedule_meetingsend_emailupdate_ticket_statusScored across 12 tools
Each tool targets a distinct HR resource and action: employees, tickets, meetings, leave, or email. There is no meaningful overlap that would cause an agent to select the wrong tool.
All tools use snake_case with a verb_noun pattern, which is predictable overall. Minor inconsistencies appear in noun forms such as schedule_meeting vs get_meetings and get_employee_details.
With 12 tools, the set is well within a reasonable range for an HR assistant. Each tool corresponds to a clear operational need across employees, tickets, meetings, leave, and email.
Core workflows are present, but notable lifecycle gaps remain: employees can be added and fetched but not updated, deleted, or listed; tickets can be listed and status-updated but not fetched individually; leave cannot be cancelled or approved. These gaps are workable but will limit some common HR operations.
Build and run AI workflows, agents, data tables and 1000+ API integrations from any MCP client.
One MCP endpoint for Claude, GPT & Gemini: 100+ tools + no-code connectors + agent workers.
Zapier MCP connects AI tools like Claude, ChatGPT, and Cursor to over 8,000 apps and 30,000+ actions, enabling AI to perform real-world tasks such as sending messages, searching data, scheduling events, and updating records. It acts as a translator between AI tools and apps, handling authentication, rate limits, and retries automatically, transforming AI from a conversational tool into a functional extension of your business stack.
Unified MCP Server is a remote MCP connector for AI agents and vertical AI products that provides access to 22,000+ authorized SaaS tools across 400+ integrations and 24 categories directly inside LLMs (Claude, GPT, Gemini, Cohere). Tools operate only on explicitly authorized customer connections, enabling agents to safely read and write against live third-party systems.