> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ontime.hosai.app/llms.txt
> Use this file to discover all available pages before exploring further.
# Quickstart for agents
> Conventions, discovery and safety rules for an AI agent operating OnTime through MCP.
This page is written **for the agent**. If you are a human setting up a connector, start at [Connect a client](/ai-mcp/connect/claude) instead.
## Endpoint and auth
```text theme={null}
POST https://app.ontime.hosai.app/api/mcp
Authorization: Bearer ont_… (or an oat_… OAuth access token)
```
JSON-RPC. Standard MCP `tools/list` and `tools/call`.
## Ground yourself first
**Call `ontime_whoami` before anything else.** It is not optional politeness — nearly every mistake an agent makes on this API comes from not knowing who it is.
It tells you:
| Field | Why it matters |
| ---------------------- | ----------------------------------------------------------------------------------------------------- |
| **`kind`** | `employee` or `service`. A service credential cannot call self-service or scope-checked tools at all. |
| **The bound employee** | Who "me" means. Every `my_*` tool refers to this person. |
| **`permissions`** | Which tools you can call. A tool absent from `tools/list` is absent because of this. |
| **`readOnly`** | If true, every mutating tool is hidden. |
It also tells you the organization and today's date in the organization's timezone, which you need for date arithmetic.
## Discovery
`tools/list` returns exactly what your credential can call. **There is no hidden surface** — listing and calling share the same predicate, so an invisible tool is an uncallable one. Do not guess at tool names you cannot see.
A generic search across the organization. Returns records with identifiers you can then act on.
Retrieves a single record by the identifier `search` returned.
The `search` and `fetch` pair exists for hosts that expect that shape (ChatGPT's deep research, among others). If you have the specific tools available — `ontime_employee_search`, `ontime_leave_get` — prefer them; they return richer, better-typed results.
## Self-service versus on-behalf
**Most domains are two separate tools, not one tool with an optional `employeeId`.**
This is the single most common source of agent errors on this API. `ontime_leave_request` files leave for **you**. `ontime_leave_request_for` files it for **somebody else** and needs `leave:approve`.
Picking the wrong one does not silently do the right thing — it either fails, or files correctly against the wrong person.
| For yourself | On behalf of someone |
| ---------------------------------------- | ----------------------------------- |
| `ontime_leave_request` | `ontime_leave_request_for` |
| `ontime_regularization_request` | `ontime_regularization_request_for` |
| `ontime_attendance_my_day` / `_my_month` | `ontime_attendance_day_report` |
| `ontime_my_pay` / `ontime_my_payslip` | `ontime_payslips` |
| `ontime_overtime_mine` | `ontime_team_report` |
Decide which you are doing **before** choosing the tool.
## Conventions
`YYYY-MM-DD` for a date, `YYYY-MM` for a month. Always. Never a locale format, never a natural-language date.
Use the current date from `ontime_whoami` — the organization's timezone is what matters, not yours.
Employees are identified by UUID, not by employee code or name. Resolve a name to an ID with `ontime_employee_search` first.
Never construct or guess an ID.
List tools return a page. Check the total against what you have before concluding a queue is empty.
A failing mutation returns the domain's own error verbatim — `"bad_stage" (HTTP 409): …`. **Read it and change your input.** Retrying the same call produces the same failure.
## Confirm-gated writes
**Four tools require an explicit human "yes" in the conversation before you call them.** They are consequential and hard to reverse:
* `ontime_payroll_disburse` — creates payslips and closes the cycle. Not reversible.
* `ontime_compliance_file` — records a statutory return as filed.
* `ontime_form16_generate` — generates tax certificates for a whole financial year.
* `ontime_holiday_delete` — removes a holiday, changing how days reconcile.
State what you are about to do, wait for confirmation, then act. Do not infer consent from a general instruction like "run payroll".
## Before any write
Use the matching read tool. Payroll in particular is a state machine — `ontime_payroll_overview` tells you which stage the cycle is at, and calling a stage out of order fails.
If you are acting on somebody, confirm you have the right person. `ontime_employee_get` on the ID you resolved.
A `403` about approval scope means you are not the subject's direct manager and lack `hr:approve`. That is not retryable and not a transitive check — being the manager's manager does not help.
## Things that will not work
* **Approving your own request.** The same-actor rule applies to you as it does to a human.
* **Writing to a frozen payroll month.** Punches and attendance-affecting approvals are refused.
* **Reaching another organization.** Your credential is bound to one.
* **Guessing a tool that is not in `tools/list`.** It is not there because you cannot call it.
## This documentation is machine-readable
Every page on this site has a plain-Markdown twin at the same URL with `.md` appended, and `/llms.txt` indexes the site. Fetch those rather than parsing HTML.