Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@officient-mcp show me who is on leave this week"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An MCP server for the Officient HR API (https://api.officient.io), so an AI assistant such as Claude Code can read people, calendars, contracts, expenses, documents, fleet and webhooks — and book time off — through typed tools instead of raw HTTP.
It ships the complete Officient API surface without dumping 99 tool definitions into your context:
2 discovery tools that read a bundled copy of the API spec (no network, no scopes needed).
1 generic escape hatch (officient_request) that can call any documented endpoint, validated against the spec before it fires.
21 curated, typed tools for the workflows people actually use every day.
Node.js 20 or newer
An Officient access token (see below)
Related MCP server: Tipsoi MCP
git clone <this-repo> officient-mcp
cd officient-mcp
npm install # runs the build automatically
npm run build # or build again by hand
npm test # build + unit/integration tests, no network callsThere is no OAuth flow here. Claude Code's OAuth support is for HTTP and SSE servers only — a stdio server cannot participate in it. This server manages its own credential, which means a long-lived personal access token that you generate and rotate yourself.
Log in to Officient as an admin.
Open the avatar menu (top right) → Developers, i.e. https://<your-tenant>.officient.io/developer.
Create a client app if you do not have one, then Manage app → Generate access token and pick an expiry. Copy the token immediately — Officient shows it once.
Put it in the environment as OFFICIENT_ACCESS_TOKEN (see Connecting it to Claude Code).
Diary the expiry. When the token lapses, generate a new one the same way; nothing else changes.
This trips everyone up: you do not choose scopes while generating a token. Scopes are configured on the client app, under Manage app → Edit scopes. A token inherits whatever the app had ticked at the moment it was issued.
So if a call comes back with HTTP 401 and {"error":"insufficient_scope"}, the token is fine —
the app was never granted that scope. The fix is:
Manage app → Edit scopes, tick the scope you need.
Generate a fresh access token (existing tokens do not pick up newly added scopes).
Update OFFICIENT_ACCESS_TOKEN and restart the server.
A plain 401 without insufficient_scope is the other problem entirely: the token itself is invalid,
revoked or expired.
Officient scopes are <object>:<action>, e.g. calendar:read. Grant the app only what you need:
Scope | Unlocks |
| people list, teams, assets, fleet, roles |
| person detail, people search |
| calendars, event types, days-off requests |
| adding / overwriting / deleting calendar events |
| weekly schedules |
| contracts |
| documents (Officient spells these with a dot) |
| expenses |
| wages, cost centers, cost units, departments, functions |
| custom fields on a person |
| webhook subscriptions |
Every tool description names the scope it needs. officient_describe_endpoint does the same for all 99 endpoints.
Configuration comes from environment variables only. A local .env is loaded for development (see .env.example).
Variable | Required | Default | Meaning |
| yes | — | Bearer token; the server refuses to start without it |
| no |
| Override for sandboxes/proxies |
| no |
| Per-request timeout in milliseconds |
The token is never logged and is redacted from anything the server prints.
Claude Code has three config scopes. Which one you want depends on whether the config is allowed to touch disk with a secret in it:
Scope | Stored in | Shared? | Use it when |
|
| no | Recommended here. Personal machine, secret-bearing server |
|
| yes, via git | A team shares the config; the token must come from each dev's shell |
|
| no, but all your projects | You want Officient available everywhere you work |
claude mcp add officient --scope local --env OFFICIENT_ACCESS_TOKEN=YOUR_TOKEN_HERE \
-- node /absolute/path/to/officient-mcp/dist/index.jsTwo CLI quirks worth knowing, both verified against Claude Code as of 2026-07:
Put the server name first. --env is variadic, so it swallows the following argument as a
second environment variable. Writing --env KEY=value officient fails with:
Invalid environment variable format: officient,
environment variables should be added as: -e KEY1=value1 -e KEY2=value2--env requires KEY=value. A bare --env OFFICIENT_ACCESS_TOKEN, meaning "pass my shell's
value through", is rejected the same way. If a later version adds passthrough, prefer it.
The trade-off is therefore real and unavoidable on this path: the literal token is persisted in
plaintext in ~/.claude.json, where it survives rotation, ends up in backups, and has to be
scrubbed by hand. If that matters to you, use the project-scoped .mcp.json route below instead —
that one does expand ${OFFICIENT_ACCESS_TOKEN} from the environment, so the secret stays in your
shell profile or password manager and never touches Claude Code's config.
.mcp.jsonThis repo ships a .mcp.json at its root:
{
"mcpServers": {
"officient": {
"type": "stdio",
"command": "node",
"args": ["${CLAUDE_PROJECT_DIR:-.}/dist/index.js"],
"env": {
"OFFICIENT_ACCESS_TOKEN": "${OFFICIENT_ACCESS_TOKEN}"
}
}
}
}Claude Code expands ${VAR} and ${VAR:-default} inside command, args, env, url and
headers, and ${CLAUDE_PROJECT_DIR} resolves to the project root — so the file is committed with
no secret and no absolute path in it. Each developer supplies the token from their own shell:
export OFFICIENT_ACCESS_TOKEN=...
npm install && npm run build # .mcp.json points at dist/, so it must exist
claude # Claude Code prompts once to approve the project serverNever replace ${OFFICIENT_ACCESS_TOKEN} with a literal in this file — it is committed to git.
claude mcp list # should show officient as connected
OFFICIENT_ACCESS_TOKEN=... npm start # or boot it by hand; it stays silent when healthyIf the token is missing, the server writes an actionable message to stderr and exits with code 1. Claude Code does not auto-restart stdio servers, so a crash is visible rather than silently retried. Runtime API failures (401, 429, 4xx) are returned as MCP tool errors instead — the process stays up.
Tool | Purpose |
| Filter all 99 documented endpoints by tag / method / free text; returns compact one-liners including the required scope. Offline. |
| Everything about one |
| Call any endpoint by |
Tool | Purpose | Scope |
| Account behind the current token |
|
| List employees (30/page, zero-indexed) |
|
| Find people by name / email / national number |
|
| Full detail for one employee |
|
| Custom field values on a person |
|
| Current weekly working schedule |
|
| Teams and their members |
|
| One person, one day |
|
| One person, one month |
|
| One person, one year ( |
|
| Custom event types for a year, incl. the id needed to book a custom event |
|
| Days-off requests, filterable by status |
|
| Writes. Add one or more events (day off, sick day, education, overtime) |
|
| Writes. Idempotent upsert of one event of a type on a date |
|
| Writes. Remove one calendar event |
|
| Employment contracts |
|
| Expenses for a year, or one month |
|
| Documents on an employee / asset / car |
|
| Fleet vehicles, optionally by owner |
|
| Company assets, optionally by owner |
|
| Webhook subscriptions |
|
Anything not in this table — wages, budgets, dimonas, cost centers, performance reviews, uploads, person/team/vehicle mutations — is reachable through officient_request. Start with officient_list_endpoints.
Pagination is zero-indexed. ?page=0 is the first page, ?page=1 is the second. 30 items per page. The curated tools default page to 0.
Rate limit: 30 requests per 5 seconds. Officient answers a breach with HTTP 429 and an empty body, and sends no Retry-After header. The server therefore runs a client-side sliding-window limiter: calls beyond the budget are queued, never dropped, and a 429 that still slips through is retried once with backoff before being surfaced.
401 is two different problems. A missing OAuth scope returns HTTP 401 with {"error":"insufficient_scope"} — the token is fine, the app just was not granted that scope; fix it in the developer dashboard and issue a new token. A plain 401 means the token itself is invalid, revoked or expired. The server reports these as kind: "insufficient_scope" and kind: "invalid_token" respectively.
Validation errors carry a human sentence. Officient replies to bad writes with {"status_code": 400, "reason_phrase": "There is already too much time off planned on <date>."}. That phrase is surfaced verbatim.
overwrite-event silently does nothing if only the start time differs. Observed live 2026-07: when an event of the given type already exists on that date with the same duration_minutes, the endpoint returns {"success": 1, "info": "no action taken"} and leaves the event untouched — it does not compare start_time_minutes. Note that success: 1 here means "request accepted", not "your change was applied". To move an existing event's start time you have to fall back to delete-event + add-event, which is exactly the delete-and-add cycle this endpoint was documented to spare you. Read the calendar back after any write rather than trusting success: 1.
A full-day event still needs a sensible start_time_minutes. duration_minutes: "all_day" correctly resolves to the person's scheduled minutes, but the start time is stored as given. Passing 0 yields a full-day event pinned to 00:00, which renders oddly next to events created in the UI. Read an existing event on a normal working day to see the house convention (typically 540, i.e. 09:00).
Team membership is not readable. list-teams returns id and name only — no members, despite what the docs imply — and there is no team-detail endpoint. The org structure lives entirely in the manager relations: walk list-people and call person-manager per person.
person-manager returns the manager, not the pairing. The response is {person_id, person_name, start_date} describing the manager, with nothing identifying whose manager it is. Fan out over several people concurrently and you can only map results back to subjects by request order — so either issue the calls sequentially, or tag each response yourself at the call site. Silently mis-mapping an org chart is an easy and expensive mistake here.
Uploads are base64 JSON, not multipart. Document and avatar endpoints take document_base64 / photo_base64 fields inside a normal JSON body.
Responses are lightly de-enveloped. Officient wraps payloads in a single data key; the server strips exactly that one level and returns compact JSON. Nothing else is filtered and nothing is truncated.
Two tools raise the output cap. Claude Code warns at 10k tokens of tool output and cuts off at 25k
(override with MAX_MCP_OUTPUT_TOKENS). Two tools declare a higher ceiling via
_meta["anthropic/maxResultSizeChars"], because truncating them loses data silently rather than
failing loudly: officient_get_year_calendar (200 000 chars — 365 day entries, each with an events
array) and officient_request (300 000 chars — it can reach any endpoint, so it needs the worst
case covered). Every other tool stays on the client default; the caps were measured, not guessed —
officient_describe_endpoint, for instance, peaks at ~2.6 KB and needs nothing.
The server never writes to stdout. stdout carries the JSON-RPC stream, so a single stray byte
breaks the transport. All diagnostics go to stderr, and installStdoutGuard() repoints every
stdout-writing console method at stderr before config is loaded — dotenv ≥ 17 prints its banner with
console.log and honours DOTENV_CONFIG_DEBUG from the inherited environment, which would otherwise
override the quiet: true this server passes.
npm run harvest # node scripts/harvest-spec.mjsThe harvester refetches every documentation page from https://apidocs.officient.io and writes three
things deterministically, so re-running with no upstream change produces no diff:
Output | Committed? | What it is |
| yes | Flat endpoint index the tools load at runtime |
| yes | Merged OpenAPI 3.1 document |
| no (gitignored) | ~100 documentation pages copied verbatim |
spec/raw/ is Officient's copyrighted documentation, so this repo does not redistribute it: it is
gitignored and excluded from the npm tarball, but kept on disk as the harvester's cache. Run
npm run harvest to regenerate it from the public docs — nothing at runtime ever reads it, so a
fresh clone without spec/raw/ works exactly the same (the test suite asserts both halves of that).
Rebuild afterwards (npm run build) and re-run npm test — the suite asserts that every curated tool
still maps onto a real operationId.
npm run dev # tsc --watch
npm run typecheck # tsc --noEmit
npm test # build + node:test suiteThe test suite makes no real API calls: HTTP is stubbed, and the stdio smoke test boots the server with a dummy token against an unreachable base URL.
MIT — see LICENSE.
Add one or more events (day off, sick day, education, overtime, …) to a person’s calendar. All events in one call must fall in the same year. Set type="custom" together with custom_day_off_type_id from officient_list_event_types; omit that id for sick_day / education. duration_minutes may be the string "all_day". Required scope: calendar:write. WRITES DATA in Officient.
| Name | Required | Description | Default |
|---|---|---|---|
| type | Yes | sick_day, education or custom. | |
| events | Yes | One entry per event. All entries must be in the same year. | |
| person_id | Yes | Officient person id. | |
| custom_day_off_type_id | No | Required when type="custom"; get it from officient_list_event_types. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that it writes data and requires calendar:write scope, aligning with annotations (destructiveHint=true). Adds constraint that all events in one call must be in the same year. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact (two sentences plus key clarifications), front-loaded, and every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers main points: multi-event capability, year constraint, type handling, required scope. No output schema, but description doesn't need return values. Could mention success behavior or error handling, but overall sufficient given annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, baseline 3. Description adds: 'Set type="custom" together with custom_day_off_type_id from officient_list_event_types; omit that id for sick_day / education' and 'duration_minutes may be the string "all_day"', providing extra semantics beyond 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 it adds one or more events (day off, sick day, education, overtime, etc.) to a person's calendar. It specifies constraints like all events in same year and differentiates from sibling tools like overwrite and delete.
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?
Provides context on when to set type='custom' and when to omit custom_day_off_type_id, and mentions required scope. However, it does not explicitly say when not to use this tool or compare with alternatives like overwrite or delete.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Permanently remove one calendar event (e.g. a day off) from a person’s calendar. Get the event_id from a calendar read tool first. Required scope: calendar:write. WRITES DATA in Officient.
| Name | Required | Description | Default |
|---|---|---|---|
| event_id | Yes | Event id as returned by the calendar read tools. | |
| person_id | Yes | Officient person id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint and readOnlyHint. Description adds 'Permanently remove' and 'WRITES DATA' which reinforce but do not add new behavioral context beyond annotations. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the action, no wasted words. Efficient 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?
Sufficient for a simple tool with 2 required params and no output schema. Could mention irreversibility or return value, but not needed given clarity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear descriptions for both parameters. Description adds usage guidance ('Get event_id from read tool') but no new semantic detail beyond schema. Baseline 3.
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?
Clearly states the action (permanently remove) and resource (one calendar event from a person's calendar), with an example (day off). Differentiates from siblings like add and overwrite.
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?
Provides prerequisite (get event_id from read tool) and required scope (calendar:write). Lacks explicit when-not or alternative comparisons, but context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Full detail for one Officient endpoint from the bundled spec (no network call, no scope needed): path/query parameters, request body schema and a worked example, the required OAuth scope, the documentation prose and the doc URL. Use before calling officient_request. READ-ONLY.
| Name | Required | Description | Default |
|---|---|---|---|
| operationId | Yes | Operation id exactly as returned by officient_list_endpoints, e.g. "add-event". |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description complements annotations by confirming the tool is read-only and requires no network call or scope. It lists exactly what information is returned (path/query params, request body schema, example, scope, docs URL). This adds context beyond the annotations, which already indicate readOnlyHint=true. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences long, front-loaded with the core detail and key notes (no network call, no scope). It is concise but includes all important aspects without fluff. Minor improvement could merge the READ-ONLY note into the first sentence, but overall effective.
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 one parameter and no output schema, the description provides sufficient context: what it does, what it returns, and its safe nature. It references the sibling tool 'officient_request' for the intended usage sequence. Complete enough for the agent to use 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 single parameter operationId is described in the schema as 'Operation id exactly as returned by officient_list_endpoints, e.g. "add-event".' The description repeats this nearly verbatim, so it adds no additional semantic meaning. With 100% schema coverage, baseline is 3. No improvement.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: providing full detail for one Officient API endpoint, including parameters, body schema, example, required scope, and docs. It distinguishes itself from siblings like officient_list_endpoints (listing) and officient_request (making requests). The use of 'describe' as verb with 'endpoint' as resource is specific.
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 says 'Use before calling officient_request,' providing clear guidance on when to use the tool. It also notes 'no network call, no scope needed,' which helps the agent understand it's safe and quick. However, it doesn't explicitly state when not to use it or compare with other sibling tools for deeper context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Time off, overtime and scheduled minutes for a single person on a single date. Required scope: calendar:read. READ-ONLY.
| Name | Required | Description | Default |
|---|---|---|---|
| day | Yes | Day of month, 1-31. | |
| year | Yes | Four-digit year, e.g. 2026. | |
| month | Yes | Month, 1-12. | |
| person_id | Yes | Officient person id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark readOnlyHint=true and destructiveHint=false. The description adds that the tool requires 'calendar:read' scope and is 'READ-ONLY', confirming safety and specifying the access level. It also lists the specific returned data (time off, overtime, scheduled minutes), adding value beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no redundant words. The first sentence immediately states the purpose and output, and the second adds security context. Efficiently 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?
No output schema exists, so the description must communicate return values. It mentions three data types but lacks detail on the structure (e.g., whether minutes are totals or per-period). Adequate for a simple single-day query, but incomplete for precise usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear parameter descriptions. The tool description does not elaborate on parameters beyond what the schema provides. Baseline score of 3 is appropriate since the schema carries the semantic load.
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 specifies 'Time off, overtime and scheduled minutes for a single person on a single date.' This clearly states the resource (person's calendar), action (get), and scope (single day), differentiating it from sibling tools like get_month_calendar or get_year_calendar.
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 a single day per request, but does not explicitly mention when not to use it or recommend alternatives like get_month_calendar for multi-day views. With many calendar-related siblings, more explicit guidance would be beneficial.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Time off, overtime and scheduled minutes for a single person for one month. Required scope: calendar:read. READ-ONLY.
| Name | Required | Description | Default |
|---|---|---|---|
| year | Yes | Four-digit year, e.g. 2026. | |
| month | Yes | Month, 1-12. | |
| person_id | Yes | Officient person id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark read-only and non-destructive; description reinforces 'READ-ONLY' and lists the data fields returned (time off, overtime, scheduled minutes), adding behavioral detail beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no fluff. First sentence states what the tool does, second provides scope and read-only hint. 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?
The description is complete for a simple query tool. While no output schema is provided, the description covers the return types (time off, overtime, scheduled minutes). No missing critical 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?
All three parameters are described in the schema with 100% coverage. The description does not add extra meaning beyond what the schema provides, meeting the baseline.
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?
Clearly states it retrieves time off, overtime, and scheduled minutes for a single person for one month. Distinguishes from sibling tools like get_day_calendar and get_year_calendar by specifying monthly granularity.
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?
Uses 'Required scope: calendar:read' to specify authorization needed. Does not explicitly contrast with day or year calendars, but the monthly scope is implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Information about the account behind the current access token (company, user, locale). Required scope: basics:read. READ-ONLY.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true, and the description reinforces with 'READ-ONLY'. Additionally, it adds auth requirement (scope) and expected data fields, providing value beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences convey purpose, data, and requirements. No wasted words; information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers what the tool does and required scope. Lacks explicit output format, but hints at fields. Given simplicity, it's adequate but could specify return structure more.
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 exist, so description does not need to explain them. Baseline 4 applies as per instructions.
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?
Clearly states it returns info about the account behind the access token, listing specific data (company, user, locale). The verb 'get' and resource are explicit, and it distinguishes from sibling tools that focus on other resources.
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?
Specifies required scope 'basics:read'. While it doesn't explicitly contrast with alternatives, the context implies when to use (to get own account info) and no sibling duplicates this function.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Full detail for one employee: personal data, contract summary, team, manager and more. Required scope: personal.info:read. READ-ONLY.
| Name | Required | Description | Default |
|---|---|---|---|
| person_id | Yes | Officient person id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false; the description adds that the scope is required and outlines the data returned (personal data, contract summary, team, manager), adding useful context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no wasted words. The first sentence front-loads the purpose, and the second provides essential scope and read-only note.
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 one simple parameter and no output schema, the description sufficiently lists the kind of information returned and the required scope, making it complete and easy to understand.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 100% coverage for the only parameter 'person_id' with a clear description. The description does not add additional semantic information 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 it retrieves 'Full detail for one employee' including specific categories, and the name 'get_person' distinguishes it from sibling tools like 'list_people' and 'search_people'.
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 the required scope 'personal.info:read' and notes it is READ-ONLY, but does not explicitly mention when not to use or contrast with other tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Custom field values configured on one employee (text, number, date, money, email, select_option). Required scope: personal.info.custom.fields:read. READ-ONLY.
| Name | Required | Description | Default |
|---|---|---|---|
| person_id | Yes | Officient person id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark it as read-only and non-destructive. The description adds the required scope ('personal.info.custom.fields:read') and repeats the read-only nature, providing useful behavioral context beyond 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 extremely concise, using one sentence plus a scope statement. Every part adds value 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?
Although no output schema is present, the description lists the possible custom field types, giving a good sense of return structure. This is sufficient for a simple read tool with clear annotations.
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 covers 100% of the single parameter (person_id) with description 'Officient person id.' The tool description adds no further meaning or formatting details, so it meets the baseline of 3.
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 gets custom field values for one employee, listing the field types (text, number, etc.) and the required scope. This distinguishes it from sibling tools like list_people or get_person.
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 the required OAuth scope and labels the tool as read-only, which helps guide appropriate use. However, it lacks explicit when-to-use or when-not-to-use guidance compared to alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The employee’s current weekly working schedule (scheduled minutes per weekday). Required scope: weekly.schedules:read. READ-ONLY.
| Name | Required | Description | Default |
|---|---|---|---|
| person_id | Yes | Officient person id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavioral details beyond the annotations, such as the required permission scope and that it returns scheduled minutes per weekday. Annotations already declare readOnlyHint=true and destructiveHint=false, so the description reinforces and supplements without contradiction.
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 two short sentences covering purpose, return content, permission scope, and read-only nature. Every word adds value, and no information is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description adequately explains the return format (scheduled minutes per weekday) and required scope. It lacks details on error handling or behavior for invalid inputs, but for a simple read operation with strong annotations, 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?
The input schema has full description coverage (100%) for the single parameter person_id. The description does not add any additional meaning beyond what the schema already provides, so the score is at the baseline of 3.
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 the employee's current weekly working schedule with scheduled minutes per weekday. It distinguishes itself from sibling tools like get_day_calendar and get_month_calendar by specifying the weekly scope.
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 indicates the required permission scope (weekly.schedules:read) and marks the tool as READ-ONLY, providing context for safe usage. However, it does not explicitly mention when not to use this tool or compare it to alternative calendar endpoints.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Every day of the year for one person, each with scheduled_minutes and any events. Use days_with_events to keep the response small. Required scope: calendar:read. READ-ONLY.
| Name | Required | Description | Default |
|---|---|---|---|
| year | Yes | Four-digit year, e.g. 2026. | |
| filter | No | "all" (default) returns every day; "days_with_events" returns only days with events. | |
| person_id | Yes | Officient person id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. Description reinforces 'READ-ONLY' and adds behavioral details: returns scheduled_minutes and events, filter affects response, and required scope. No contradictions. Description adds significant context beyond 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?
Description is two sentences plus a scope and read-only note. No redundant information. Every sentence is informative.
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, description sufficiently explains what the tool returns (days with scheduled_minutes and events). It covers filtering and required scope. Could elaborate on output format, but for a simple retrieval tool it 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 100% with all three parameters described. Description adds value by explaining that 'all' is the default for filter and advising to use days_with_events to keep response small. This goes beyond the schema's enum description.
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 it gets a person's calendar for one year, listing days with scheduled_minutes and events. It also mentions filtering with days_with_events. This distinguishes it from sibling tools like get_day_calendar and get_month_calendar.
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?
Description provides guidance to use days_with_events filter to keep response small, and states required scope. It implies the use case (yearly calendar) but does not explicitly exclude other tools like month or day calendars. Clear context but no explicit 'when not to use'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Company assets (laptops, phones, badges, …), optionally filtered by owner. Zero-indexed pagination. Required scope: basics:read. READ-ONLY.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Zero-indexed page number: page 0 is the first page. 30 items per page. | |
| person_id | No | Only return assets owned by this person. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true and destructiveHint=false; the description reinforces this with 'READ-ONLY' and adds 'Required scope: basics:read', providing additional behavioral context beyond 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?
Extremely concise: two sentences with no fluff. Every part adds value—resource definition, optional filter, pagination, scope, and read-only status.
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 key aspects: assets scope, optional filter, pagination, and required scope. The return format is not described, but for a list tool 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 100% with clear descriptions for both parameters. The description adds the phrase 'optionally filtered by owner' reflecting person_id, but this is not significantly beyond the schema's own description. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists company assets with examples (laptops, phones, badges) and an optional filter by owner. It distinguishes from sibling list tools (e.g., list_people, list_vehicles) by the resource 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 indicates optional filtering by owner and zero-indexed pagination, but does not explicitly state when to use this tool versus alternatives or when not to use it. The sibling tools are for different resources, but no direct comparison or exclusion is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
All employment contracts in the account, 30 per page, zero-indexed pagination. Required scope: contracts:read. READ-ONLY.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Zero-indexed page number: page 0 is the first page. 30 items per page. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true. The description adds useful behavioral details: pagination (30 per page, zero-indexed) and the required scope. This goes beyond annotations without contradicting them.
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—two short sentences—and front-loads the core purpose. Every word 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 list tool with no output schema, the description lacks details on the response structure (e.g., fields returned, sorting). While pagination is covered, the absence of return value information makes it less 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?
With 100% schema coverage, the schema already describes the 'page' parameter well. The description repeats the same pagination info, adding no further semantic 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 the tool lists employment contracts with pagination. The verb 'list' and resource 'contracts' are specific, but it does not explicitly differentiate from sibling tools.
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 the required scope 'contracts:read' and that it's read-only, providing basic usage conditions. However, it offers no guidance on when to use this tool vs alternatives like search_people.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Calendar (days off) requests across the account, 30 per page, zero-indexed pagination. Required scope: calendar:read. READ-ONLY.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Zero-indexed page number: page 0 is the first page. 30 items per page. | |
| status | No | Filter by request status. Defaults to "all". |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavioral details beyond annotations: pagination behavior ('30 per page, zero-indexed pagination') and required scope. Annotations already indicate read-only and non-destructive, so the description complements well.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three short sentences, efficiently conveying key information without redundancy. It is front-loaded with the main purpose.
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 listing tool with no output schema, the description covers pagination and scope. It does not explain the response structure (e.g., items array, total count), but annotations (openWorldHint) and sibling tools provide some context. Still, a slightly more complete description of the response could be beneficial.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema fully describes parameters. The description reiterates pagination info already in the schema parameter descriptions, adding no new semantic meaning.
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 resource ('Calendar days off requests') and the action (list), with specific details like pagination. It distinguishes from sibling tools by focusing on days-off requests specifically.
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 helpful usage guidance by specifying the required scope ('calendar:read') and read-only nature. However, it does not explicitly state when to use this tool versus alternatives like officient_get_day_calendar or officient_get_month_calendar.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Documents attached to an employee, asset or car. Zero-indexed pagination. Use officient_request with operationId "download-document" to get a download URL. Required scope: documents.read. READ-ONLY.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Zero-indexed page number: page 0 is the first page. 30 items per page. | |
| object_id | Yes | Id of the employee, asset or car. | |
| object_type | Yes | Which kind of object the documents hang on. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the READ-ONLY note adds no new info. Description adds pagination details but lacks info on sorting, ordering, or return structure. No contradictions.
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?
Very concise: 3 sentences covering purpose, pagination, sibling tool reference, scope, and read-only flag. 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?
No output schema, and description does not explain return format (e.g., array of documents, total count, pagination links). Adequate for a read-only list with good annotations but could be more informative.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already fully documents parameters. Description adds the pagination context (zero-indexed) but not beyond what schema provides.
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 it lists documents attached to an employee, asset, or car, and mentions pagination. This distinguishes it from sibling tools that handle other entities like people, calendars, or vehicles.
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?
Provides explicit guidance to use officient_request for downloading documents and states required scope. However, it does not explicitly mention when not to use this tool or common pitfalls.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Discover Officient API endpoints from the bundled spec (no network call, no scope needed). Returns compact one-liners: operationId | METHOD path | summary | required scope | read/WRITE. Filter by tag, HTTP method or free text, then feed an operationId into officient_describe_endpoint or officient_request. READ-ONLY.
| Name | Required | Description | Default |
|---|---|---|---|
| tag | No | Filter by tag, e.g. calendar, people, expenses, wages, documents, fleet. | |
| limit | No | Max results (default 100). | |
| method | No | Filter by HTTP method. | |
| search | No | Free-text filter over operationId, path, summary, tag and description. | |
| writes_only | No | Only return endpoints that modify data. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description adds value beyond annotations by specifying output format and that no network call or scope is needed. Confirms read-only nature. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences that front-load the main purpose, output format, and usage. Every sentence adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a discovery tool with no output schema, the description adequately explains output format, usage pattern, and filtering. Annotations cover safety. No missing critical 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?
Schema already covers all 5 parameters with descriptions. Description re-iterates filtering options but does not add significant new meaning 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?
Clearly states the tool lists/disovers Officient API endpoints from a bundled spec. Distinguishes from siblings by noting it returns one-liners to feed into officient_describe_endpoint or officient_request.
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?
Explicitly tells how to use the results (feed operationId into other tools) and mentions filtering options. Does not explicitly state when not to use, but context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Custom event types (holiday, remote work, overtime types, …) available in a given year, with the custom_day_off_type_id needed to add a "custom" calendar event. Required scope: calendar:read. READ-ONLY.
| Name | Required | Description | Default |
|---|---|---|---|
| year | Yes | Four-digit year, e.g. 2026. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds value by explaining the output contains the custom_day_off_type_id and the required scope. It does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the main purpose, and every word is informative. No redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with one parameter and no output schema, the description gives examples of event types and the key ID. It lacks detail on other potential return fields but is adequate for usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a clear description for the year parameter. The tool description reinforces the year context but does not add new information 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 it lists custom event types for a given year and specifies the role of the custom_day_off_type_id. It distinguishes from sibling tools like get_day_calendar or add_calendar_event by focusing on event type metadata.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It mentions required scope calendar:read and the read-only nature, and implies the ID is needed for adding custom events. However, it does not explicitly direct the agent to use this tool before add_calendar_event or state 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.
Expenses for a whole year, or for one month when month is given. Zero-indexed pagination. Required scope: expenses:read. READ-ONLY.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Zero-indexed page number: page 0 is the first page. 30 items per page. | |
| year | Yes | Four-digit year, e.g. 2026. | |
| month | No | Optional month, 1-12. | |
| include_deleted | No | Include deleted expenses. Defaults to false. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true and destructiveHint=false, so the description's addition of 'READ-ONLY' is redundant but not harmful. It adds useful context about zero-indexed pagination and the required scope expenses:read, which goes beyond 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 two sentences, very concise, and front-loaded with the main purpose. Every sentence adds value, 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?
For a list tool with no output schema, the description covers the core functionality, filtering, pagination, and permissions. It does not explain the return format, but this is acceptable given the tool's simplicity and the lack of an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds meaning by explaining the conditional behavior of the month parameter and the pagination scheme, which enriches the understanding beyond the schema's individual parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool lists expenses for a whole year or for a specific month when provided, which is a specific verb+resource combination. It also mentions pagination and required scope, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context on when to use the tool (for a year or a month), but does not explicitly mention when not to use it or name alternatives. However, among the sibling tools, there is no other expense-listing tool, so this is a minor gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List employees, 30 per page. Pagination is zero-indexed: page 0 is the first page. Required scope: basics:read. READ-ONLY.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Zero-indexed page number: page 0 is the first page. 30 items per page. | |
| include_archived | No | Include archived (former) employees. Defaults to false. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations (readOnlyHint=true, destructiveHint=false) are consistent with the description's 'READ-ONLY' label. Description adds pagination detail beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no redundancy. Essential info is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, pagination, scope, and parameters. Lacks return structure description, but acceptable for a simple list tool with no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so description adds minimal extra meaning. Repeats pagination info already in schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'List employees, 30 per page' with a specific verb and resource. Distinguishes from siblings like 'search_people' and 'get_person' by implying a paginated 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?
Provides pagination semantics (zero-indexed) and required scope. Does not explicitly compare to alternatives (e.g., search_people) but context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
All teams in the account. Returns id and name only — despite what the upstream docs imply, the response carries NO member list (verified live 2026-07). There is no team-detail endpoint either, so team membership is not readable over the API. To reconstruct the org structure, walk officient_list_people and call the "person-manager" operation per person via officient_request instead. Required scope: basics:read. READ-ONLY.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark readOnlyHint=true and destructiveHint=false. The description adds verified behavioral details (no member list, no team-detail endpoint, required scope) that enhance transparency without contradiction.
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, though the note about live verification adds length but is valuable for trust. Could be slightly trimmed without losing meaning.
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 parameters and output schema, the description fully covers the tool's behavior, limitations, and provides a complete picture for an agent to decide when and how to use it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so baseline is 4. The description does not need to add parameter information.
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?
Clearly states it lists all teams, returns id and name only. Distinguishes from siblings by noting the limitation of no member list and the absence of a team-detail endpoint.
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?
Explicitly describes when to use the tool and provides clear alternatives: walk officient_list_people and use officient_request to reconstruct org structure when team membership is needed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Vehicles in the fleet, optionally only those assigned to one person. Zero-indexed pagination. Required scope: basics:read. READ-ONLY.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Zero-indexed page number: page 0 is the first page. 30 items per page. | |
| person_id | No | Only return vehicles assigned to this person. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explicitly states READ-ONLY, required scope basics:read, and zero-indexed pagination, adding significant behavioral context beyond the annotations which only hint at read-only and destructive intent.
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 long, front-loads the purpose, and includes essential context like pagination and scope without any 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?
For a simple read-only list tool with 2 optional parameters and no output schema, the description covers purpose, optional filter, pagination, required scope, and read-only nature. No important information is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already has high coverage (100%) with descriptions for both parameters. The description adds no new parameter-specific information beyond what's in the schema, so it meets but does not exceed the baseline.
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 fleet vehicles, with an optional filter by person. This differentiates it from sibling tools like list_people or list_assets.
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 retrieving fleet vehicles and mentions optional person filtering, but does not provide explicit guidance on when to use this tool over 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.
Webhook subscriptions configured on the account. Officient POSTs {account, event_type, related_object_id} to the target URL and retries on non-200. Required scope: webhooks:read. READ-ONLY.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and destructiveHint. The description adds context about webhook behavior (POSTing and retries) which is beyond the tool's own behavior. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences that are front-loaded and efficient, with no wasted words. Every sentence provides 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 no parameters and no output schema, the description adequately explains the tool's purpose and provides context about webhooks. It is complete enough for a simple list 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?
No parameters exist, so baseline is 4. The description adds no parameter info which is acceptable since 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?
The description clearly states the tool lists webhook subscriptions on the account, using specific verb 'List' and resource 'webhooks'. It is distinct from sibling tools which operate on other resources.
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 required scope 'webhooks:read' and declares the operation read-only, but does not explicitly state when to use this tool over alternatives or provide context on 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.
Idempotent upsert of a single event of a given type on a given date: overwrites the existing event of that type or creates it. Handy for syncing time tracking. The event type itself cannot be changed. CAVEAT (observed live 2026-07): when an event of that type already exists on that date with the same duration_minutes, the API returns {"success":1,"info":"no action taken"} and changes NOTHING — it does not compare start_time_minutes. To move an existing event's start time, delete it with officient_delete_calendar_event and re-add it with officient_add_calendar_event. Always read the calendar back to confirm the change actually landed. Required scope: calendar:write. WRITES DATA in Officient.
| Name | Required | Description | Default |
|---|---|---|---|
| day | Yes | Day of month, 1-31. | |
| type | Yes | sick_day, education or custom. | |
| year | Yes | Four-digit year, e.g. 2026. | |
| month | Yes | Month, 1-12. | |
| person_id | Yes | Officient person id. | |
| duration_minutes | Yes | Duration in minutes, or the string "all_day" to use the scheduled hours for that day. | |
| start_time_minutes | Yes | Start time in minutes since midnight, e.g. 540 = 09:00. | |
| custom_day_off_type_id | No | Required when type="custom"; get it from officient_list_event_types. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructive and non-read-only behavior. The description adds critical behavioral context: the API does nothing when event type and duration match, even if start time differs; recommends verifying writes by reading back; states idempotency; declares required scope and that it writes data. This goes well beyond 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 efficiently structured: clear purpose first, then use case, critical caveat, alternative method, verification advice, scope, and write warning. Every sentence provides necessary information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a write tool with 8 parameters and no output schema, the description thoroughly covers usage, behavioral nuances, parameter interactions, failure modes, and recommended verification. It also references relevant sibling tools explicitly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, baseline 3. The description adds semantic value by explaining that the event type cannot be changed and why duration_minutes matching prevents start_time_minutes updates, and when custom_day_off_type_id is required.
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 performs an idempotent upsert of a single calendar event by type on a given date, overwriting existing or creating new. It distinguishes from siblings by explicitly contrasting with officient_delete_calendar_event + officient_add_calendar_event for start time changes.
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 includes explicit guidance on when to use alternatives: to move an existing event's start time, use delete then add. It also notes the caveat about same duration preventing update, guiding users away from this tool when that condition is problematic.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Escape hatch that reaches every one of the documented Officient endpoints by operationId. Input is validated against the bundled spec before anything is sent. Required scope depends on the endpoint — officient_describe_endpoint tells you which one, and whether it writes. CAN WRITE: this tool will happily fire POST/PATCH/PUT/DELETE endpoints, so check the endpoint first. Pagination is zero-indexed (page=0 is the first page). Prefer the dedicated officient_* tools when one exists.
| Name | Required | Description | Default |
|---|---|---|---|
| body | No | JSON request body for POST/PATCH/PUT endpoints. File uploads use base64 JSON fields (document_base64 / photo_base64), not multipart. | |
| query | No | Query string parameters, e.g. {"page": 0}. Pagination is zero-indexed. | |
| dry_run | No | When true, validate and return the resolved request without calling Officient. | |
| pathParams | No | Values for the {placeholders} in the path, e.g. {"person_id": 123, "year": 2026}. | |
| operationId | Yes | Operation id from officient_list_endpoints, e.g. "person-detail" or "add-event". |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds critical behavioral details: validation against spec, zero-indexed pagination, and write capability warning, complementing annotations that set destructiveHint and readOnlyHint.
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 paragraph front-loading purpose, covering usage guidance, behavior, and warnings without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Comprehensive for a generic endpoint caller: covers input validation, pagination, write warning, scope checking, and priority over dedicated tools. No output schema needed as output varies.
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?
All parameters are described in schema (100% coverage). Description adds context: validation, pagination index, file upload format, and explains dry_run, pathParams, etc., beyond 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?
Clearly identifies as an escape hatch to call any Officient endpoint by operationId. Distinguishes from dedicated tools by stating preference for those when available.
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?
Explicitly says to use when no dedicated tool exists, recommends checking scope via officient_describe_endpoint, and warns about write operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find people by name, work email or national number. Supply at least one criterion. Required scope: personal.info:read. READ-ONLY.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Full or partial name. | |
| No | Work email address. | ||
| national_number | No | National registration number. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, making the safety profile clear. The description adds context by stating the required scope and explicitly labeling it 'READ-ONLY'. This goes beyond annotations and is consistent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no wasted words. First sentence explains functionality and criteria. Second sentence covers usage rule, required scope, and read-only nature. Every sentence adds essential 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 the return format (e.g., what fields are returned, if pagination exists). Since there is no output schema, the description should clarify the output structure. However, the tool is simple and the openWorldHint suggests flexibility, so it is functional but not fully 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 100% and each parameter has a description. The description adds the constraint that at least one criterion must be supplied, which is not enforced in the schema (no required parameters). This additional guidance is valuable beyond what the schema provides.
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 'Find' and the resource 'people' with specific search criteria (name, work email, national number). It also notes that at least one criterion must be supplied, distinguishing it from sibling tools like 'officient_list_people' (list all) and 'officient_get_person' (by ID).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage guidance: 'Supply at least one criterion' and states the required scope. It implies when to use this tool versus list/get tools, but does not explicitly state when not to use it or name alternatives. The guidance is clear but lacks explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0officient_add_calendar_eventofficient_delete_calendar_eventofficient_describe_endpointofficient_get_day_calendarofficient_get_month_calendarofficient_get_own_accountofficient_get_personofficient_get_person_custom_fieldsofficient_get_weekly_scheduleofficient_get_year_calendarofficient_list_assetsofficient_list_contractsofficient_list_days_off_requestsofficient_list_documentsofficient_list_endpointsofficient_list_event_typesofficient_list_expensesofficient_list_peopleofficient_list_teamsofficient_list_vehiclesofficient_list_webhooksofficient_overwrite_calendar_eventofficient_requestofficient_search_peopleScored across 24 tools
Every tool has a clearly distinct purpose, with no overlap. Even the calendar-related tools (get_day_calendar, get_month_calendar, add_calendar_event, etc.) are well-differentiated by granularity and action.
All tools follow a consistent 'officient_verb_noun' snake_case pattern. Verbs like list, get, search, add, overwrite, delete are used predictably, with no mixed conventions.
24 tools is appropriate for a comprehensive HR API covering people, calendar, expenses, contracts, and more. Each tool addresses a distinct operation, and the meta-tools (list_endpoints, describe_endpoint, request) add valuable discoverability without bloat.
The tool set covers most core HR workflows (people, calendar, expenses, contracts, etc.) with dedicated tools. Minor gaps exist (e.g., no create/update for people, no webhook management beyond listing), but the officient_request escape hatch mitigates these, and the surface handles primary use cases well.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
MCP server that lets AI assistants use all OneSchema features exposed via the public API.
Hosted MCP server connecting AI assistants to 9,000+ apps and 40,000+ actions via Zapier.
MCP server exposing klokin time-tracking operations (employees, time entries, stores) to AI clients.
