This is a read-only MCP server that lets Claude query BambooHR data about employees, time off, training, and company info.
Who's out: List employees on time off and company holidays in a date range.
Employee directory: Search and filter employees by name, email, department, or location; get id, job title, supervisor, etc.
Time-off types: List available time-off types (excluding health-related) and their units.
Time-off balances: Check one employee's vacation/sick balances as of a date, including used YTD.
Time-off requests: List requests by date range, employee, status, or type.
Vacation overview: Per department or employee list: balances, planned/unplanned vacation, longest continuous block, and whether 14-day blocks exist.
Employee fields: Discover standard and custom fields (e.g., shoe size) and whether they are readable.
Employee tables: List tabular data (job history, employment status, custom tables like equipment/certificates).
Company holidays: List holidays for a date range.
BambooHR users: List user accounts with status and last login for access reviews.
Get employee: Read a single employee's standard and custom field values (allow-listed only).
Employee report: Pull fields for a group of employees (by department, location, etc.) with filters.
Table rows: Read rows from a specific employee table for one employee.
Changed employees: See which employees were inserted, updated, or deleted since a timestamp.
Training types: List training categories, renewal periods, etc.
Training records: List one employee's completed trainings with details.
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., "@BambooHR MCP Server Who is out of office this week?"
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.
Eesti keeles: README.et.md
Ask Claude about your BambooHR data: who is out, vacation balances, employee fields, training and holidays. Read-only: it never creates, approves or changes anything in BambooHR.
Create an API key. In BambooHR: your photo (bottom left) → API Keys → Add New Key. Copy it; it is shown once.
Download bamboohr-mcp.mcpb.
Double-click it. Claude Desktop asks for:
BambooHR subdomain: acme if your BambooHR is at acme.bamboohr.com
BambooHR API key: the key from step 1
Click Install, start a new chat and ask: Who is out this week?
No Node.js, no terminal. The key is kept in your operating system's credential store, never in a file. Double-click does nothing? Settings → Extensions → Advanced settings → Install Extension and pick the file. To change the key or subdomain later: Settings → Extensions → BambooHR → Configure.
Related MCP server: bamboohr-mcp
Who is out next week?
How many vacation days does Anna Tamm have left?
Who in Engineering has not taken a 14-day vacation this year?
Which time-off requests in October are still waiting for approval?
When did Mart Mets start, and who is their manager?
Shoe sizes of everyone in the Tallinn office. (custom fields work too)
Has Anna done first-aid training?
Which public holidays are left this year?
Ask per department, office or person. One answer covers at most 25 people; for more, Claude will ask you to narrow it down.
You see at most what your own BambooHR account can see, and less:
Never: salary, bonuses, bank details, national id numbers, date of birth, home address, gender and similar personal fields.
Sick leave shows only as "absent", without reason or notes.
Dependents and employee documents are off unless an administrator turns them on.
If you ask for any of these, Claude says the field is excluded by policy. That is intentional.
You see | Fix |
"No BambooHR API key is available" | Settings → Extensions → BambooHR → Configure, fill in the key and subdomain. |
"is not a bare BambooHR subdomain" | Enter only |
Error 401 | Wrong or revoked key. Create a new one and paste it in Configure. |
Error 403, or people missing from answers | Your BambooHR account cannot see that data. Ask your BambooHR admin. |
"above the per-call limit" | Ask about a smaller group: one department, office or person. |
Vacation type not found | Put the exact name (e.g. |
Installed, but no answers | Quit Claude Desktop completely and reopen it. |
Data goes from BambooHR to the extension on your computer, and from there into your Claude chat. No BambooHR data is stored on disk.
A local audit log records which tool ran and which fields were asked for, never values or names. It is never sent anywhere.
The key is only sent to https://<subdomain>.bamboohr.com. The only other request is a version check at start-up; it sends only the version number.
If a key leaks, delete it in BambooHR under API Keys. To remove the extension: Settings → Extensions → BambooHR → Uninstall.
Read-only is enforced by this extension, not by BambooHR. An API key has the same rights as the account that created it. Use an account with the narrowest access you need. Provided as is under the MIT licence, without warranty or liability; you are responsible for your organisation's data-protection obligations.
Security design, settings, command line, Claude Code setup, release verification and development: docs/ADMIN.md. Changes: CHANGELOG.md.
MIT, see LICENSE.
List employees whose record changed since a timestamp: new hires (Inserted), edits to any field or table (Updated), and removals (Deleted). Ids and timestamps only, no field values. Newest first. Use bamboohr_get_employee to see the current values.
| Name | Required | Description | Default |
|---|---|---|---|
| type | No | Only this change type. Default: all. | |
| since | Yes | ISO 8601 date or date-time, e.g. 2026-09-01 or 2026-09-01T00:00:00+00:00. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so safety is covered. The description adds valuable behavioral context beyond that: output is limited to IDs and timestamps (no field values), results are 'Newest first', and the tool covers inserted/updated/deleted changes. This gives the agent a clear picture of what to expect without an output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each earning its place: the first states the core purpose and change types, the second specifies output shape and ordering, and the third routes to the sibling tool for current values. The description is front-loaded with the primary action and contains zero filler words.
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 no output schema, the description compensates by specifying that only IDs and timestamps are returned and that ordering is newest-first. It also mentions the three change types, which is essential for understanding output. Missing details like pagination or whether 'since' is inclusive are minor gaps, but for a simple two-parameter read-only tool the description is largely complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%: the 'since' parameter is fully documented with pattern and example, and 'type' has an enum with default. The description adds minor conceptual mapping (new hires = Inserted, edits = Updated, removals = Deleted), but it does not add syntax or format details beyond what the schema already provides. Baseline 3 is appropriate when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'List employees whose record changed since a timestamp', then enumerates the three change types (Inserted, Updated, Deleted) and states the output scope ('Ids and timestamps only'). This clearly distinguishes it from sibling tools like bamboohr_list_employees (listing all) and bamboohr_get_employee (current values), leaving no ambiguity about what the tool does.
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 explicitly points to an alternative: 'Use bamboohr_get_employee to see the current values', which tells the agent when to switch tools. It also states that only IDs and timestamps are returned, implying you should not use this tool if field values are needed. However, it does not mention other relevant siblings (e.g., bamboohr_list_employees) or provide broader when-not-to-use guidance, so it falls just short of full explicitness.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List company holidays that overlap a date range. Default: the current calendar year. Multi-day holidays that overlap the range are included.
| Name | Required | Description | Default |
|---|---|---|---|
| end | No | Range end, YYYY-MM-DD. Default: 31 December of the current year. | |
| start | No | Range start, YYYY-MM-DD. Default: 1 January of the current year. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so safety is covered. The description adds two behavioral details beyond the schema: the default range (current calendar year) and the inclusion of multi-day holidays that overlap. These are useful, non-obvious traits that help an agent reason about the result set.
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, no redundancy, and the primary action is stated first. The default and edge-case behavior are added efficiently without padding. Every clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only list tool with no required parameters and full schema coverage, the description covers the core behavior and defaults. It does not mention the response format, but the verb 'List' implies a list, and with no output schema, this is a minor gap. An agent can call it correctly without further info.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both start and end parameters are already documented with formats and defaults. The description reiterates the default but adds no new parameter-specific semantics. The multi-day overlap rule is behavioral, not parameter-focused. Thus a baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('List'), a clear resource ('company holidays'), and a precise condition ('overlap a date range'). It also defines defaults, making it unambiguous. With no sibling tool for holidays, it stands alone without confusion.
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 clear context on what the tool does and its default behavior, which implies when to use it (when company holiday data is needed). It doesn't explicitly contrast with alternatives like 'whos_out', but the scope is clear enough that an agent can infer its purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Pull chosen fields for a bounded group of employees in one call: e.g. hire date and a custom field such as shoe size for one department. Requires either employeeIds or a department, location or division filter (exact name, case-insensitive); company-wide reports are refused. At most the configured per-call record limit of rows is returned, otherwise the call is refused — narrow the filter. Only allow-listed and custom fields may be requested; pay, bank, birth date and similar fields are refused. id, displayName and status are always included. Inactive (terminated) employees are excluded unless includeInactive is true. missingFields lists fields BambooHR did not return, usually because the API key may not see them or the name is wrong; check names with bamboohr_list_fields.
| Name | Required | Description | Default |
|---|---|---|---|
| fields | Yes | Fields to include. | |
| division | No | Only employees in this division (exact name, case-insensitive). | |
| location | No | Only employees in this location (exact name, case-insensitive). | |
| department | No | Only employees in this department (exact name, case-insensitive). | |
| employeeIds | No | Restrict to these employee ids (at most the per-call record limit). | |
| includeInactive | No | Include employees whose status is not Active. Default false. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly and idempotent annotations, the description discloses important runtime behavior: calls are refused when the row limit is exceeded, sensitive fields are refused, inactive employees are excluded unless includeInactive is true, and missingFields indicates fields the API key could not return. This gives the agent a detailed failure model without contradicting the annotations.
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 information-dense but every sentence earns its place: purpose and example first, then filter requirements, limits, field restrictions, and edge cases in a logical sequence. No content is redundant with the schema or annotations, and the length is justified by the number of behavioral constraints.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a six-parameter tool with no output schema, the description covers the essential invocation contract: filter prerequisites, hard refusals, the per-call record limit, always-included fields, inactive handling, and how to interpret missingFields. The agent has enough information to select parameters, anticipate failures, and validate field names using the named sibling 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?
Even though schema coverage is 100%, the description adds mutually exclusive filter semantics ('Requires either employeeIds or a department, location or division filter') and notes that id, displayName and status are always included. It also explains that 'fields' refers to allow-listed or custom fields, and that employeeIds is capped by the per-call limit, materially enriching the schema definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Pull chosen fields for a bounded group of employees in one call', illustrated with a concrete example (hire date plus a custom field for one department). It further distinguishes itself from company-wide or single-employee siblings by stating 'company-wide reports are refused' and requiring a bounded filter, so an agent can confidently select it over alternatives.
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 explicitly defines when the tool can be used: requires employeeIds or a department/location/division filter, and explicitly says company-wide reports are refused. It also gives a when-not condition for sensitive fields ('pay, bank, birth date ... are refused') and directs the agent to bamboohr_list_fields for name validation, providing a named alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read one employee's field values: standard fields (hire date, job title, supervisor, status, work contact details) and custom fields (e.g. shoe size). Omit employeeId to read the API key owner's own record. Omit fields for a sensible default set. Fields outside the allow-list — pay, bank, national id, date of birth, gender, home contact details — are refused and nothing is returned; ask for other fields instead. missingFields lists requested fields that came back empty or that the key may not see.
| Name | Required | Description | Default |
|---|---|---|---|
| fields | No | Fields to read; only allow-listed and custom fields are permitted. Default: name, job, department, hire date, status, work contact. | |
| employeeId | No | Internal employee id from bamboohr_list_employees. Omit or 0 for yourself. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark readOnlyHint and idempotentHint, but the description adds critical behavioral details: the allow-list restriction with specific refused fields (pay, bank, national id, etc.), the consequence of 'nothing is returned' for those, and the missingFields response field. It also clarifies the omission semantics for employeeId. These go well beyond the annotations and significantly aid correct invocation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences with no fluff. The first sentence states the core purpose, the second covers parameter omission defaults, and the third explains restrictions and the missingFields output. It is front-loaded with the most important info and every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter read-only tool with no output schema, the description is remarkably complete. It covers what the tool does, how to invoke it (including defaults), what fields are forbidden, and what to expect in the response (missingFields). No critical information an agent needs to call it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds substantial meaning: for 'fields' it defines the default set and the allow-list boundary, and for 'employeeId' it explains the omission behavior (self) and the source of the id (bamboohr_list_employees). This enriches both parameters beyond the bare schema descriptions, which only mention type and basic intent.
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 action ('Read one employee's field values') and resource, distinguishing it from sibling tools like bamboohr_list_employees (which lists employees) or bamboohr_employee_report (which likely generates reports). It also specifies the scope of fields (standard and custom), making the purpose 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 gives usage tips (omit employeeId for self, omit fields for defaults) but never addresses when to choose this tool over alternatives. It does not mention sibling tools or conditions for using a different one, leaving the agent to infer the selection criteria. The absence of any exclusion guidance is a notable gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Look up employees in the BambooHR directory with id, name, job title, department, division, location, supervisor and work email. Requires search, department or location — listing the whole company in one call is not allowed — and returns at most the per-call record limit of people. Use the id with the balance and request tools.
| Name | Required | Description | Default |
|---|---|---|---|
| search | No | Case-insensitive substring of the name or work email. | |
| location | No | Only employees in this location (exact name, case-insensitive). | |
| department | No | Only employees in this department (exact name, case-insensitive). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, openWorld, and non-destructive hints, so the safety profile is covered. The description adds that a filter is required and that a per-call record limit applies, which is useful behavioral context. It does not describe pagination or error handling, but given the annotation coverage, a 3 is appropriate.
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 three sentences and front-loads the core purpose and fields. The constraint and record limit are clearly stated. The final sentence about using the id with other tools is useful but slightly tangential. Overall, it is efficient and well-structured, though not maximally concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so the description is responsible for clarifying the return. It lists the fields returned (id, name, job title, etc.) and mentions the record limit, which is helpful. However, it does not explain pagination, handling of no results, or whether additional pages can be requested. For a simple list tool this is a moderate gap, so a 3 is given.
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 already documents all three parameters with descriptions (100% coverage). The description adds critical semantics beyond the schema by stating that at least one of search, department, or location must be provided and that listing the whole company is not allowed. This is meaningful guidance that the schema alone does not convey.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: looking up employees with specific fields. It mentions the resource (BambooHR directory) and the action (look up/list). However, it doesn't explicitly differentiate from sibling tools like bamboohr_get_employee, which might serve a similar single-record use case. The constraint that a filter is required adds clarity but doesn't name alternatives.
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 a clear usage constraint: at least one of search, department, or location must be supplied, and listing the whole company is disallowed. It also hints at downstream use of the id. However, it does not explicitly say when to choose this tool over siblings like get_employee or list_users, leaving some inference to the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List every employee field in this BambooHR account, standard and custom, with id, name, API alias, type and an allowed flag. Only fields with allowed:true can be read by bamboohr_get_employee or bamboohr_employee_report; the rest (pay, bank, national id, date of birth, gender, home contact details) are refused by policy. Use search to find a field by name (e.g. 'shoe', 'hire'). Set includeOptions to see the allowed values of list fields.
| Name | Required | Description | Default |
|---|---|---|---|
| search | No | Case-insensitive substring of the field name or alias. | |
| includeOptions | No | Attach the option list of list-type fields. Default false. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavior beyond that: it discloses policy restrictions on sensitive fields (pay, bank, national ID, etc.) and explains the meaning of the allowed flag. No contradiction with annotations.
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 four sentences, front-loading the core function and then adding policy context and usage tips. Each sentence adds information; it could be slightly tightened but is appropriately sized and well ordered.
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 absence of an output schema, the description compensates by naming the exact return fields (id, name, API alias, type, allowed flag). It also covers the two parameters and the policy constraint. No obvious missing information an agent needs to call the tool correctly, though pagination/limits are not mentioned.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds meaning with concrete usage examples ('shoe', 'hire') and explains the effect of includeOptions ('see the allowed values of list fields'), which goes modestly beyond the schema's parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource ('List every employee field in this BambooHR account') and enumerates the output attributes (id, name, API alias, type, allowed flag). It clearly differentiates from sibling tools that list other resources (tables, time-off types, etc.).
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 clear usage context: it explains that only fields with allowed:true can be read by get_employee or employee_report, and gives guidance on using search and includeOptions. It does not explicitly name alternatives or when-not-to-use, but no direct alternative exists among siblings for listing fields.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the tabular fields this server may read (job history, employment status, and custom tables such as equipment or certificates) with the table alias and its columns. Compensation, bonus, bank, identity-document, health and similar tables, and money-type columns, are excluded by policy and are not listed. Use the alias with bamboohr_table_rows.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the operation safe/read-only; the description adds meaningful behavioral context by stating that certain tables and money-type columns are excluded by policy and will not appear. It also sets expectations for the response content (alias + columns), which goes beyond the annotations.
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 main purpose is front-loaded, followed by one sentence of policy exclusions and one routing pointer to a sibling tool. Every sentence earns its place, with no redundancy relative to the schema or annotations.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a no-input discovery tool, the description explains what will be returned, what is excluded, and how to use the results with bamboohr_table_rows. The annotations cover safety and open-world behavior, so nothing needed to call it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and 100% schema coverage, so there are no parameter semantics the description must explain. This matches the baseline for a no-parameter tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names the exact action ('List'), the resource ('tabular fields this server may read'), and the delivered content ('table alias and its columns'). It also distinguishes the tool from sibling bamboohr_table_rows by explaining how the alias is used downstream.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It clarifies when the tool is appropriate for job history, employment status, and custom tables, and explicitly states policy exclusions so an agent won't expect compensation, bank, or health tables. It names bamboohr_table_rows as the follow-up, though it doesn't explicitly contrast it as the alternative for row-level data.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the company's time-off types (e.g. vacation, unpaid leave) with their ids and units, plus the default hours per weekday. Use this to find the right type name or id for other tools. Health-related types (sick leave, care leave and similar) are excluded by policy and are not listed; health-related absences appear elsewhere as a generic 'absent'.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover readOnly, idempotent, and non-destructive behavior. The description adds meaningful context beyond annotations: health-related types are deliberately excluded by policy, and the tool returns default hours per weekday alongside ids and units.
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 three sentences, front-loads the core purpose, provides a direct use case, and closes with a necessary caveat. No sentence is redundant or wasted.
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 zero-parameter, read-only list tool, the description is complete: it explains what is returned, how to use the result, and a policy-driven exclusion that could otherwise surprise an agent. The annotations cover safety and idempotency, so no critical information is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters and schema coverage is 100%, so the baseline is 4. The description's mention of the output fields is useful but not necessary for parameter understanding because none exist.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('List') and resource ('the company's time-off types'), and specifies the returned data: ids, units, and default hours per weekday. This distinguishes it from sibling tools like time-off balances, requests, or whos-out, which address different concerns.
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 explicitly tells agents to use this tool 'to find the right type name or id for other tools,' giving a clear intended use case. It also notes that health-related types are excluded and appear elsewhere as a generic 'absent,' which prevents misuse when looking for sick leave.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List BambooHR user accounts (people who can log in) with their linked employee id, status and last login (no email: BambooHR may return a home address there). Useful for access reviews: who has an enabled account, who never logged in. Narrow the list with status or search; more accounts than the per-call record limit are refused.
| Name | Required | Description | Default |
|---|---|---|---|
| search | No | Case-insensitive substring of the first or last name. | |
| status | No | Only accounts with this status. Default: all. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already communicate read-only, idempotent, and non-destructive behavior. The description adds valuable behavioral context beyond annotations: it returns specific fields, flags the no-email caveat where BambooHR may return a home address, and states that accounts exceeding the per-call record limit are refused. It does not cover ordering or pagination, but for a list tool this is a solid disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each earning its place: main function and return fields, use case, then filtering and a critical limit warning. The key purpose is front-loaded and no redundant prose is present.
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 optional parameters and no output schema, the description covers the function, relevant fields, an important data caveat (no email), practical use, filtering options, and the record-limit refusal behavior. Nothing needed for correct invocation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both `search` and `status` are already documented in the input schema. The description only restates that filters exist ('narrow the list with status or search') without adding new semantic detail beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('List') and a distinct resource ('BambooHR user accounts (people who can log in)'), differentiating it from employee-list tools by focusing on login-capable accounts. It also lists returned fields (linked employee id, status, last login), making the tool's purpose unmistakable even without inspecting the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives concrete use context ('useful for access reviews'), explains how to narrow results ('with status or search'), and warns about the per-call record limit being refused. It does not explicitly name sibling alternatives or state when not to use this tool, so it stops short of full when/when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read the rows of an employee table for ONE employee: job history (jobInfo), employmentStatus, or any custom table (e.g. equipment, certificates). employeeId is required. Pay, compensation, bank, identity-document, health and similar tables are excluded by policy and are refused; money-type columns are dropped. Get valid table aliases from bamboohr_list_tables. Rows are unsorted; sort by date yourself.
| Name | Required | Description | Default |
|---|---|---|---|
| table | Yes | Table alias, e.g. jobInfo, employmentStatus, customEquipment. | |
| employeeId | Yes | Internal employee id. Required: this tool reads one employee at a time. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool read-only, idempotent, and non-destructive, and the description adds meaningful behavioral detail beyond that: policy-excluded tables are refused, money-type columns are dropped, one employee is handled per call, and row ordering is not guaranteed. No contradiction with annotations 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?
The description is compact and front-loaded with the core action and scope, followed by exclusions, dependency guidance, and a sorting caveat. Every sentence carries necessary information with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only tool with only two well-documented parameters and no output schema, the description is complete: it states scope, required parameter, policy exclusions, how to get valid aliases, and the unsorted-row behavior. An agent has enough information to select and invoke the tool 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?
The input schema fully documents both parameters, so the baseline is 3. The description adds extra value by explaining that employeeId is required and scopes the call to a single employee, and it tells the agent to obtain table aliases from bamboohr_list_tables and expect money-type columns to be dropped—useful context beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Read the rows of an employee table for ONE employee,' and clarifies the table categories (jobInfo, employmentStatus, custom tables) as well as excluded tables. This clearly differentiates it from siblings like bamboohr_get_employee, bamboohr_list_employees, and bamboohr_list_tables.
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 explicit when-to-use context (one employee's table rows), explicit when-not-to-use exclusions (pay, compensation, bank, health tables are refused), and directs the agent to bamboohr_list_tables for valid aliases. It also warns that rows are unsorted, so the caller knows to sort by date.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get one employee's time-off balances as of a date, including amount used year-to-date. Use a future date to project the balance. Health-related balances (sick leave and similar) are not reported.
| Name | Required | Description | Default |
|---|---|---|---|
| asOf | No | Calculate the balance as of this date, YYYY-MM-DD. Default: today. | |
| employeeId | Yes | Internal BambooHR employee id (from bamboohr_list_employees). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish read-only, idempotent, and non-destructive behavior. The description goes beyond those by clarifying that only one employee's balances are returned, that YTD usage is included, and that health-related balances are omitted. This adds meaningful operational context without contradicting the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short, purposeful sentences with no filler. The primary action is front-loaded, followed by a usage tip and a key exclusion, making it easy to scan and understand quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter read-only tool with strong annotations and no output schema, this definition is complete. It explains what the result covers, how to project future balances, and which balances are excluded—everything an agent needs to use 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?
The schema already documents both parameters with 100% coverage, giving the baseline of 3. The description adds extra meaning for 'asOf' by showing how to use it ('Use a future date to project the balance') and ties 'employeeId' to 'one employee's' balances, which is useful beyond the raw schema text.
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 uses a specific verb and resource: 'Get one employee's time-off balances as of a date.' It also defines the scope (one employee) and the data included ('amount used year-to-date'), which clearly separates it from sibling tools like bamboohr_time_off_requests or bamboohr_whos_out.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives direct usage guidance: 'Use a future date to project the balance.' It also warns of an important limitation with 'Health-related balances ... are not reported.' While it doesn't explicitly name alternative sibling tools, the context is clear enough for an agent to know when this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List time-off requests overlapping a date range, optionally filtered by employee, status and time-off type. Health-related absences are reduced to type 'absent' with no notes. Results are limited to employees the API key's owner may see, and to the per-call record limit.
| Name | Required | Description | Default |
|---|---|---|---|
| end | Yes | Range end, YYYY-MM-DD. | |
| start | Yes | Range start, YYYY-MM-DD. | |
| status | No | Limit to these statuses. Default: all. | |
| employeeId | No | Limit to one employee. | |
| timeOffTypeId | No | Limit to one time-off type id (see bamboohr_list_time_off_types). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark this as read-only, idempotent, and non-destructive. The description adds valuable behavioral context beyond that: health-related absences are reduced to type 'absent' with no notes, results are scoped to what the API key owner may see, and a per-call record limit applies. This is useful and does not contradict the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences with no filler: the first states the action and scope, the second adds a non-obvious behavioral transformation, and the third adds visibility and limit constraints. The key information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core behavior, optional filters, privacy scoping, redaction, and record limits, while the schema supplies formats and defaults. Without an output schema, a little more return-shape detail could help, but the description is adequate for selecting and invoking the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so start/end formats, status enum, employeeId, and timeOffTypeId are already documented structurally. The description only paraphrases the filter dimensions rather than adding new parameter-level semantics.
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 uses a specific verb and resource: 'List time-off requests overlapping a date range', with optional filters named. It clearly communicates the tool's function, though it does not explicitly differentiate it from sibling tools like bamboohr_whos_out or bamboohr_vacation_overview.
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 date-range and filter language imply when the tool is appropriate, but there is no explicit guidance on when to choose this over sibling tools. It does not state exclusions or point to alternatives such as who's-out or balance tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List one employee's completed trainings with completion date, instructor, hours, credits, cost and notes. Optionally limit to one training type. To check who is missing a required training, call this per employee.
| Name | Required | Description | Default |
|---|---|---|---|
| employeeId | Yes | Internal employee id. | |
| trainingTypeId | No | Only records of this training type (see bamboohr_training_types). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already signal read-only, idempotent, non-destructive behavior; the description adds concrete facts about scope ('per employee', 'completed') and return content (dates, instructor, hours, credits, cost, notes). It does not discuss edge cases like missing employee IDs or pagination, but the disclosed context exceeds the annotated baseline.
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 with action and resource, no redundant filler. Each clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple 2-parameter read tool with no output schema, the description covers the core return fields, the per-employee scope, and a representative use case. The schema and annotations fill in safety and parameter details, so nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%: employeeId and trainingTypeId are described in the schema, including the link to bamboohr_training_types. The description only restates that trainingTypeId is optional, adding no new semantics. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb ('List') and a bounded resource ('one employee's completed trainings'), and enumerates the returned fields. This distinguishes it from sibling tools like bamboohr_training_types, which lists type definitions rather than per-employee records.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives a clear operational context: 'Optionally limit to one training type' and 'To check who is missing a required training, call this per employee.' It does not explicitly name alternatives or exclusions, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the company's training types (name, category, required, renewable, renewal frequency in months, due window for new hires) and training categories. Use the type id with bamboohr_training_records.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish this as a safe, read-only, idempotent operation. The description adds the output fields and the relationship to training records, but does not describe response structure or other behavioral details. This is adequate but not extensive beyond the annotations.
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 concise sentences, front-loaded with the core purpose and followed by a useful usage pointer. No wasted words.
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 zero-parameter schema and read-only annotations, the description is nearly complete. It lists the returned fields and connects to the related sibling, but the exact response shape (e.g., array vs. object) is not stated. Still, this is a minor gap for such a simple list 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?
The tool has zero parameters, so the baseline is 4. The description adds value by enumerating the returned fields and clarifying that training categories are part of the result, which helps the agent understand the output even though no inputs are needed.
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 says this tool lists the company's training types with specific fields and training categories. It is unambiguous and distinguishable from the sibling bamboohr_training_records, with which it directly connects via the type id.
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 clearly implies this is the lookup tool for training type definitions and tells the agent to use the returned type id with bamboohr_training_records. It does not explicitly exclude other alternatives, but the context and sibling list make the intended usage clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Vacation report for one department (or a list of employeeIds) and one calendar year: vacation balance as of a date, used year-to-date, vacation planned after that date (approved or requested), unplanned balance (balance minus planned), the longest continuous vacation block in calendar days, and whether they have at least one 14-day continuous block. Adjacent requests are merged into one block. A department or employeeIds is required — a company-wide overview in one call is not allowed, ask per department — and the group must fit the per-call record limit. Use onlyMissingFourteenDayBlock to list only employees without a 14-day vacation. The summary counts all employees before that filter. Note: planned vacation excludes a request already in progress on the as-of date, on the assumption that BambooHR's balance has already deducted it.
| Name | Required | Description | Default |
|---|---|---|---|
| asOf | No | Balance date, YYYY-MM-DD, must be inside the year. Default: today (or Dec 31 for past years). | |
| year | No | Calendar year. Default: current year. | |
| department | No | Only employees in this department (exact name, case-insensitive). | |
| employeeIds | No | Only these employees. Use instead of, or together with, department. | |
| timeOffType | No | Vacation time-off type name or id. Default: the enrolled vacation type, else a type named like 'vacation' or 'puhkus'. | |
| onlyMissingFourteenDayBlock | No | Return only employees without a 14-day continuous block. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already cover readOnlyHint, openWorldHint, idempotentHint, and non-destructiveness, so the safety profile is clear. The description adds non-obvious calculation behaviors beyond annotations: adjacent requests are merged into one block, planned vacation excludes an in-progress request, and the summary counts all employees before the filter is applied.
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 dense but well organized: report contents first, then invocation constraints, then filter behavior, then an edge-case note. Each sentence carries a distinct and necessary fact, with no filler or repetition of the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description compensates by naming each computed field and explaining the in-progress request exclusion and per-call limits. The only minor gap is that the exact response envelope is not described, but an agent has enough information to invoke the tool correctly and interpret the returned concepts.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, and each parameter already has a schema description. The narrative adds business-level semantics the schema cannot express, such as requiring department or employeeIds despite no JSON-schema 'required' fields, and explaining that the filter only changes returned rows while summary counts remain unfiltered.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific computed resource: 'Vacation report for one department (or a list of employeeIds) and one calendar year', then enumerates the exact fields returned (balance, used YTD, planned, unplanned, longest block, 14-day flag). This level of specificity clearly differentiates it from siblings like bamboohr_time_off_balances or bamboohr_whos_out.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states when the tool can and cannot be used: 'A department or employeeIds is required — a company-wide overview in one call is not allowed, ask per department' and 'the group must fit the per-call record limit'. It also gives targeted feature usage for onlyMissingFourteenDayBlock. It does not explicitly name sibling tools as alternatives, so it stops short of a full 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List employees who are out of office and company holidays in a date range. Defaults to today through 14 days ahead. Each entry has type 'timeOff' (with employeeId and employee name) or 'holiday' (holiday name only). A range with more people out than the per-call record limit is refused (holidays do not count); use a shorter range.
| Name | Required | Description | Default |
|---|---|---|---|
| end | No | Last day of the range, YYYY-MM-DD. Default: start + 14 days. | |
| start | No | First day of the range, YYYY-MM-DD. Default: today. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the tool read-only, idempotent, and non-destructive, so the description's job is to add behavior beyond safety. It does this by disclosing the per-call record-limit refusal, clarifying that holidays do not count toward that limit, and describing the response entry shapes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each carrying distinct information: the core purpose, the default range and response entry types, and the failure/limit behavior. It is front-loaded with the action and resource, with no filler or 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?
All essential call information is present: optional parameters and defaults, response entry types, and the failure mode involving the per-call limit. Since there is no output schema, the description compensates by clearly describing the response shape.
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 100% parameter description coverage, documenting start and end with YYYY-MM-DD format and defaults. The description restates the default range but adds no parameter-specific meaning beyond what the schema already provides; the record-limit note is operational behavior rather than parameter semantics.
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 ('List') and the exact resource (employees out of office and company holidays) and further clarifies the two entry types, timeOff and holiday. This distinguishes it from sibling tools that cover only one category, such as company holidays or time-off requests.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear usage context: an optional date range with defaults (today through 14 days ahead) and an explicit corrective instruction to use a shorter range if the per-call record limit is exceeded. It does not name sibling alternatives, so it falls short of full when-to-use-versus-alternatives guidance.
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.
v4.2.0bamboohr_list_users1 field changedInput schema / properties / search / descriptionPrevious value: -"Case-insensitive substring of the first name, last name or email."New value: +"Case-insensitive substring of the first or last name."v4.1.0bamboohr_changed_employees2 fields changedInput schema / properties / since / minLengthRemoved value: -10Input schema / properties / since / patternAdded value: +"^\\d{4}-\\d{2}-\\d{2}(T[0-9:+\\-Z.]+)?$"bamboohr_employee_dependentsbamboohr_employee_filesbamboohr_employee_report4 fields changedInput schema / properties / departmentAdded value: +{
+ "description": "Only employees in this department (exact name, case-insensitive).",
+ "minLength": 1,
+ "type": "string"
+}Input schema / properties / divisionAdded value: +{
+ "$ref": "#/properties/department",
+ "description": "Only employees in this division (exact name, case-insensitive)."
+}Input schema / properties / employeeIds / descriptionPrevious value: -"Restrict to these employee ids."New value: +"Restrict to these employee ids (at most the per-call record limit)."Input schema / properties / locationAdded value: +{
+ "$ref": "#/properties/department",
+ "description": "Only employees in this location (exact name, case-insensitive)."
+}bamboohr_get_employee1 field changedInput schema / properties / fields / descriptionPrevious value: -"Fields to read. Default: name, job, department, hire date, status, contact."New value: +"Fields to read; only allow-listed and custom fields are permitted. Default: name, job, department, hire date, status, work contact."bamboohr_list_employees4 fields changedInput schema / additionalPropertiesAdded value: +falseInput schema / properties / departmentAdded value: +{
+ "$ref": "#/properties/search",
+ "description": "Only employees in this department (exact name, case-insensitive)."
+}Input schema / properties / locationAdded value: +{
+ "$ref": "#/properties/search",
+ "description": "Only employees in this location (exact name, case-insensitive)."
+}Input schema / properties / searchAdded value: +{
+ "description": "Case-insensitive substring of the name or work email.",
+ "minLength": 1,
+ "type": "string"
+}bamboohr_list_fields1 field changedInput schema / properties / search / minLengthAdded value: +1bamboohr_list_users1 field changedInput schema / properties / searchAdded value: +{
+ "description": "Case-insensitive substring of the first name, last name or email.",
+ "minLength": 1,
+ "type": "string"
+}bamboohr_table_rows5 fields changedInput schema / properties / employeeId / descriptionPrevious value: -"Internal employee id. Omit for all employees the key may see."New value: +"Internal employee id. Required: this tool reads one employee at a time."Input schema / properties / table / descriptionPrevious value: -"Table alias, e.g. jobInfo, compensation, employmentStatus, customEquipment."New value: +"Table alias, e.g. jobInfo, employmentStatus, customEquipment."Input schema / properties / table / minLengthRemoved value: -1Input schema / properties / table / patternAdded value: +"^[A-Za-z0-9_]{1,64}$"Input schema / requiredPrevious value: -[
- "table"
-]New value: +[
+ "table",
+ "employeeId"
+]bamboohr_time_off_requests1 field changedInput schema / properties / timeOffTypeId / patternAdded value: +"^\\d{1,10}$"bamboohr_vacation_overview5 fields changedInput schema / properties / department / minLengthAdded value: +1Input schema / properties / employeeIdsAdded value: +{
+ "description": "Only these employees. Use instead of, or together with, department.",
+ "items": {
+ "exclusiveMinimum": 0,
+ "type": "integer"
+ },
+ "type": "array"
+}Input schema / properties / timeOffType / $refAdded value: +"#/properties/department"Input schema / properties / timeOffType / descriptionPrevious value: -"Vacation time-off type name or id. Default: BAMBOOHR_VACATION_TYPE, else a type named like 'vacation' or 'puhkus'."New value: +"Vacation time-off type name or id. Default: the enrolled vacation type, else a type named like 'vacation' or 'puhkus'."Input schema / properties / timeOffType / typeRemoved value: -"string"v3.0.0bamboohr_changed_employeesbamboohr_company_holidaysbamboohr_employee_dependentsbamboohr_employee_filesbamboohr_employee_reportbamboohr_get_employeebamboohr_list_employeesbamboohr_list_fieldsbamboohr_list_tablesbamboohr_list_time_off_typesbamboohr_list_usersbamboohr_table_rowsbamboohr_time_off_balancesbamboohr_time_off_requestsbamboohr_training_recordsbamboohr_training_typesbamboohr_vacation_overviewbamboohr_whos_outScored across 16 tools
Tools mostly map to distinct resources and actions, with detailed descriptions clarifying boundaries. Some overlap exists between whos_out, time_off_requests, and company_holidays, and between list_employees, get_employee, and employee_report, but these are unlikely to cause serious misselection.
All tools share the bamboohr_ prefix and snake_case, but the naming convention is mixed: some use list_ or get_ while many are bare noun phrases like training_types, table_rows, or vacation_overview. This is readable but does not follow a consistent verb_noun pattern.
At 16 tools, the server is slightly above the typical 3-15 range, but the count is justified by the breadth of HR subdomains covered: employees, time off, training, tables, users, holidays, and change tracking. Each tool serves a distinct purpose and none feels redundant.
The server provides strong read-only coverage of common HR workflows: employee lookup, field metadata, time-off balances and requests, training records, holidays, and change tracking. Minor gaps exist, such as training compliance requiring per-employee calls and company-wide reports being intentionally blocked, but agents can work around these.
Query your org's data in natural language — read-only MCP access to SQL, NoSQL, files & warehouses.
Ask data questions in natural language. Get SQL, insights, and charts from your databases.
Ask questions in plain language, get answers from your business database. No SQL required.
Ask business questions in plain English. Get instant answers from your database, no SQL needed.
