> ## Documentation Index
> Fetch the complete documentation index at: https://docs.a-char.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Tools

> Every tool on the A-Char MCP server, its parameters, and the tools/list call that returns your client's catalog.

The A-Char MCP server has 9 time-off tools. Each tool runs the same code as its
[API endpoint](/introduction), so it takes the same arguments, returns the same data, and follows the same
rules.

## First call

`tools/list` returns the tools your credential can use, each with its description, input schema and
annotations. Your client calls it when it connects; you can call it yourself:

```bash theme={null}
curl https://a-char.com/api/mcp \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer $A_CHAR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}'
```

Response (`200`), abridged to one tool:

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "cancel_time_off",
        "title": "Cancel a time-off request",
        "description": "Cancels a pending, approved or declined request and returns its days to the balance...",
        "inputSchema": {
          "type": "object",
          "properties": {
            "id": { "type": "string" },
            "employee_id": { "type": "string" },
            "note": { "type": "string" }
          },
          "required": ["id"]
        },
        "annotations": { "readOnlyHint": false, "destructiveHint": true, "openWorldHint": false }
      }
    ]
  }
}
```

## Time-off tools

| Tool | Description |
| - | - |
| `get_time_off_balances` | Your balance for every active policy |
| `list_my_time_off` | Your requests and their status |
| `preview_time_off` | Work out a request without creating it |
| `request_time_off` | Book time off |
| `update_time_off` | Change a request |
| `cancel_time_off` | Cancel a request |
| `approve_time_off` | Approve a request waiting on you |
| `decline_time_off` | Decline a request waiting on you |
| `get_time_off_document` | Download an attachment or generated document |

Dates are `YYYY-MM-DD`. Day types are `FULL_DAY`, `AM` (morning) and `PM` (afternoon), for half days.

### get\_time\_off\_balances

Every active policy you are assigned to, with the balance left in the current cycle and the days taken,
requested and accrued. Use a policy's `id` as `policy_id` in the tools below.

| Parameter | Type | Description | Required | Default |
| - | - | - | - | - |
| `employee_id` | string | Read someone else's balances. Needs the admin role or being their approver | No | You |

### list\_my\_time\_off

Your requests with their status (pending, approved, declined, cancelled), dates, days, policy, each
approver's decision and attachments.

| Parameter | Type | Description | Required | Default |
| - | - | - | - | - |
| `employee_id` | string | Read someone else's requests. Needs the admin role or being their approver | No | You |

### preview\_time\_off

Which days count against the balance once weekends and public holidays are left out, how many that is, and
the balance left afterwards. Nothing is created; call it before `request_time_off`.

| Parameter | Type | Description | Required | Default |
| - | - | - | - | - |
| `policy_id` | string | Policy from `get_time_off_balances` | Yes | |
| `start_date` | string | First day | Yes | |
| `end_date` | string | Last day | Yes | |
| `start_date_type` | string | `FULL_DAY`, `AM` or `PM` | No | `FULL_DAY` |
| `end_date_type` | string | `FULL_DAY`, `AM` or `PM` | No | `FULL_DAY` |
| `request_id` | string | When previewing a change to an existing request, so its days are not counted twice | No | |
| `employee_id` | string | Preview for someone else | No | You |

### request\_time\_off

Books time off and notifies the approvers, or approves it straight away when the policy needs no approval.
Rejected when it would overdraw the balance, overlaps another request, misses the notice period, or falls
outside the dates you may book.

| Parameter | Type | Description | Required | Default |
| - | - | - | - | - |
| `policy_id` | string | Policy from `get_time_off_balances` | Yes | |
| `start_date` | string | First day | Yes | |
| `end_date` | string | Last day | Yes | |
| `start_date_type` | string | `FULL_DAY`, `AM` or `PM` | No | `FULL_DAY` |
| `end_date_type` | string | `FULL_DAY`, `AM` or `PM` | No | `FULL_DAY` |
| `note` | string | Note for the approvers. Some policies require one | No | |
| `attachments` | file\[] | Images and PDFs, 4 MB in total. Some policies require one | No | `[]` |
| `employee_id` | string | Book for someone else. Needs the admin role or being their approver | No | You |

### update\_time\_off

Changes a pending or approved request; a changed request goes back to its approvers. Send only what changes.
The policy cannot be changed.

| Parameter | Type | Description | Required | Default |
| - | - | - | - | - |
| `id` | string | The request | Yes | |
| `start_date` | string | New first day | No | Unchanged |
| `end_date` | string | New last day | No | Unchanged |
| `start_date_type` | string | `FULL_DAY`, `AM` or `PM` | No | Unchanged |
| `end_date_type` | string | `FULL_DAY`, `AM` or `PM` | No | Unchanged |
| `note` | string | New note | No | Unchanged |
| `attachments` | file\[] | Files to add | No | `[]` |
| `kept_attachment_paths` | string\[] | Existing attachments to keep | No | All |
| `employee_id` | string | Change someone else's request | No | You |

### cancel\_time\_off

Cancels a pending, approved or declined request and returns its days to the balance. Only an admin can
cancel leave that has already started. Marked destructive.

| Parameter | Type | Description | Required | Default |
| - | - | - | - | - |
| `id` | string | The request | Yes | |
| `note` | string | Reason for cancelling | No | |
| `employee_id` | string | Cancel someone else's request | No | You |

### approve\_time\_off

Records your approval when it is your turn as approver. Once every approver has approved, the days are
deducted and the employee is notified. An admin can approve in place of the approver whose turn it is.
Nobody can approve their own request.

| Parameter | Type | Description | Required | Default |
| - | - | - | - | - |
| `id` | string | The request | Yes | |

### decline\_time\_off

Declines a request waiting on you, returns its days to the balance and notifies the employee. Marked
destructive.

| Parameter | Type | Description | Required | Default |
| - | - | - | - | - |
| `id` | string | The request | Yes | |
| `note` | string | Reason, shown to the employee | Yes | |

### get\_time\_off\_document

Returns an attachment, or the generated request, approval or decline document, of a request. Open to the
request's employee, its approvers and admins.

| Parameter | Type | Description | Required | Default |
| - | - | - | - | - |
| `id` | string | Document `id` from the request's `time_off_documents` in `list_my_time_off` | Yes | |

## How it behaves

### Your credential decides the catalog

`tools/list` only returns tools your credential's scopes allow, capped by your role. A tool you cannot use
is not listed at all, so it never costs the assistant context.

### Destructive tools are marked

`cancel_time_off` and `decline_time_off` carry `destructiveHint: true`, and read tools carry `readOnlyHint: true`.
Clients that honour the hints ask before running a destructive tool and may run read tools without asking.

### Errors come back as tool results

A rejected call returns `isError: true` with the reason as text, the same message A-Char shows, for example
`You already have a time off request for the period 22 December 2026 to 23 December 2026. Please adjust
your request.` The assistant can explain it or retry with other arguments. An unexpected failure returns
`Something went wrong. Try again later.`

### Documents come back as files

`get_time_off_document` returns images as MCP image content and PDFs as an embedded resource, so clients
that render them show the document inline.

### `employee_id` acts for someone else

Time-off tools default to you. Passing `employee_id` acts for that person, and only works when you are an
admin or their approver.

## Related

* [MCP](/mcp): a first tool call over plain HTTP and how the server behaves.
* [Setup](/mcp/setup): per-client configuration, API keys, and fixes when it fails.
* [API reference](/introduction): the endpoint behind every tool.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.