This server provides an MCP interface for the Timetastic API, enabling agentic clients to query and manage absence, leave, and related workforce data.
Absences
List who is off between specified dates (up to 31 days), merging bookings, public holidays, non-working days, and other events.
Leave Bookings (Holidays)
List holidays with rich filtering (date, status, user, department, leave type, approver, etc.) with pagination
Get a single holiday by ID
Book leave (including half-days, hourly bookings, admin overrides) for yourself, a department, or everyone
Approve, decline, or cancel individual or group bookings
Users
List, get, add, edit, archive, and restore users
Get user contact details (Pro accounts only)
Assign public holidays to a user by country/region
Departments
List, get, create, edit, and delete departments
Leave Types
List, get, create, update, and delete leave types
List valid colors and icons for leave types
Allowances
List allowances, carry-forward, and TOIL for all users or a specific user
Update annual allowances and carry-forward amounts
Add, update, and delete TOIL (Time Off In Lieu) entries
Locked Dates
List, add, and delete locked date periods (scoped to organisation, department, or user)
Public Holidays
List public holidays (filterable by country, year, or user), get a specific holiday, and list available countries
Webhooks
List recent webhook events (up to 30 days of history)
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@timetastic-mcp list upcoming holidays for Jane Doe"
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.
An unofficial MCP server for Timetastic, exposing the Timetastic API to agentic clients so they can query and manage absence & leave data.
You need an admin API token, generated at
https://app.timetastic.co.uk/api. The server reads it from the
TIMETASTIC_API_TOKEN environment variable.
The quickest way to run it is with uv's uvx,
which fetches and runs the published package without a manual install:
export TIMETASTIC_API_TOKEN="your-token-here"
uvx timetastic-mcpOr install it as a tool so the timetastic-mcp command is on your PATH:
uv tool install timetastic-mcp # or: pipx install timetastic-mcpOnly admin users can generate API tokens on Timetastic. The above URL is only accessible to admin users.
Related MCP server: Tweek MCP Server
Add the server to your MCP client (e.g. Claude Desktop / Claude Code):
{
"mcpServers": {
"timetastic": {
"command": "uvx",
"args": ["timetastic-mcp"],
"env": { "TIMETASTIC_API_TOKEN": "your-token-here" }
}
}
}Pin a version with "args": ["timetastic-mcp@0.1.0"]. If you installed the
command on your PATH instead, use "command": "timetastic-mcp" with
"args": []. In Claude Code you can also add it from the CLI:
claude mcp add timetastic --env TIMETASTIC_API_TOKEN=your-token -- uvx timetastic-mcpTools are grouped by resource and named <verb>_<resource>.
Group | Tools |
Absences |
|
Holidays (leave bookings) |
|
Users |
|
Departments |
|
Leave types |
|
Allowances |
|
Locked dates |
|
Public holidays |
|
Webhooks |
|
Note: Timetastic calls all leave bookings "holidays" for historical reasons — the Holidays tools cover any kind of absence, not just annual leave.
The package lives under src/timetastic_mcp/:
timetastic.py — async HTTP client (auth,
base URL, rate-limit retries, error handling).
server.py — the shared FastMCP instance
and get_client(), the lazily-created API client the tools call.
tools/ — one module per resource area, each
registering its tools on the shared server: absences, holidays, users,
departments, leave_types, allowances, locked_dates,
public_holidays, webhooks.
main.py — entry point (the timetastic-mcp
console script); imports tools to register everything, then runs the server.
Requires Python 3.13+ and uv.
uv sync # create the venv and install the package + dev deps
uv run pytest # run the test suite
uv run timetastic-mcp # run the server from your checkoutThe API is rate limited to 5 requests/second per token (1/second for
list_absences); the client retries once on a 429.
Write and admin operations require appropriate permissions on the token's user account.
Approve, decline or cancel a holiday.
Args:
holiday_id: The holiday ID (or a holiday token).
action: Approve, Decline, Delete (cancel this booking) or
DeleteGroup (cancel the whole group booking).
reason: Optional reason, typically used when declining/cancelling.
suppress_emails: Suppress notification emails when actioning.
Raises a webhook event if webhooks are configured.
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | ||
| reason | No | ||
| holiday_id | Yes | ||
| suppress_emails | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses webhook event side effect and notes that reason is typically used for declining/cancelling. Suppress_emails is explained. Lacks mention of permissions or reversibility, but given no annotations, this adds good value.
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?
Concise bullet-style list of parameters. No redundant information. Would benefit from a brief note on usage context, but otherwise efficient.
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?
Covers purpose and parameters well but lacks return value description, error handling, or permission requirements. For a mutation tool with no output schema and no annotations, the description could provide more context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Adds significant meaning beyond the schema: explains each parameter's purpose (holiday_id, action values, reason usage, suppress_emails). Clarifies distinction between 'Delete' and 'DeleteGroup'. Schema coverage is 0%, so description fully compensates.
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?
Explicitly states the verb 'Approve, decline or cancel' and the resource 'a holiday'. Distinguishes from siblings like book_holiday (create) and list_holidays (read) by focusing on modifying existing holidays.
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?
Indicates the tool is for approving, declining, or canceling holidays but provides no explicit comparison to alternative tools (e.g., delete_department) or conditions for use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new department.
Args: name: The department name. manager_id: User ID of the department manager. max_off: Max number of users off at once (0 = no limit).
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| max_off | No | ||
| manager_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It only indicates the action (create) without mentioning side effects, permissions required, error conditions (e.g., duplicate name), idempotency, or any other behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, using a single sentence to state the purpose followed by a clear list of arguments. Every word is necessary, and there is no fluff or repetition.
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 and annotations, the description should provide information about the tool's return value (e.g., whether it returns the new department ID or a success status). It also lacks context on error handling or what happens when required fields are invalid. The tool is simple, but these gaps hinder an agent's ability to handle the response 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 description adds a brief explanation for each parameter: name is department name, manager_id is user ID of manager, max_off is max off at once with 0 indicating no limit. While this provides some clarity beyond the schema (which had 0% coverage), the explanations are minimal and do not elaborate on constraints (e.g., manager_id must be an existing user) or edge cases.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a new department.' This is a specific verb+resource pairing and distinguishes the tool from siblings like edit_department, delete_department, and list_departments.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives (e.g., edit_department for modifications, get_department for retrieval). The description only states what it does, with no context on prerequisites, restrictions, or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add a locked date period.
Args:
from_date: Start of the locked period (ISO 8601 date-time).
to_date: End of the locked period (ISO 8601 date-time).
reason: Reason for the lock (1–2000 chars).
record_type: Scope of the lock: Organisation, Department or
User. Higher-level locks supersede lower-level ones.
record_id: The organisation, department or user ID the lock targets.
| Name | Required | Description | Default |
|---|---|---|---|
| reason | Yes | ||
| to_date | Yes | ||
| from_date | Yes | ||
| record_id | Yes | ||
| record_type | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description explains the lock's effect, including the hierarchy of record types ('Higher-level locks supersede lower-level ones'). It does not cover authorization or side effects, but the behavioral context is adequate for an add operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with a clear docstring format. Every sentence is informative, no unnecessary words. Parameter explanations are direct and well-organized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description covers all required inputs and the core behavior. It lacks information about response format, error handling, or authentication, but is sufficient for a simple creation 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 coverage is 0%, so the description compensates fully. It explains every parameter: from_date, to_date, reason, record_type (with enum meanings and hierarchy), and record_id. Adds significant meaning beyond schema titles/types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Add a locked date period,' which is a specific verb+resource description. It distinguishes from sibling tools like 'delete_locked_date' and 'list_locked_dates' by using 'add'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. Does not mention prerequisites, context, or when not to use it. The description only defines the tool's function and parameters.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add a new user to Timetastic.
Args:
first_name: The user's first name.
last_name: The user's last name.
department_id: The department to place the user in.
allowance: Annual leave allowance in days (0–366).
email_address: The user's email address.
start_date: Start date, ISO 8601 (e.g. 2022-02-04T00:00:00).
leave_year_start: Month the leave year starts (1=Jan … 12=Dec).
send_welcome_email: Email the user to set a password and get started.
| Name | Required | Description | Default |
|---|---|---|---|
| allowance | Yes | ||
| last_name | Yes | ||
| first_name | Yes | ||
| start_date | No | ||
| department_id | Yes | ||
| email_address | No | ||
| leave_year_start | No | ||
| send_welcome_email | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavioral traits. It only states the action without covering side effects, idempotency, permission requirements, or error conditions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with a clear opening sentence followed by parameter descriptions. No redundant or irrelevant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description covers the 'what' of parameters but lacks information on return values, error cases, or behavioral constraints. It is minimally adequate but not 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?
The description adds meaningful details for each parameter beyond the schema titles, such as allowance range, ISO 8601 format for start_date, and leave_year_start mapping. With 0% schema coverage, this is crucial and well-done.
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 tool name and description clearly state 'Add a new user to Timetastic', which is a specific verb+resource. It distinguishes well from siblings like 'edit_user' and 'archive_user'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. The description does not mention prerequisites, when it should not be used, or any context for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add a TOIL (time off in lieu) entry for a user in a year.
Args: user_id: The user to add TOIL for. year: The year the TOIL applies to. amount: TOIL amount (-5000 to 5000). description: Optional description (max 1000 chars).
Returns the ID of the new TOIL entry.
| Name | Required | Description | Default |
|---|---|---|---|
| year | Yes | ||
| amount | Yes | ||
| user_id | Yes | ||
| description | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description discloses basic behavior: it adds a TOIL entry and returns the ID. It mentions amount range and description max length, but lacks details on permissions, idempotency, or conflict handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with no fluff. It uses a clear structure: a one-line purpose, then bullet-like parameter descriptions, and a return statement. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description explains the purpose, all parameters, and return value. However, it omits potential error conditions, prerequisites (e.g., user existence), and behavior on duplicate entries. For a simple add tool, it is adequate but not exhaustive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% coverage, but the description adds meaning beyond the schema by explaining each parameter's purpose, the amount range (-5000 to 5000), and the description max length. This adds significant value beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Add' and the resource 'TOIL entry' with context 'for a user in a year'. It distinguishes from sibling tools like 'delete_user_toil' and 'update_user_toil' by specifying the action of adding.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention prerequisites, when not to use it, or compare with other tools like 'book_holiday' or 'action_holiday'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Archive a user. They are logged out immediately and cannot log in.
Args: user_id: The ID of the user to archive. archive_date: The date the user left (UTC, must be in the past), ISO 8601. Shown on their archived profile and in reports.
| Name | Required | Description | Default |
|---|---|---|---|
| user_id | Yes | ||
| archive_date | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses immediate logout and inability to log in, which is good. However, it omits details like whether the user is removed from workspaces, if data is retained, or if the action is reversible (restore_user exists). The behavioral footprint is partly covered but not fully.
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 action and effect, and then provides parameter details. No unnecessary words, every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with two parameters and no output schema, the description covers the key behavioral effects and parameter details. However, it does not explain what happens if archive_date is omitted (default to current time? never shown?), and omits side effects like cancelling future bookings. Still, it is mostly 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 coverage is 0%, so the description must add meaning. It explains archive_date with format, constraint (past), and purpose (shown on profile and reports), adding value. The user_id description is minimal but functional. Overall, the description compensates for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Archive a user' and its immediate effects: 'They are logged out immediately and cannot log in.' This distinguishes it from sibling tools like edit_user (which doesn't deactivate) and restore_user (which reactivates).
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 deactivating users but does not explicitly state when to use this tool versus alternatives like edit_user or restore_user. No preconditions or exclusions are provided. The simple nature makes implied usage acceptable but not exemplary.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Assign a set of public holidays to a user (enabling them if needed).
Args:
user_id: The user's ID.
country_code: ISO 3166-1 alpha-2 country code (e.g. "ES" for Spain).
region_code: Full region code (e.g. "GB-SCT" for Scotland,
"ES-AN" for Andalucía).
If the chosen country/region is already used by your organisation, that (possibly customised) set is used; otherwise the standard set is assigned.
| Name | Required | Description | Default |
|---|---|---|---|
| user_id | Yes | ||
| region_code | No | ||
| country_code | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It explains that if the country/region is already used by the organization, the custom set is used; otherwise standard. This adds useful behavioral context. However, it does not disclose whether the assignment is additive or replaces existing holidays, or any side effects like overriding previous assignments.
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 efficient: one sentence for purpose, then a clean Args list with examples, and a final sentence on custom vs standard. No extraneous words; well-structured for quick parsing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with 3 parameters and no output schema, the description covers purpose, parameter details, and behavioral nuance (custom vs standard). It lacks completeness on the effect of re-assignment or reversal, but is generally adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description must add meaning. It provides examples and format for 'country_code' (ISO 3166-1 alpha-2) and 'region_code' (full region code like 'GB-SCT'). 'user_id' is only described as 'The user's ID', which adds minimal value beyond the schema title. Overall partial but helpful compensation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Assign' and the resource 'a set of public holidays to a user'. It also mentions enabling them if needed. This distinguishes the tool from siblings like 'book_holiday' (individual booking) and 'get_public_holiday' (retrieval).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives. The description mentions behavior regarding custom vs standard holiday sets but does not advise on cases where sibling tools like 'action_holiday' or 'book_holiday' might be more appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Submit a leave request (book time off).
Args:
from_date: Start date YYYY-MM-DD (no time component).
to_date: End date YYYY-MM-DD (no time component).
leave_type_id: The leave type to book (see list_leave_types).
book_for: User, Department or Everyone.
user_or_department_id: ID of the user/department to book for (with
book_for). Omit to book for yourself.
from_time: Part of the start day: "AM", "PM", or minutes since
midnight for an hourly booking.
to_time: Part of the end day: "AM", "PM", or minutes since
midnight for an hourly booking.
reason: Optional reason for the request.
suppress_emails: Admins only — suppress notification emails.
book_as_requestee: Admins only — book as if the requestee made it so the
normal approval flow runs (default is auto-approved by the admin).
override: Admins only — bypass the department max-off limit.
override_locked_days: Admins only — book over locked dates.
override_accrued_allowance: Admins only — bypass accrued-allowance check.
attachment_id: Attach a previously uploaded attachment by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| reason | No | ||
| to_date | Yes | ||
| to_time | No | ||
| book_for | No | User | |
| override | No | ||
| from_date | Yes | ||
| from_time | No | ||
| attachment_id | No | ||
| leave_type_id | Yes | ||
| suppress_emails | No | ||
| book_as_requestee | No | ||
| override_locked_days | No | ||
| user_or_department_id | No | ||
| override_accrued_allowance | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility. It explains each parameter's effect (e.g., admin-only overrides, notification suppression) and implies a write operation, but does not disclose potential side effects (e.g., duplicate request handling, approval flow details beyond book_as_requestee). The behavior is partially transparent but lacks completeness.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is structured as a clear docstring with a brief summary and an Args list. While it is lengthy due to 14 parameters, it is well-organized and front-loaded with the purpose. Minor redundancy (e.g., 'book time off' in summary) but overall efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (14 parameters, 3 required) and lack of output schema, the description covers parameters but omits the return value (e.g., the created leave request ID) and prerequisites (e.g., user existence, leave type validity). It references list_leave_types but not explicitly as a prerequisite. Could be more complete for agent decision-making.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, meaning no parameter descriptions in the JSON. The description compensates fully by explaining all 14 parameters, including format (YYYY-MM-DD), enum values (AM/PM), and admin-only flags. This adds significant meaning beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Submit a leave request (book time off).' It uses a specific verb (submit/book) and resource (leave request), making the tool's purpose unambiguous. It distinguishes itself from sibling tools like list_holidays or get_holiday by focusing on creation.
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 parameter explanations and references list_leave_types for leave_type_id, but lacks explicit guidance on when to use this tool versus alternatives like action_holiday. No 'use this when' or 'instead of' statements are present, leaving the agent to infer context from the action.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new leave type (admins only).
Args:
name: Name of the leave type (1–50 chars).
deducted: Whether it deducts from the user's allowance.
requires_approval: Whether bookings need approval.
include_max_off: Whether it counts toward max-absent limits.
is_private: Whether the leave type is private.
color: A hex colour (see list_leave_type_colors).
icon: An icon name (see list_leave_type_icons).
calendar_visibility: Busy, Available or OutOfOffice.
limit_hours: Optional limit in hours.
limit_days: Optional limit in days.
Returns the ID of the new leave type.
| Name | Required | Description | Default |
|---|---|---|---|
| icon | No | ||
| name | Yes | ||
| color | No | ||
| deducted | No | ||
| is_private | No | ||
| limit_days | No | ||
| limit_hours | No | ||
| include_max_off | No | ||
| requires_approval | No | ||
| calendar_visibility | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that the tool creates a new leave type and returns its ID, but does not mention side effects, rate limits, or error conditions. It does not contradict any 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 concise and well-structured with an initial purpose statement followed by a clear list of parameters. Every sentence adds value, and there is no extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (10 parameters, no output schema, no annotations), the description provides thorough parameter documentation and a return value. It could be more complete by mentioning potential errors or prerequisites, but overall it adequately covers the tool's behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, yet the description adds detailed meaning for all 10 parameters. It explains each parameter's purpose, includes enumerated values for calendar_visibility, and directs users to sibling tools for color and icon options, exceeding compensation requirements.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a new leave type' with a specific verb and resource. It explicitly says 'admins only' and distinguishes from sibling tools like update_leave_type and delete_leave_type.
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 specifies that it's for admins and references sibling tools for valid parameter values (list_leave_type_colors, list_leave_type_icons). However, it does not explicitly state when to use this tool versus alternatives like update_leave_type.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a department. It must be empty (reassign any users first).
| Name | Required | Description | Default |
|---|---|---|---|
| department_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description adds the behavioral constraint that the department must be empty, but does not disclose irreversibility, permissions needed, or side effects beyond deletion.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with a brief precondition, no unnecessary words, and is front-loaded with the action.
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 delete tool with one parameter and no output schema, the description covers the essential precondition but omits return value or how to obtain the department_id.
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 0% schema description coverage, the description does not explain the department_id parameter (e.g., format, source), relying on the obvious meaning from the tool name.
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 'Delete a department', which is a specific verb and resource. It distinguishes from sibling tools like add_department, edit_department, and get_department.
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 precondition 'It must be empty (reassign any users first)' provides context for when to use the tool, but does not explicitly mention alternatives or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete (deactivate) a leave type. Cannot delete the last active one.
| Name | Required | Description | Default |
|---|---|---|---|
| leave_type_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses a behavioral constraint—cannot delete the last active leave type—but does not mention permissions, side effects, or what happens on deletion (e.g., if leave types in use are affected).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that efficiently conveys the action and a key constraint. No unnecessary 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?
The tool is simple (one parameter, no output schema), but the description lacks parameter explanation and return value info. For a deletion tool, basic completeness might include what the response indicates (e.g., success/failure), which 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 0%, so the description must add meaning beyond the schema. However, the description does not mention the leave_type_id parameter at all, leaving the agent with only the schema name and type (integer). This is insufficient for understanding the parameter's role or format.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Delete (deactivate) a leave type.' It also adds a specific constraint ('Cannot delete the last active one'), which distinguishes it from other tools like update_leave_type or create_leave_type.
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 when to use (for deletion) but provides no explicit guidance on when not to use or alternatives. The constraint about not deleting the last active one gives some usage context, but no direct comparison to siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a locked date by ID (admins/authorised managers only).
| Name | Required | Description | Default |
|---|---|---|---|
| locked_date_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description must fully disclose behavior. It confirms the destructive nature (delete) and mentions authorization, but does not discuss reversibility, side effects, or response format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence with no filler. Every part serves a purpose—action, resource, parameter, and authorization hint.
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 delete tool with one parameter and no output schema, the description provides minimal but adequate information. It could include behavioral details like confirmation or effects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not elaborate on the locked_date_id parameter beyond 'by ID'. It fails to add meaning such as format, source, or constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Delete' and the resource 'locked date', with explicit granularity 'by ID'. This distinguishes it from sibling tools like add_locked_date or list_locked_dates.
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 hints at who should use it via '(admins/authorised managers only)', but does not provide explicit guidance on when to use it versus alternatives, nor any conditions or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a user's TOIL entry.
| Name | Required | Description | Default |
|---|---|---|---|
| year | Yes | ||
| toil_id | Yes | ||
| user_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Only states that it deletes, but no details on reversibility, permissions, or side effects. Minimal behavioral 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?
Single sentence, no fluff, but lacks structure and could provide more detail in a concise manner.
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 0% schema coverage, no output schema, and no annotations, the description is severely incomplete. Key information about return values, error states, and parameter meaning 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?
No parameter descriptions in schema or description. All three parameters (user_id, year, toil_id) are 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?
Description clearly states the action (delete) and resource (user's TOIL entry). Distinguishes from sibling tools like add_user_toil and update_user_toil.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives. No prerequisites or context provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Edit a department. Only the fields you supply are changed.
Args: department_id: The department to edit. name: New department name. manager_id: User ID of the department manager. max_off: Max users off at once (0 disables the limit; range 0–20).
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | ||
| max_off | No | ||
| manager_id | No | ||
| department_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description states 'Only the fields you supply are changed', indicating partial update behavior. With no annotations provided, the description carries the burden of behavioral disclosure, but it does not mention permissions, side effects, or whether changes are reversible. It adds some context (e.g., max_off range) but lacks overall transparency for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short (two sentences plus argument list) and gets to the point. It uses a docstring-style structure for parameters. Could be slightly more structured (e.g., bullet points) but is efficient and readable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description should provide more context about return values, permissions, or usage scenarios. It explains the partial update behavior and a constraint on max_off, but lacks completeness for a tool that modifies data. Agent would need to infer permissions and response format.
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. It adds meaning beyond the schema for some parameters: 'max_off' has range and disabling behavior explained; 'name' and 'manager_id' have brief descriptions. However, 'department_id' is only identified as required without additional context. The description partially enriches parameters but is incomplete.
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 'Edit a department' with a specific verb ('Edit') and resource ('department'). It conveys that it is an update operation, distinguishing it from add (add_department) and delete (delete_department) siblings, though it does not explicitly name those 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?
No guidance on when to use this tool versus alternatives (e.g., add_department for creation, delete_department for removal). No prerequisites or context for use are provided. The description only states what it does, not when it is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Edit a user. Only the fields you supply are changed (partial update).
Args:
user_id: The ID of the user to edit.
email_address: New email. Pass "" to clear an existing address.
approver_id: The user's approver; set to 0 to default to dept manager.
public_holiday_set_id: Public holiday set (needs has_public_holidays).
has_public_holidays: Enable public holidays for this user.
(Other args map directly to the corresponding user fields.)
| Name | Required | Description | Default |
|---|---|---|---|
| city | No | ||
| admin | No | ||
| country | No | ||
| user_id | Yes | ||
| address1 | No | ||
| address2 | No | ||
| birthday | No | ||
| director | No | ||
| job_title | No | ||
| last_name | No | ||
| post_code | No | ||
| first_name | No | ||
| payroll_id | No | ||
| start_date | No | ||
| telephone1 | No | ||
| telephone2 | No | ||
| approver_id | No | ||
| department_id | No | ||
| email_address | No | ||
| has_public_holidays | No | ||
| public_holiday_set_id | No | ||
| emergency_contact_name | No | ||
| emergency_contact_phone | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, description must disclose behavior. It notes partial update but omits side effects, authentication needs, error handling, or success/failure responses.
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?
Starts with a clear, front-loaded purpose. The Arg list is somewhat redundant given the schema, but overall efficient.
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?
High parameter count and no output schema demand thorough description. Missing validation, constraints, return value, and permissions. Incomplete for safe 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 coverage is 0%, yet description covers only 5 of 23 parameters with specific notes (e.g., email_address can be cleared). The rest are dismissed as 'map directly' without further detail.
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 'Edit a user' with partial update semantics. It distinguishes from sibling tools like 'add_user' (create) and 'archive_user' (archive).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies usage when editing an existing user, but does not explicitly state when to use vs. alternatives (e.g., add_user for creation). No exclusion criteria or prerequisites mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a single department by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| department_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It implies a read-only operation, but does not disclose permissions required, error behavior (e.g., if ID not found), or return format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that conveys the essential purpose without any extraneous text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (1 parameter, no output schema), the description covers the basic purpose but lacks details about return values, error handling, or usage context. It is minimally 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?
The schema has 0% description coverage, meaning no parameter descriptions. The tool description adds no additional meaning to the 'department_id' parameter beyond its name and type. For a single integer parameter, this is adequate but not helpful.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get a single department') and the key parameter (by ID). It distinguishes from sibling tools like list_departments (multiple) and add/edit/delete (mutations). However, it does not specify the system or context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs. alternatives. For example, when to use get_department vs. list_departments or other retrieval tools is not addressed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a single holiday (leave booking) by its ID.
| Name | Required | Description | Default |
|---|---|---|---|
| filter | No | ||
| holiday_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description bears full burden. 'Get' implies a read-only operation with no side effects. However, it does not disclose behavior on missing IDs, required permissions, or return format. For a simple retrieval, transparency is adequate but not exemplary.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that directly states the tool's purpose with no extraneous words. However, it lacks structure such as parameter explanations or usage notes.
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 output schema and parameter descriptions, the description is insufficient for an agent to fully understand the tool's behavior. It does not explain the return value, error cases, or how to use the filter parameter.
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 has 0% description coverage. The description only explains 'holiday_id' by association, but the optional 'filter' parameter is not mentioned at all. This leaves the agent unaware of how to use the filter parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and the resource 'a single holiday (leave booking) by its ID'. It distinguishes from sibling tools like list_holidays which would list multiple holidays.
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 use when you have a specific ID, but it does not explicitly state when to use this tool versus alternatives like list_holidays or book_holiday. No exclusions or prerequisites are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a single leave type by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| leave_type_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. Description only states basic retrieval, without disclosing error handling, permissions, idempotency, or behavior when ID does not exist.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with no waste. Appropriate length for a simple retrieval tool, though could add a bit more detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-parameter retrieval tool with no output schema, the description is adequate but would benefit from indicating what is returned (e.g., leave type object) and error conditions.
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%. Description does not explain the leave_type_id parameter beyond what the schema already provides. No additional context 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?
Description clearly states the action ('Get') and resource ('a single leave type by ID'), distinguishing it from sibling tools that list or create leave types.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like list_leave_types. Does not mention that ID is required or that it retrieves a single item.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a single public holiday by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| public_holiday_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries full burden. It only states 'Get', implying a read-only operation, but does not disclose any behavioral traits such as safety (e.g., no side effects), permissions, or rate limits. The description is too brief to provide meaningful transparency beyond the obvious.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, consisting of a single sentence. It is front-loaded and contains no wasted words. However, it may be too brief, potentially missing useful context that could be added without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (one parameter, no output schema), the description provides the essential purpose. However, it omits any indication of the return value or the structure of the response. With no output schema, this gap could be filled with a brief mention. The description feels minimally adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has one parameter (public_holiday_id) with no description, and the schema coverage is 0%. The description only mentions 'by ID' without elaborating on the type, format, or how to obtain the ID. The description adds minimal value over the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get') and the resource ('a single public holiday'), specifying retrieval by ID. This distinguishes it from list_public_holidays, which likely returns multiple. However, it does not mention what information is returned, which could reduce clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance is provided on when to use this tool versus alternatives like list_public_holidays or assign_public_holidays_to_user. The context of retrieving a single holiday by ID is implied, but without explicit when-to-use or when-not-to-use instructions, the agent may not choose optimally.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a user by ID, including work schedule and allowance breakdown.
| Name | Required | Description | Default |
|---|---|---|---|
| user_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description uses 'Get' to imply a read operation, but with no annotations provided, it fails to disclose behavioral traits like authentication needs, rate limits, or whether the user must be active. The description does not compensate for the missing 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 a single, clear sentence that is front-loaded with the main action and key details. No redundant words; every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description partially compensates by specifying the included data (work schedule, allowance breakdown). However, it does not describe the return format, pagination, or error handling. For a read tool with many siblings, more context would improve completeness.
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 adds no meaning beyond the schema; it does not explain what the user_id parameter represents or how to obtain it. The agent receives no additional context about the parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get', the resource 'a user by ID', and the included data (work schedule and allowance breakdown). This distinguishes it from sibling tools like list_users (list all) or get_user_allowance (only allowance).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as get_user_allowance, get_user_contact, or list_users. The description does not mention 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 allowances, TOIL and carry-forward for one user.
Args: user_id: The user to query. year: Restrict to a single year. Omit for all years.
| Name | Required | Description | Default |
|---|---|---|---|
| year | No | ||
| user_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Discloses it retrieves data without side effects, but does not elaborate on read-only nature, authorization needs, or rate limits.
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?
Concise with clear argument listing; efficient but could be slightly more compact by integrating parameter descriptions into one line.
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?
Covers basic functionality and two parameters, but lacks output schema, so missing detail on return shape. Adequate for a simple retrieval 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?
Description adds meaning beyond the schema: explains that 'user_id' is the user to query and that omitting 'year' returns all years. Schema only shows type and default.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb 'Get' specifies resource 'allowances, TOIL and carry-forward for one user'. Differentiates from sibling 'list_all_allowances' which retrieves for all users.
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?
Implied usage for single-user allowance queries, but does not explicitly mention alternatives like 'list_all_allowances' for multiple users or 'update_user_allowance' for modifications.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a user with contact-tab details (address, phone, emergency contact).
Requires a Timetastic Pro account.
| Name | Required | Description | Default |
|---|---|---|---|
| user_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries burden. It adds one behavioral trait: requires a Pro account. However, it does not disclose whether the operation is read-only, error handling for missing user, or other side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences: first defines purpose, second states a requirement. No unnecessary words, front-loaded with key action.
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 1-parameter retrieval tool with no output schema or annotations, the description provides essential purpose and a key constraint. Could be improved by summarizing the response structure, but not strictly necessary.
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 has one required integer parameter 'user_id' with 0% coverage. The description does not explain the parameter, but the parameter name is self-explanatory. Baseline score of 3 is appropriate given minimal need for additional 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 clearly states the verb 'Get' and the resource 'user with contact-tab details', specifying the included fields (address, phone, emergency contact). It distinguishes from sibling tool 'get_user' by emphasizing contact details, but could be more explicit.
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 only mentions a prerequisite (Timetastic Pro account). No guidance on when to use this tool versus alternatives like 'get_user', nor when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a chronological list of who is off between two dates.
The single best endpoint for "who is off on/around a given day" — it merges bookings, non-working days, public holidays and (optionally) other events without needing multiple queries.
Args:
start: Start date, ISO format YYYY-MM-DD.
end: End date, ISO format YYYY-MM-DD. Max 31 days after start.
query_type: What to include. AllAbsences (bookings, public holidays
and non-working days), Bookings, PublicHolidays or
AllEvents (also birthdays, work anniversaries and locked dates).
Rate limited to 1 request per second; limited to a 31-day range.
| Name | Required | Description | Default |
|---|---|---|---|
| end | Yes | ||
| start | Yes | ||
| query_type | No | AllAbsences |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses rate limiting (1 req/s) and a 31-day max range, which are key behavioral constraints. It does not mention safety (read-only/destructive) or authentication requirements, but for a list endpoint these are less critical.
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 moderately concise and well-structured, with a brief introduction, a usage recommendation, and a bulleted Args section. A small amount of redundancy exists (rate limit mentioned twice), but overall efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description still provides enough context for correct invocation: parameter formats, constraints, and usage guidance. It could be enhanced by describing the expected return structure, but for a list tool with simple parameters this is adequate.
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%, but the description provides detailed parameter semantics: start/end date formats (ISO YYYY-MM-DD) and range constraint (max 31 days), plus enumerations for query_type with clear meanings. This fully compensates for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves a chronological list of absences between two dates, with a specific verb 'get' and resource 'list of who is off'. It distinguishes itself from siblings by merging multiple types of absences (bookings, holidays, events) into one query.
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 frames this as 'the single best endpoint' for checking who is off on a given day, and explains it avoids multiple queries. It also describes the query_type parameter to refine the scope, but does not explicitly mention when not to use it or alternative tools for specific cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List allowances, TOIL and carry-forward for all users.
Args: year: Restrict to a single year. Omit for all years.
| Name | Required | Description | Default |
|---|---|---|---|
| year | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses the operation type (list) and data types (allowances, TOIL, carry-forward), but omits details like read-only nature, pagination, ordering, or potential rate limits. The description is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with front-loaded purpose. Every sentence provides distinct value: the first states the tool's function, the second explains the optional parameter. No waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with one optional parameter and no output schema, the description is complete enough. It states what is listed and how to filter by year. It could mention return structure or ordering, but not strictly necessary given simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description must add meaning. It explains the 'year' parameter: 'Restrict to a single year. Omit for all years.' This adds clarity beyond the schema's default null. Since only one parameter exists and it's well described, score is high.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' and the resources 'allowances, TOIL and carry-forward for all users'. It distinguishes from sibling tools like get_user_allowance (per-user) and update_user_allowance (mutation) by specifying the scope 'all users'.
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 guidance on the optional 'year' parameter (restrict to a single year or omit for all), but does not compare with siblings or state when to use this tool versus others like list_absences or list_holidays.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all departments in the organisation.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, but the description implies a read-only operation. No additional behavioral traits (e.g., permissions, pagination) are mentioned, but the simplicity of the tool makes this acceptable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with no superfluous words. The key information is front-loaded. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (0 parameters, no output schema), the description is complete. It tells the agent exactly what it does without needing further elaboration.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, so schema coverage is 100% by default. The description adds no parameter information, which is fine. Baseline score for 0 parameters is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' and the resource 'departments' with the scope 'all in the organisation'. It differentiates from siblings like get_department (single) and add_department (create).
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 implied usage is to retrieve all departments, but there is no explicit guidance on when to use it versus alternatives or any exclusions. It's adequate for a straightforward list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Query leave bookings ("holidays") for the organisation.
All filters are optional. Results are paginated at 100 per page — use
page_number and read totalRecords/nextPageLink in the response.
Args:
start: Include holidays on or after this date-time (ISO 8601).
end: Include holidays before and including this date-time (ISO 8601).
status: Filter by status. Defaults to pending + approved if omitted.
user_ids: Comma-separated user IDs to include (e.g. "12,34").
exclusion_user_ids: Comma-separated user IDs to exclude.
department_id: Only holidays for this department.
leave_type_id: Only holidays of this leave type.
approver_id: Only holidays approved by this user.
my_team_only: Restrict to the team of this user ID.
my_favourites_only: Restrict to the favourite users of this user ID.
department_managers_only: Only holidays for department managers.
non_archived_users_only: Exclude archived users.
transaction_year: Filter to this transaction year.
page_number: Page to fetch (defaults to 1).
| Name | Required | Description | Default |
|---|---|---|---|
| end | No | ||
| start | No | ||
| status | No | ||
| user_ids | No | ||
| approver_id | No | ||
| page_number | No | ||
| my_team_only | No | ||
| department_id | No | ||
| leave_type_id | No | ||
| transaction_year | No | ||
| exclusion_user_ids | No | ||
| my_favourites_only | No | ||
| non_archived_users_only | No | ||
| department_managers_only | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses pagination (100 per page, totalRecords/nextPageLink) and optional filters. However, it does not mention authorization, rate limits, or performance implications.
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 well-structured with a clear intro and per-parameter explanations. It is front-loaded with purpose and pagination. Slightly verbose, but every part adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 14 optional parameters and no output schema, the description covers pagination and all filters. It mentions response fields (totalRecords/nextPageLink), but lacks details on the structure of individual holiday records.
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 provides detailed semantics for all 14 parameters (e.g., 'start: Include holidays on or after this date-time (ISO 8601)'). This adds significant value beyond schema field 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 clearly states 'Query leave bookings ("holidays") for the organisation.' The verb 'query' is precise for a list operation, and it distinguishes from siblings like book_holiday (create) and get_holiday (single).
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 says 'All filters are optional.' and explains pagination. It implies usage for listing holidays, but does not explicitly contrast with siblings like list_absences or provide when-not-to-use scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the valid colour hex codes for leave types.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
List operation implies read-only, but no explicit behavioral disclosure beyond that. No annotations to supplement, but the tool is simple.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single, clear sentence with no unnecessary 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?
For a parameterless list tool with no output schema, the description covers all needed information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters; schema coverage 100% with empty schema. Description adds no param details but doesn't need to.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb 'List' and resource 'valid colour hex codes for leave types', distinguishing it from siblings like list_leave_types.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives like list_leave_types or list_leave_type_icons, but the purpose is self-evident for a simple listing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the valid icon names for leave types (empty string = no icon).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explains the output (icon names) and the meaning of an empty string. As a read-only list with no annotations, this is adequate, though it does not mention potential side effects (unlikely here).
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?
A single, concise sentence that is front-loaded with the action and intended result. Every word is necessary and clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with no parameters and no output schema, the description fully covers what the agent needs to know: what it returns and the special case of empty string.
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 zero parameters and 100% schema coverage, the description adds significant value by explaining the output semantics (valid icon names, empty string meaning). This goes well beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists valid icon names for leave types, distinguishing it from sibling tools like list_leave_type_colors. It also clarifies that an empty string signifies no icon, adding specificity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
While no explicit when-to-use or when-not-to-use guidance is given, the context of sibling tools (e.g., list_leave_type_colors) makes its purpose clear. However, a brief exclusion note could improve it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List leave types for the organisation.
Args: include_inactive: Also return inactive (deleted) leave types.
| Name | Required | Description | Default |
|---|---|---|---|
| include_inactive | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose behavioral traits such as pagination, ordering, permission requirements, or error handling. It only hints at the default behavior via the parameter description (active only unless include_inactive=true).
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 efficiently short, front-loading the main action. However, it sacrifices some completeness for brevity, leaving out potential usage and behavioral details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (1 boolean parameter, no output schema), the description covers the basic purpose and parameter behavior. However, it lacks guidance on when to use this tool and any behavioral pitfalls, making it minimally 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?
The description adds meaningful context to the parameter 'include_inactive' by explaining it returns inactive (deleted) types, beyond the schema's title. However, with 0% schema coverage, the description could provide more detail on parameter usage.
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 'List leave types for the organisation' with a specific verb and resource, and the parameter 'include_inactive' clarifies scope. It effectively distinguishes from sibling tools like 'get_leave_type', 'create_leave_type', and 'delete_leave_type'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives (e.g., 'get_leave_type' for a single type). There is no mention of prerequisites or context for listing leave types.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all locked dates (periods where booking time off is blocked).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It states 'list all locked dates' but does not detail behavior such as whether results are paginated, if any filters apply, or if authentication is required. For a list tool, this is minimally acceptable but lacks transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that clearly communicates the tool's purpose without any fluff. It is front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no parameters, no output schema, and is a simple list operation, the description is adequate. However, it could mention the expected output format or provide more context about when to use it. It meets the minimum viable standard.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no parameters, so the description provides additional context by explaining what locked dates are. This adds value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'list' and the resource 'locked dates', and explains what locked dates are (periods where booking time off is blocked). It distinguishes from siblings like add_locked_date and delete_locked_date.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. For example, it does not mention that this is a read-only operation or that it complements add_locked_date and delete_locked_date. Sibling tools include other list operations, but no differentiation is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all countries available for public holidays.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but the description is honest about listing countries. For a zero-parameter read operation, it adequately communicates behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with no wasted words. Efficient and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has zero parameters and no output schema; description fully covers purpose. No missing details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters; baseline 4 per rule. Schema coverage is 100%.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb 'list' and resource 'countries available for public holidays'. It distinguishes from sibling 'list_public_holidays' which lists holidays for a specific country.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or alternatives provided. The description is minimal, but the tool's purpose is straightforward.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List public holidays for the organisation.
Args: country_code: Filter to a country code. year: Filter to a year. user_id: Filter to a user's public holidays. bank_holiday_set_id: Filter to a bank holiday set. use_org_leave_year: Use the user's leave year instead of calendar year.
| Name | Required | Description | Default |
|---|---|---|---|
| year | No | ||
| user_id | No | ||
| country_code | No | ||
| use_org_leave_year | No | ||
| bank_holiday_set_id | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description does not disclose read-only nature, authorization needs, rate limits, or any side effects. Fails to add behavioral context beyond the operation name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise with front-loaded purpose and well-structured argument list. Every sentence serves a purpose with 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?
With 5 parameters, no output schema, and no annotations, the description fails to explain return format, default behavior, or ordering. Incomplete for a tool of this complexity.
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 0%; description lists parameters with minimal filters like 'Filter to a country code' but lacks detailed semantics for 'bank_holiday_set_id' or 'use_org_leave_year'. Insufficient compensation for missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States 'List public holidays for the organisation' with clear verb and resource. Distinguishes from siblings like 'get_public_holiday' and 'assign_public_holidays_to_user'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool vs alternatives like 'get_public_holiday'. No 'when not to use' context provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List users in the organisation, optionally filtered by department.
Args: department_id: Only users in this department. include_archived_users: Include archived users in the results. only_show_archived_users: If archived users are included, show ONLY them.
| Name | Required | Description | Default |
|---|---|---|---|
| department_id | No | ||
| include_archived_users | No | ||
| only_show_archived_users | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries full burden. It does not disclose behavioral traits such as pagination, read-only nature, performance considerations, or any side effects. Minimal behavioral information beyond listing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with a clear docstring format for parameters. No unnecessary words, though the structure could be slightly tighter.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description does not explain the return structure (e.g., user objects with fields). Parameter semantics are covered, but overall context for what the user gets is lacking. Adequate for a simple list tool but incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds detailed explanations for all three parameters (department_id, include_archived_users, only_show_archived_users) beyond the schema, which only has titles and defaults. However, the explanations are straightforward and add value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List users in the organisation, optionally filtered by department,' which is a specific verb+resource and distinguishes it from sibling tools like get_user (single user) or add_user.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives (e.g., get_user, archive_user). The description does not mention exclusions or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List recent webhook events (up to 30 days of history are retained).
Args: days_history: How many days of history to return (defaults to 1).
| Name | Required | Description | Default |
|---|---|---|---|
| days_history | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses that events are retained for up to 30 days, which is a key behavioral constraint. It also explains the days_history parameter. Lacks details on pagination or event structure, but acceptable for a simple list tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise: two sentences and an args line. It front-loads the purpose and every sentence adds value. No unnecessary 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 tool's simplicity (one parameter, no output schema), the description is mostly complete but lacks information about the return format (e.g., what fields are in each event) and any limits beyond the retention policy. Somewhat adequate but could be improved.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, so the description must compensate. It explains the days_history parameter as 'How many days of history to return (defaults to 1)', adding meaning beyond the schema's type and default. This is adequate compensation.
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 'List recent webhook events', which is a specific verb-resource pair. It also mentions a retention policy of 30 days, distinguishing from siblings that deal with different entities (holidays, users, 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 does not provide explicit guidance on when to use this tool versus alternatives. Since no sibling tools are for webhook events, usage is implied but no when-not-to-use criteria are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Restore an archived user so they can use Timetastic again.
| Name | Required | Description | Default |
|---|---|---|---|
| user_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description only states the action without detailing behavioral effects such as whether it restores permissions, schedules, or requires the user to be currently archived.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence that conveys the essential purpose without superfluous 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 low complexity (one parameter, no output schema), the description adequately conveys the purpose. It lacks some behavioral detail but is sufficient for a simple restore 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 single required parameter (user_id) is obvious from the schema, and the description adds no further meaning. With 0% schema coverage, the description does not compensate, but the parameter is self-explanatory.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('restore'), the resource ('archived user'), and the outcome ('so they can use Timetastic again'). It directly distinguishes from sibling tools like archive_user.
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 context (when a user is archived and needs reactivation) but provides no explicit guidance on when not to use it or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing leave type (admins only). name is required.
| Name | Required | Description | Default |
|---|---|---|---|
| icon | No | ||
| name | Yes | ||
| color | No | ||
| deducted | No | ||
| is_private | No | ||
| limit_days | No | ||
| limit_hours | No | ||
| leave_type_id | Yes | ||
| include_max_off | No | ||
| requires_approval | No | ||
| calendar_visibility | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must carry the full behavioral burden. It only states 'admins only' and that 'name is required', but does not disclose whether the update is partial or requires full replacement, or any side effects. Behavioral details are insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is highly concise at one sentence, front-loading the verb, resource, and access constraint. It uses backticks for 'name', but overall format is clean. Could be slightly expanded without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 11 parameters, no output schema, and 0% schema coverage, the description is severely incomplete. It does not explain return values, update behavior (partial vs full), error conditions, or how optional parameters work. The tool is under-documented for an agent to use reliably.
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 should add meaning. However, it only repeats that 'name is required' (already in schema) and provides no explanation for the other 10 parameters, such as 'icon', 'color', or 'deducted'. Parameter semantics are almost entirely absent.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Update'), the resource ('existing leave type'), and specifies an access constraint ('admins only'). This effectively distinguishes it from sibling tools like 'create_leave_type' and 'delete_leave_type'.
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 mentions 'admins only' to indicate the user role, but does not provide explicit guidance on when to use this tool versus alternatives or when not to use it. The purpose is clear, but context for decision-making is minimal.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set a user's annual allowance for a year.
Args: user_id: The user to update. year: The year to update. amount: The new allowance (0–8784).
| Name | Required | Description | Default |
|---|---|---|---|
| year | Yes | ||
| amount | Yes | ||
| user_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but the description indicates it is a write operation ('Set') and includes a range constraint for amount (0–8784). It does not disclose potential side effects or error conditions, but is minimally transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with one sentence plus a brief argument list, containing no redundant or unnecessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description lacks details about return values or permissions, and with no output schema, agents might need more context. However, for a simple update tool, it is reasonably 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 0%, but the description explains each parameter's purpose (user_id, year, amount) and adds a range for amount, providing meaningful context beyond the input 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 uses a specific verb 'Set' and identifies the resource 'user's annual allowance for a year', clearly distinguishing it from sibling tools like get_user_allowance (read) and list_all_allowances (list).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when or when not to use this tool versus alternatives, but the verb 'Set' implies it is for updating allowances, which is adequate for a simple tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set a user's carry-forward amount for a year (0–5000).
| Name | Required | Description | Default |
|---|---|---|---|
| year | Yes | ||
| amount | Yes | ||
| user_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description provides no behavioral details beyond the 'Set' action. No annotations exist, so the description carries full burden. It fails to disclose idempotency, side effects (e.g., overwriting previous carry-forward), or impact on related data like allowances. Minimal transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence with no redundancy. It front-loads the purpose. However, it could include brief parameter constraints without harming conciseness. Still, it earns a high score for being efficient.
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 3 required parameters, 0% schema coverage, no output schema, and no annotations, the description is severely incomplete. It lacks details on return value, error conditions, and behavior beyond a vague 'Set'. For a mutation tool, this is insufficient for correct 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% and the description adds no explanation for any of the three parameters. The amount range is mentioned (0-5000), but units, year format, and valid ranges for year and user_id are absent. Agents have no semantic guidance beyond parameter names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (Set), resource (carry-forward amount), and target (user for a year). The range (0-5000) adds specificity. However, it does not differentiate from potentially overlapping sibling tools like update_user_allowance, which might also involve carry-forward.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives, no prerequisites (e.g., user existence, valid year), and no context about the effect on existing values. Agents must infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing TOIL entry (-5000 to 5000).
| Name | Required | Description | Default |
|---|---|---|---|
| year | Yes | ||
| amount | Yes | ||
| toil_id | Yes | ||
| user_id | Yes | ||
| description | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It only says 'update' indicating mutation, but fails to disclose whether the operation is idempotent, partial vs full replacement, or error handling if the entry does not exist. The range hint suggests validation but not behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence, minimal verbosity. The range constraint is a useful addition. However, the conciseness sacrifices necessary detail; still, it earns its place as efficient rather than wordy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 5 parameters, no output schema, and no annotations, the description is underspecified. It lacks information about return values, prerequisites (e.g., entry must exist), error scenarios, and effect on related data (e.g., allowance updates). Complements the schema poorly.
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 0% schema coverage, the description adds no parameter-specific details except an implied range for amount. The other four parameters (user_id, year, toil_id, description) are completely undefined in the description, leaving the agent to infer from names alone.
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 'Update an existing TOIL entry', specifying the verb and resource. It also adds a numeric range constraint (-5000 to 5000) that hints at amount limits. However, it does not distinguish from sibling tools like add_user_toil or delete_user_toil.
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 only the amount range, implying a constraint but not when to use this tool vs alternatives (e.g., add vs update vs delete). No explicit context or exclusions are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.0.1action_holidayadd_departmentadd_locked_dateadd_useradd_user_toilarchive_userassign_public_holidays_to_userbook_holidaycreate_leave_typedelete_departmentdelete_leave_typedelete_locked_datedelete_user_toiledit_departmentedit_userget_departmentget_holidayget_leave_typeget_public_holidayget_userget_user_allowanceget_user_contactlist_absenceslist_all_allowanceslist_departmentslist_holidayslist_leave_type_colorslist_leave_type_iconslist_leave_typeslist_locked_dateslist_public_holiday_countrieslist_public_holidayslist_userslist_webhook_eventsrestore_userupdate_leave_typeupdate_user_allowanceupdate_user_carry_forwardupdate_user_toilEach tool targets a distinct resource and action (e.g., book vs approve vs list holidays, CRUD for users, departments, leave types, etc.). Descriptions are clear, and overlapping concepts are differentiated by purpose (e.g., list_absences vs list_holidays).
All tools follow a consistent verb_noun pattern in snake_case (e.g., add_user, get_holiday, delete_leave_type). No mixing of conventions or irregular naming.
At 39 tools, the set is larger than typical but justified by the comprehensive scope of leave management (users, departments, holidays, leave types, public holidays, TOIL, allowances, webhooks). Could be slightly consolidated but remains well-organized.
The tool set covers full lifecycle management: CRUD for all entities (users, departments, leave types, locked dates), booking and managing holidays, handling TOIL and allowances, public holidays, and even webhook events. No obvious gaps for the domain.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
MCP server providing attendance data queries via the CloudTime API.
A basic MCP server to operate on the Postman API.
MCP server for Cronofy — read calendars, events and free/busy, and create, update or delete events.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/mlequime/timetastic-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server