What can you do with this server?

This server provides an MCP interface to HiBob's Workforce Planning API, letting you read, create, update, and manage planned positions, their openings, and their budgets. * Read & search workforce data: list fields, search positions, position openings, and position budgets, with human-readable labels and filtering. * Get organizational context: fetch company named lists (departments, sites, etc.), resolve list values to IDs, retrieve workforce forms with options and required fields. * Analyze structure and costs: find openings belonging to positions, walk position reporting trees, compute position costs, and summarize costs across departments/statuses/currencies. * Create positions: create a position with its required opening and optional budget. * Update and cancel positions: modify position fields like name, dates, manager, FTE, department, site, job profile; cancel positions. * Manage openings: create, update, and delete position openings, including recruitment status and expected start dates. * Manage budgets: create and update position budgets, including salary, currency, pay period, and cost figures. * Safety and validation: refuses invalid writes, verifies writes by reading back, supports read-only mode, and handles rate limits.

How do I use hibob-advanced-mcp?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@hibob-advanced-mcp show open positions in Engineering" 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.

de en es ja ko ru zh

hibob-advanced-mcp

by JustParent

Overview Schema Source Related Servers Discussions Admin

Python

Remote

hibob-advanced-mcp

An MCP server for HiBob's Workforce Planning API — planned positions, their openings, and their budgets.

This complements a standard HiBob HRIS integration rather than replacing it. Common HRIS functionality (people, time off, documents) belongs in the main integration; this server exposes the workforce planning surface that has no equivalent in other HRIS systems, so it can be enabled only for the customers who plan headcount in HiBob.

It runs over stdio, is installable with uvx, and authenticates with a HiBob API service user.

HiBob setup

In HiBob, go to Settings → Integrations → API service users and create a service user. HiBob shows the service user ID and token once — copy both now, as they cannot be retrieved later.
Create (or reuse) a permission group containing that service user, and grant it:
Features → Workforce planning → Position management → Manage positions
Service users have no permissions by default. Without this grant every call returns 403, and this server will tell you to add exactly this permission.
If your HiBob account restricts API access by IP address, allow the outbound IP of wherever this server runs.

Read-only use still needs the same grant — HiBob does not offer a narrower workforce planning permission. Use HIBOB_READ_ONLY=true (below) if you want the server itself to refuse to make changes.

Related MCP server: humaans-mcp

Configuration

Environment variable	Required	Description
`HIBOB_SERVICE_USER_ID`	yes	Service user ID (the Basic auth username).
`HIBOB_SERVICE_USER_TOKEN`	yes	Service user token (the Basic auth password).
`HIBOB_API_HOST`	no	Defaults to production (`api.hibob.com`). Set `api.sandbox.hibob.com` for HiBob's sandbox. A pasted URL such as `https://api.sandbox.hibob.com/v1` is accepted; only the hostname is used.
`HIBOB_READ_ONLY`	no	`true`, `1`, `yes` or `on` registers only the eleven read tools; the eight write tools are not exposed at all.

Standard proxy variables (HTTPS_PROXY, ALL_PROXY) are honoured. A SOCKS5 proxy needs the optional socks extra — see the install line below.

Running it

Pinned to a commit, which is how it should be deployed:

uvx --from 'git+https://github.com/JustParent/hibob-advanced-mcp@<GIT_SHA>' hibob-advanced-mcp

From a local checkout, during development:

uvx --from . hibob-advanced-mcp --test

--test prints the version, the resolved API base URL, whether credentials are set (never their values), the read-only state, and every registered tool, then exits. It verifies an install without needing an MCP client or live credentials.

With a SOCKS5 proxy:

uvx --from 'git+https://github.com/JustParent/hibob-advanced-mcp@<GIT_SHA>[socks]' hibob-advanced-mcp

Claude Desktop

{
  "mcpServers": {
    "hibob-workforce-planning": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/JustParent/hibob-advanced-mcp@<GIT_SHA>",
        "hibob-advanced-mcp"
      ],
      "env": {
        "HIBOB_SERVICE_USER_ID": "<service user ID>",
        "HIBOB_SERVICE_USER_TOKEN": "<service user token>"
      }
    }
  }
}

Plugging into a sandboxed MCP integration

For a host that runs MCP servers as sandboxed subprocesses using the Claude Desktop config shape, the integration config is:

{
  "server_type": "sandboxed",
  "sandbox_command": "uvx",
  "sandbox_args": [
    "--from",
    "git+https://github.com/JustParent/hibob-advanced-mcp@<GIT_SHA>",
    "hibob-advanced-mcp"
  ],
  "sandbox_runtime": "python",
  "auth_type": "none",
  "sandbox_env": {
    "HIBOB_SERVICE_USER_ID": "<service user ID>",
    "HIBOB_SERVICE_USER_TOKEN": "$SECRET_KEY"
  }
}

Paste the service user's token into the integration's secret key field: $SECRET_KEY is substituted with it inside the sandbox, so the token is never stored in the config itself. The service user ID is not a secret and goes in literally.

No --with 'mcp<2' argument is needed — this package pins the MCP SDK itself.

Tools

Field IDs are passed as flat mappings, for example {"/position/fte": 100}. The /position/ prefix may be omitted ({"fte": 100}). The server wraps values into HiBob's {"value": ...} envelope for you, and flattens search results back out.

Read

Tool	HiBob endpoint	Rate limit
`hibob_list_workforce_fields`	metadata for `position`, `positionOpening` or `positionBudget`	50/min
`hibob_get_workforce_form`	metadata for each section of the form, plus `GET /company/named-lists/{name}` for each list a field draws from	50/min
`hibob_get_company_named_lists`	`GET /company/named-lists/{name}`, or `GET /company/named-lists` summarised to names and sizes	—
`hibob_resolve_list_values`	metadata for the object, then `GET /company/named-lists/{name}` for the field's list, both cached	50/min each
`hibob_search_positions`	`POST /objects/position/search`; a free-text `query` is matched locally against title, code, department, site, job profile and holder	100/min
`hibob_search_position_openings`	`POST /positions/position-openings/search`	100/min
`hibob_get_openings_for_positions`	`POST /positions/position-openings/search`, every page	100/min
`hibob_get_positions_under`	`POST /objects/position/search`, every position, walked in memory	100/min
`hibob_search_position_budgets`	`POST /positions/position-budget/search`, plus `POST /objects/position/search` to name each budget's position	100/min
`hibob_get_position_costs`	`POST /objects/position/search`, then `POST /positions/position-budget/search` for the budgets they reference	100/min
`hibob_summarize_position_costs`	the same two searches, company-wide, aggregated in memory	100/min

Search results come back as {"count": N, "entries": [{"values": {...}, "display": {...}}]}. values holds the raw values including the IDs the write tools need; display holds HiBob's human-readable labels. The opening and budget searches are cursor-paginated and return has_more and next_cursor; the budget search takes a limit up to 1000 (HiBob rejects anything larger), which is one page for most companies. Position search has no pagination and ignores limit entirely, so request only the fields you need and filter where you can.

Seven of the read tools do work HiBob's API cannot do in one request:

hibob_get_openings_for_positions answers "which openings belong to this position?". HiBob's opening search only filters by an opening's own ID, status or name, never by its parent position. The tool sends a filter every opening satisfies (/positionOpening/id notEqual "1", the clause verified against HiBob's sandbox), pages through every opening 100 at a time, and joins on /positionOpening/positionId in memory. Pass several positions at once to pay for the scan once; a statuses filter is applied by HiBob and shortens it. Positions may be given by numeric ID or by name (P-0000000368); names are resolved in one search first and reported back in resolved_positions. The result reports counts_by_position, so a position with no openings shows as 0, and scan_complete, which is false only if the scan hit its 10,000-opening safety cap.
hibob_get_positions_under answers "which positions report up to me, and which are filled?". Position search cannot filter by manager position or by holder, but it returns every position in one unpaginated response with its manager position and the employee filling it, so the tool fetches them all (one request) and walks the reporting tree in memory. The top position can be given as a position ID, a position name (P-...), the holder's HiBob employee ID, the holder's work email or the holder's name; those last two matter because HiBob has no call from an employee to their position, and a name fitting several people returns candidates instead. An email costs one narrowly scoped call to HiBob's people search that asks for the employee ID and nothing else; it is the server's only use of the people API. The result lists each position beneath with its status, holder and own manager position, depth levels down (1 for direct reports), with counts_by_status; a statuses filter is applied after the walk so a vacant position under a filled one is never lost.
hibob_search_position_budgets names the position each budget belongs to. A budget record carries no reference to its position — HiBob's only link runs the other way, as /position/budget on the position — so a budget fetched on its own genuinely cannot be attributed to anything, and the honest reading of one in isolation is that its cost belongs to nobody. The tool therefore scans every position for that reference and reports the owner as each entry's position. It sits beside values rather than among the field IDs because it is synthesised here, and HiBob can neither filter nor sort on it. null means no position references that budget; a failed lookup returns the budgets with position_link_error and no position key at all, which is deliberately not the same as null. Pass include_position: false for a pure total to skip the extra request.
hibob_get_position_costs answers "what does this position cost?". Cost is not a field on a position. /objects/position/search exposes 38 fields and none of them are cost; the figures the HiBob UI shows on a position (expected base salary, total position cost, total converted cost, prorated cost) live on a separate positionBudget object. The only link is /position/budget on the position, an entity_reference holding the budget's ID — a budget carries no position ID of its own, so the join only exists in that one direction. The tool fetches the named positions, reads that reference off each, fetches exactly those budgets and merges them, in two requests; positions may be given by numeric ID or by name (P-0000000368), and names cost one more search, reported back in resolved_positions. Positions whose budget is missing are listed in positions_without_budget rather than dropped.
Two HiBob behaviours make this hard to discover, and both fail silently. Unrecognised field IDs are dropped without an error — asking the position search for /positionBudget/totalPositionCostCurrencyValue, or for an entirely invented field, returns 200 OK with the key simply absent, so a request for cost looks like it worked and came back empty. And filtering is whitelisted: positions filter only on /position/status, /position/name, /position/hasOpenRequests and /position/id, budgets only on /positionBudget/id and /positionBudget/proRatedCostPercentage. Anything else is a 400, so no cost figure can be filtered or grouped by HiBob at all.
hibob_summarize_position_costs rolls that cost up across the company, or a department, or everything still vacant — the thing HiBob cannot do itself, since cost is neither filterable nor groupable. It fetches every position and every budget (two requests), joins them and aggregates here, optionally grouped by department, site, status, jobProfile or currency and restricted to given statuses. Only the converted figures are summed: HiBob reports each position's total in its own local currency, and a company can have many, so adding those together would produce a meaningless number, while the converted values share the company's reporting currency. If converted costs ever arrive in more than one currency, total_converted_cost is null and totals_by_currency carries a total per currency instead of one wrong number.
hibob_resolve_list_values turns the option names a user chose back into the IDs HiBob wants. A form is offered by option name, and what comes back from it is the name; by then a bot may have lost the form response that paired names with IDs, and the ID of the list behind the field with it. The tool takes what is left, the field as an ID or its label (Locations for hiring, Site) and the names, finds the list from the field's metadata, fetches that one list, and matches each name exactly, ignoring case, against the items and, for a tree-shaped list, their path labels (Spain > Madrid - Office). It returns values, the IDs in the order given and ready to submit, and says whether the field is multi. A name matching nothing comes back under unmatched with the nearest items as candidates; one that two items share comes back under ambiguous rather than guessed at; a branch of a tree, which cannot be submitted, offers its leaves. Every list field on a form names this tool as resolve_with.
hibob_get_workforce_form returns everything needed to fill in a create form as one blob: for position (the default) that is the position's fields plus the nested opening (required) and budget (optional) sections; for positionOpening or positionBudget just that object. Every list-backed field (department, site, job profile, currency, ...) arrives with its options resolved from the company's named lists, including the id to submit (a list longer than max_options, 100 by default, is truncated, and the field then says to fetch the rest with hibob_get_company_named_lists); fields with a fixed vocabulary (position type, recruitment status, pay periods) carry allowed_values; each field says whether it is required, and fields HiBob sets itself are listed separately as read_only_fields. Each section names the write tool argument it maps to (position_fields, opening_fields, budget_fields or fields), so the filled-in form can be passed straight to the create tool.
A form has to be complete when it is generated (a Slack form, say, needs every option up front), and job profiles and manager positions run to a thousand items. So for a position form the tool takes what the user should be asked first: department, job_profile (a rough title) and manager (a name, P-... position name or ID). A department pre-fills its field and narrows the manager choices to that department's branch of the position tree and the job profiles to those naming the department; a title or a manager's name picks out the matching leaves, and a single match pre-fills the field as value. Tree-shaped lists are offered as their leaves, labelled by path (Data > Head of Data > P-0001 · London · Jane Doe). If any of these three fields still cannot be offered within max_options, the response carries questions (each with the argument to pass, a question to ask the user and, when few enough, candidates) instead of sections; answer them and call again.

Write (omitted when `HIBOB_READ_ONLY` is set)

Tool	HiBob endpoint	Rate limit
`hibob_create_position`	`POST /workforce-planning/positions`	10/min
`hibob_update_position`	`PATCH /workforce-planning/positions/{id}`	10/min
`hibob_cancel_position`	`PATCH /workforce-planning/positions/{id}/cancel`	10/min
`hibob_create_position_opening`	`POST .../position-openings`	10/min
`hibob_update_position_opening`	`PATCH .../position-openings/{openingId}`	10/min
`hibob_delete_position_opening`	`DELETE .../position-openings/{openingId}`	10/min
`hibob_create_position_budget`	`POST .../position-budget`	10/min
`hibob_update_position_budget`	`PATCH .../position-budget/{budgetId}`, the budget found from the position	10/min

Every tool that takes a position or an opening accepts it either as its numeric ID or as the name HiBob shows: P-0000000368 for a position, O-6853240227 for an opening. A name costs one search before the write, which comes out of the search limit rather than the write limit; a name that matches nothing, or that HiBob has let two records share, is refused rather than guessed at. Openings are always looked up before an update or delete, whether given by ID or by name, because the lookup returns the position each opening belongs to. A write addressed under the wrong position, such as O-6853240227 beneath the ID of another position, is refused before anything is sent. Budgets have no name and need none: a position carries its budget's ID as /position/budget, so hibob_update_position_budget finds the budget from the position, and its budget_id argument is optional. If a budget_id is given it must be that position's budget, so an ID carried over from another position is refused; a second budget for a position that already has one is refused likewise. Each result reports the numeric position_id (and opening_id or budget_id) actually written to.

Writes are limited to ten calls a minute, so required fields are validated before a request is sent and write calls are never retried automatically. Read calls retry twice on 429 and 5xx responses, honouring Retry-After. Named lists and metadata are each limited to fifty calls a minute and a position form needs a dozen lists and three metadata calls, so both are cached in the server process for five minutes, shared between the form, named-list and resolve tools; a failed fetch is not cached. Every create and update reads the record back through its search endpoint and returns it with verified; a read-back failure is reported as verification_error rather than as a failed write, and a created opening is checked to belong to the position it was created under.

hibob_create_position creates one position per call, together with its first opening (HiBob requires one) and an optional budget.

Field cheat sheet

Required to create a position:

Object	Required fields
`position`	`effectiveDate`, `fte`, `department`, `site`, `jobProfile`
`positionOpening` (nested, required)	`expectedStartDate`
`positionBudget` (nested, optional)	`salaryPayPeriod`, `currency` if the budget is supplied

Updatable on a position: name, effectiveDate, managerPositionId, positionType, fte, employmentType, department, site, jobProfile, reason, plus custom fields (/position/field_<number>, IDs from hibob_get_workforce_form). Custom fields are passed to HiBob unverified: the result names them as undocumented_fields, a rejected update says they may be the reason, and a field HiBob accepted but did not keep shows up in unconfirmed_fields after the read-back. Fields HiBob sets itself (id, status, filledBy, ...) are refused before any request.

Filterable fields: /position/status, /position/name, /position/hasOpenRequests, /position/id; /positionOpening/id, /positionOpening/status (vacant, starting, filled, departing, cancelled, onHold, cancelledSoon), /positionOpening/positionOpeningName. A search without filters returns everything: HiBob refuses an empty filter list, so the server sends a clause every record satisfies.

Fields such as department, site and jobProfile take HiBob list item IDs, not names. hibob_get_workforce_form returns those IDs alongside each field; hibob_get_company_named_lists returns one list's items, or with no list_name just the names and sizes of every list, since the full contents of every list can run to tens of megabytes.

Development

uv venv
uv pip install -e '.[test,lint,typecheck]'
pytest

Lint, formatting and types are enforced in CI:

ruff check .          # add --fix to apply the automatic fixes
ruff format .         # CI runs --check, so format before pushing
mypy                  # non-strict; paths come from pyproject.toml

Type checking is deliberately non-strict — annotations are checked where they exist, but untyped code is allowed. The package ships a py.typed marker, so its annotations are visible to anything that imports it.

Inspect the tools interactively:

npx @modelcontextprotocol/inspector uvx --from . hibob-advanced-mcp

License

MIT

Available Tools

13 tools

hibob_cancel_positionA

DestructiveIdempotent

Cancel a planned position, removing it from the workforce plan.

HiBob refuses to cancel a position that is currently filled; check '/position/status' with hibob_search_positions first. Cancelling cannot be undone through this API, so confirm the position ID before calling.

Args: position_id: The position's ID.

Returns: str: JSON confirming the cancellation, or an error message beginning with "Error:".

Rate limit: 10 requests/minute.

ParametersJSON Schema

Name	Required	Description	Default
`position_id`	Yes	ID of the position to cancel.

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.7/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the destructiveHint annotation, the description discloses important behavioral traits: cancellation cannot be undone, HiBob refuses filled positions, and the tool is rate-limited to 10 requests/minute. It also describes the return contract (JSON confirmation or an 'Error:' string). No contradiction with annotations is present.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core purpose and key warning, then follows a compact structured format for Args, Returns, and Rate limit. Every sentence adds value: purpose, precondition, irreversibility, parameter, return behavior, and rate limit. No filler or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter, clearly scoped cancellation tool, the description covers the essential context: purpose, precondition, irreversibility, error return, and rate limit. An output schema exists, so detailed return documentation is not required. Nothing material is missing for an agent to invoke this correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, and the only parameter, position_id, is already documented in the schema as 'ID of the position to cancel.' The description's Args section merely repeats this meaning without adding format, source, or validation details, so it stays at the baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description starts with a specific verb and resource: 'Cancel a planned position, removing it from the workforce plan.' It clearly names the action and the object, and the mention of 'planned position' differentiates it from active/filled position operations and from sibling tools like create/update position.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly tells the agent when to call this tool (to cancel a planned position) and gives a concrete precondition: check '/position/status' with hibob_search_positions first because HiBob refuses to cancel filled positions. This is actionable usage guidance that also names the sibling tool to use beforehand.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

hibob_create_positionA

Create a planned position, with its opening and optional budget.

A position is a budgeted seat in the plan; every position must be created with an opening, which is the vacancy to be filled. Field values that reference HiBob lists (department, site, job profile) must be the list item IDs - resolve them first with hibob_get_company_named_lists and hibob_list_workforce_fields.

Creates one position per call. Required fields are checked before the request is sent, because HiBob allows only ten write calls per minute.

Args: position_fields: Flat mapping of position field IDs to values. opening_fields: Flat mapping for the nested opening. budget_fields: Optional flat mapping for the nested budget.

Returns: str: JSON {"id": int, "positionOpeningId": int} identifying the new position, or an error message beginning with "Error:".

Examples: - "Plan a new engineer starting in September" -> position_fields with effectiveDate/fte/department/site/jobProfile plus opening_fields with expectedStartDate. - Don't use when: adding a second vacancy to an existing position (use hibob_create_position_opening).

Rate limit: 10 requests/minute.

ParametersJSON Schema

Name	Required	Description
`budget_fields`	No	Optional budget. If given, requires "/positionBudget/salaryPayPeriod" and "/positionBudget/currency".
`opening_fields`	Yes	Fields for the position's first opening. Required: "/positionOpening/expectedStartDate". Optional: positionOpeningName, recruitmentStatus.
`position_fields`	Yes	Position fields as a flat mapping, e.g. {"/position/effectiveDate": "2026-09-01", "/position/fte": 100, "/position/department": "<list item ID>", "/position/site": 123, "/position/jobProfile": 456}. Required: effectiveDate, fte, department, site, jobProfile.

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.9/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the annotations, the description discloses important runtime behavior: rate limiting ('HiBob allows only ten write calls per minute'), pre-request validation of required fields, and the fact that exactly one position is created per call. It also describes the return format and error convention, which is valuable context for an agent handling failures.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with a clear opening definition, explicit prerequisites, parameter summaries, return format, examples, and an anti-example. Every sentence earns its place, and the most important usage guidance is front-loaded. Despite length, it remains scannable and useful.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with three nested object parameters and an open-world schema, the description is complete: it explains what a position is, what counts as the opening, how to resolve list IDs, what constraints apply, what the response looks like, and how to avoid misuse. The presence of an output schema reduces the burden of explaining return values, and the description still covers them.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already covers 100% of parameters with detailed descriptions, so the baseline is 3. The description adds value by clarifying that all three arguments are flat mappings, by explaining that HiBob list values must be list item IDs, and by instructing the agent to resolve those IDs first. This goes beyond the schema's individual field descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: 'Create a planned position, with its opening and optional budget.' It clearly distinguishes this from sibling tools, especially hibob_create_position_opening, by explaining that a position is a budgeted seat and must be created with its first opening. The 'one position per call' constraint further sharpens the purpose.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly tells the agent when to use this tool and when not to, naming the alternative: 'Don't use when: adding a second vacancy to an existing position (use hibob_create_position_opening).' It also gives a concrete example of when to use the tool and instructs the agent to resolve list IDs with hibob_get_company_named_lists and hibob_list_workforce_fields before calling.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

hibob_create_position_budgetA

Attach a salary and cost budget to a position.

Args: position_id: The position's ID. fields: Flat mapping of budget field IDs to values.

Returns: str: JSON {"positionBudgetId": int}, or an error message beginning with "Error:".

Examples: - "Budget 65k a year for that role" -> fields with expectedBaseSalaryCurrencyValue, salaryPayPeriod and currency.

Rate limit: 10 requests/minute.

ParametersJSON Schema

Name	Required	Description	Default
`fields`	Yes	Budget fields as a flat mapping. Required: "/positionBudget/salaryPayPeriod" (e.g. "Annual", "Monthly") and "/positionBudget/currency" (e.g. "GBP"). Optional: expectedBaseSalaryCurrencyValue, totalPositionCostCurrencyValue, expectedVariablePayCurrencyValue, variablePayPeriod.
`position_id`	Yes	Position the budget belongs to.

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.1/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate this is a mutating, non-idempotent operation. The description adds useful behavior beyond that by documenting the exact return format (JSON with positionBudgetId), error message prefix ('Error:'), and the 10 requests/minute rate limit. It does not cover duplicate-creation consequences, but the idempotentHint=false annotation covers that signal.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with Args, Returns, Examples, and Rate limit sections, and the main purpose is front-loaded in the first sentence. It is slightly verbose due to some duplication with the schema, but all included details earn their place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a mutating tool with two required parameters and an output schema, the description covers success/error output, rate limiting, and a practical example. The main missing context is explicit guidance about updating existing budgets versus creating new ones, though sibling names partly compensate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already has 100% coverage, documenting position_id and fields with required and optional field IDs. The description adds value with a concrete natural-language example mapping 'Budget 65k a year' to expectedBaseSalaryCurrencyValue, salaryPayPeriod, and currency, plus clarifying that fields is a flat mapping.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with 'Attach a salary and cost budget to a position,' which clearly identifies the action and resource. This differentiates the tool from siblings like hibob_update_position_budget and hibob_search_position_budgets by implying a create operation on a position budget.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides a concrete example ('Budget 65k a year for that role') that helps an agent recognize when the tool is appropriate. However, it does not explicitly state when to use this instead of hibob_update_position_budget or mention any exclusions or prerequisites.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

hibob_create_position_openingA

Add a vacancy to an existing position.

Args: position_id: The parent position's ID. fields: Flat mapping of opening field IDs to values.

Returns: str: JSON {"id": int, "positionOpeningId": int}, or an error message beginning with "Error:".

Rate limit: 10 requests/minute.

ParametersJSON Schema

Name	Required	Description	Default
`fields`	Yes	Opening fields as a flat mapping. Required: "/positionOpening/expectedStartDate". Optional: positionOpeningName, recruitmentStatus ("open", "onHold", "closed").
`position_id`	Yes	Position the opening belongs to.

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=false. The description adds meaningful behavior beyond those: a rate limit of 10 requests/minute, the exact return JSON shape, and an error prefix. This helps an agent anticipate failures and throttling.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact and well-structured: a one-sentence purpose, labeled Args, Returns, and Rate limit. Every line adds useful information without fluff or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers return format, error behavior, and rate limiting, while the output schema handles the return structure. It doesn't mention prerequisites beyond 'existing position' or auth concerns, but with a 2-parameter tool and rich schema, it is nearly complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, and the schema already documents the required expectedStartDate and optional fields. The description restates parameter names and short meanings, adding little beyond what the schema provides. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with 'Add a vacancy to an existing position,' naming a specific action and resource. It clearly distinguishes this from sibling tools like create_position or update_position_opening, and the phrase 'existing position' signals the parent context.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies this tool is for adding a vacancy to an existing position, which gives some usage context but does not explicitly say when to prefer it over create_position or update_position_opening. No alternatives or exclusions are mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

hibob_delete_position_openingA

DestructiveIdempotent

Permanently remove an opening from a position.

This deletes the vacancy record in HiBob and cannot be undone through this API. Confirm the opening ID with hibob_search_position_openings before calling.

Args: position_id: Parent position ID. opening_id: The opening's ID.

Returns: str: JSON confirming the deletion, or an error message beginning with "Error:".

Rate limit: 10 requests/minute.

ParametersJSON Schema

Name	Required	Description	Default
`opening_id`	Yes	ID of the opening to delete.
`position_id`	Yes	Parent position ID.

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.6/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the annotations already marking this as destructive and non-read-only, the description adds critical behavior: the action is permanent and cannot be undone through the API, the rate limit is 10 requests/minute, and the return value is either a JSON confirmation or an 'Error:' prefixed message. This substantially exceeds what annotations alone convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured and front-loaded with the primary purpose, followed by irreversible consequences, confirmation guidance, args, return value, and rate limit. The Args block is slightly redundant with the 100%-covered schema, but the overall length is reasonable and every section serves a clear purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive two-parameter operation, the description is complete: it explains irreversibility, provides a verification step, specifies the return format including failure behavior, and notes the rate limit. Despite the presence of an output schema, the return description adds further clarity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so both parameters are already fully documented in the input schema. The description's Args section largely repeats this information without adding new semantics, though it does clarify the relationship between position_id and opening_id.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with 'Permanently remove an opening from a position,' which clearly identifies the specific verb (remove), resource (opening), and container (position). This distinguishes it from sibling tools like create, update, and search operations on openings and positions without needing to inspect schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly instructs the agent to 'Confirm the opening ID with hibob_search_position_openings before calling,' naming the exact sibling tool to use first. It also communicates that the deletion is permanent, making the 'when to use' decision unambiguous.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

hibob_get_company_named_listsA

Read-onlyIdempotent

Look up the allowed values of HiBob's named lists.

Position fields such as department, site and employment type must be set to a list item from HiBob's named lists rather than to free text. This tool resolves those names to the IDs that hibob_create_position and hibob_update_position expect.

Args: list_name: A single list to fetch, or None for all lists.

Returns: str: JSON mapping list names to their items, each with an ID and a display name.

Examples: - "Which departments exist?" -> list_name='department' - Use before hibob_create_position to turn "Engineering" into its list item ID.

ParametersJSON Schema

Name	Required	Description	Default
`list_name`	No	Optional single list to fetch, e.g. 'department' or 'site'. Omit to return every named list.

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already establish read-only, idempotent, non-destructive behavior. The description adds meaningful behavioral details: list_name is optional and None returns all lists, and the return value is a JSON mapping to IDs and display names. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact and well-organized into Args, Returns, and Examples. Every sentence advances understanding, and the most important workflow context ('position fields must use named lists') is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-optional-parameter read-only lookup, the description provides purpose, usage timing, parameter behavior, return shape, and an example. Nothing needed for correct invocation is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema fully documents list_name. The description adds value with concrete examples ('Which departments exist?' -> list_name='department') and by restating the None/omit semantics in plain language, going slightly beyond the schema baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Look up the allowed values of HiBob's named lists.' It further clarifies that the tool resolves names to IDs used by hibob_create_position and hibob_update_position, making its distinct role among position-related siblings clear.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit context: position fields must come from named lists, and this tool should be used before creating or updating positions to convert names to list-item IDs. It does not mention when-not-to-use or contrast with an alternative lookup sibling, but none is apparent among the listed tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

hibob_list_workforce_fieldsA

Read-onlyIdempotent

List the fields available on a HiBob workforce planning object.

Call this before searching or creating anything: it returns the field IDs (such as '/position/fte') that every other tool in this server expects, along with each field's type and whether it is required.

Args: object_type: 'position', 'positionOpening' or 'positionBudget'.

Returns: str: JSON describing the available fields, as returned by HiBob.

Examples: - "What can I set on a position?" -> object_type='position' - "What does a budget need?" -> object_type='positionBudget' - Don't use when: you need the allowed values of a list field such as department or site (use hibob_get_company_named_lists).

Rate limit: 50 requests/minute.

ParametersJSON Schema

Name	Required	Description	Default
`object_type`	No	Which workforce planning object to describe.	position

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.9/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds useful behavioral context by stating the return format, that it returns field IDs/types/required flags, and the rate limit of 50 requests/minute.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured and front-loaded with the core purpose. It uses compact sections for args, returns, examples, exclusions, and rate limit without redundant filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

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, rich schema coverage, a full output schema, and comprehensive annotations, the description covers everything needed: when to call it, what it returns, and when to use an alternative.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already fully documents the single parameter with an enum and description, so the baseline is 3. The description adds extra value by giving natural-language examples mapping user intents to specific object_type values.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it lists available fields on a HiBob workforce planning object. It also distinguishes itself from sibling tools by explaining it returns the field IDs that every other tool expects, making its purpose and scope unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly says to call this before searching or creating anything. It also provides a concrete exclusion: don't use it for allowed list values, and names the sibling tool to use instead.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

hibob_search_position_budgetsA

Read-onlyIdempotent

Search position budgets: planned salary and total cost per position.

Use this for cost roll-ups across planned headcount, such as the total budgeted cost of every vacant position in a department.

Args: fields: Field IDs to return (1-50). filters: Optional filter clauses. limit: Page size, 1-100. cursor: Cursor from a previous page, or None to start. include_human_readable: Include display labels.

Returns: str: JSON of the form {"count": int, "entries": [...], "has_more": bool, "next_cursor": str}.

Rate limit: 100 requests/minute.

ParametersJSON Schema

Name	Required	Description
`limit`	No	Maximum entries per page.
`cursor`	No	Cursor from a previous page.
`fields`	Yes	Field IDs to return, 1-50, e.g. ['/positionBudget/expectedBaseSalaryCurrencyValue'].
`filters`	No	Optional filter clauses on budget fields.
`include_human_readable`	No	Also return display labels for each value.

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.2/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safe/read-only nature is established. The description adds useful behavioral context beyond annotations by stating the rate limit ('100 requests/minute') and the pagination contract via 'has_more' and 'next_cursor'.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured and front-loaded with purpose and use case, followed by compact Args, Returns, and Rate limit sections. It is slightly redundant with the schema's parameter descriptions, but overall every section earns its place and there is no fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers the essential operational details: what the tool returns, pagination fields, parameter constraints, rate limits, and a representative use case. Given that an output schema is present and annotations cover safety, nothing critical is missing for an agent to call this tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all parameters. The description mostly restates the schema, adding only minor practical details like 'None to start' for cursor and 'display labels' for include_human_readable, which does not significantly exceed the schema baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with 'Search position budgets' and specifies 'planned salary and total cost per position,' making the tool's subject and scope immediately clear. It is clearly distinguishable from sibling search tools like hibob_search_positions and hibob_search_position_openings because it focuses on budget/cost data.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly says 'Use this for cost roll-ups across planned headcount' and gives a concrete example, which tells the agent when to select this tool. It does not explicitly name alternatives or state when not to use it, but the use-case guidance is specific enough to route correctly.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

hibob_search_position_openingsA

Read-onlyIdempotent

Search position openings, the vacancies attached to positions.

Openings carry the recruitment view of a position: expected start date, recruitment status and whether the seat is vacant, starting, filled or departing.

Returns: str: JSON of the form {"count": int, "entries": [...], "has_more": bool, "next_cursor": str}. When "has_more" is true, call again passing "next_cursor" to retrieve the rest.

Examples: - "Which openings are still vacant?" -> filters=[{field_id: '/positionOpening/status', operator: 'equals', values: ['vacant']}]

Rate limit: 100 requests/minute.

ParametersJSON Schema

Name	Required	Description
`limit`	No	Maximum entries per page.
`cursor`	No	Pass the 'next_cursor' from a previous call to get the next page.
`fields`	Yes	Field IDs to return, 1-50, e.g. ['/positionOpening/id', '/positionOpening/status'].
`filters`	No	Optional filters. Filterable fields: '/positionOpening/id', '/positionOpening/status' (vacant, starting, filled, departing), '/positionOpening/positionOpeningName'.
`include_human_readable`	No	Also return display labels for each value.

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.6/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already mark the call as read-only and idempotent, and the description adds valuable behavioral details beyond them: pagination through has_more/next_cursor, the exact JSON return envelope, the instruction to call again with next_cursor, and a concrete rate limit of 100 requests/minute. Nothing in the description contradicts the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with purpose, args, returns, example, and rate limit. It is front-loaded and readable, though the Args section largely duplicates the input schema and could have been trimmed. The example and pagination details justify the overall length.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a paginated search tool, the description covers the full call lifecycle: required fields, optional filters, pagination loop, return envelope, rate limit, and a concrete usage example. The output schema covers return values and annotations cover safety, so no critical information is missing for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3; the description mostly restates parameter meanings but adds a worked filter example showing exactly how to encode field_id, operator, and values. It also clarifies the status domain (vacant, starting, filled, departing), which helps agents build correct filters without opening the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with 'Search position openings' and immediately defines them as 'the vacancies attached to positions,' which clearly identifies the resource and separates the tool from position-level searches. It also explains that openings carry the recruitment view, making the tool's domain concrete.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for when this tool is relevant: it exposes recruitment status, expected start date, and whether a seat is vacant/starting/filled/departing. It also includes a natural-language example ('Which openings are still vacant?') with the matching filter. However, it does not explicitly name alternatives or state when not to use this tool versus sibling search tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

hibob_search_positionsA

Read-onlyIdempotent

Search the company's positions.

Returns one entry per matching position. Each entry has 'values' (the raw values, including the IDs needed by the update tools) and 'display' (human-readable labels).

This endpoint has no pagination, so always request only the fields you need and filter where possible in a large organization.

Args: fields: Field IDs to return (1-50). filters: Optional filter clauses combined by HiBob. include_human_readable: Include display labels alongside raw values.

Returns: str: JSON of the form {"count": int, "entries": [{"values": {...}, "display": {...}}]}, or an error message beginning with "Error:".

Examples: - "Which positions are vacant?" -> fields=['/position/id', '/position/name'], filters=[{field_id: '/position/status', operator: 'equals', values: ['vacant']}] - Don't use when: you need opening-level detail such as expected start dates (use hibob_search_position_openings).

Rate limit: 100 requests/minute.

ParametersJSON Schema

Name	Required	Description
`fields`	Yes	Field IDs to return, 1-50 of them, e.g. ['/position/id', '/position/name', '/position/status'].
`filters`	No	Optional filters. Filterable fields: '/position/status', '/position/name', '/position/hasOpenRequests', '/position/id'.
`include_human_readable`	No	Also return display labels for each value.

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.6/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond annotations (readOnly, idempotent, non-destructive), the description discloses no pagination, rate limit of 100 requests/minute, and the response shape with values/display, including that values carry IDs needed by update tools. This gives agents actionable expectations for invocation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Well-sectioned with opening, return format, warning, args, returns, example, and rate limit. The Args section somewhat duplicates schema, but the overall structure is clear and front-loaded with key behavioral caveat (no pagination) early.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given rich annotations, complete schema, and the description's own return-shape and example, an agent can correctly invoke it, including constructing valid filters. It even covers rate limiting and differentiates from the closest sibling. Nothing essential is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents fields, filters, and include_human_readable. The description adds a concrete filter example ('Which positions are vacant?') and notes filters are combined by HiBob, a slight semantic addition, but largely restates parameter meaning. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a clear verb+resource: 'Search the company's positions.' It distinguishes from siblings by specifying one entry per matching position and explicitly contrasts with hibob_search_position_openings. No ambiguity about what resource is queried.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says 'Don't use when: you need opening-level detail... (use hibob_search_position_openings),' naming the alternative and the condition. It also advises requesting only needed fields and filtering in large organizations due to no pagination, which is practical usage context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

hibob_update_positionA

Idempotent

Change details of an existing position.

Only the fields supplied are modified. Use hibob_search_positions to find the position ID first.

Args: position_id: The position's ID. fields: Flat mapping of field IDs to new values.

Returns: str: JSON confirming the update, or an error message beginning with "Error:".

Examples: - "Move that position's start to October" -> fields with '/position/effectiveDate'.

Rate limit: 10 requests/minute.

ParametersJSON Schema

Name	Required	Description	Default
`fields`	Yes	Fields to change, as a flat mapping. Updatable: name, effectiveDate, managerPositionId, positionType, fte, employmentType, department, site, jobProfile, reason.
`position_id`	Yes	ID of the position to update.

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already establish readOnly=false, idempotent=true, and destructive=false. The description adds relevant behavior beyond annotations: only supplied fields are modified, the response is a JSON string or error, and there is a 10 requests/minute rate limit. No contradiction with annotations exists.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact and well-structured: purpose, partial-update semantics, prerequisite lookup tool, args, return format, example, and rate limit all appear in a tight, readable layout. Every section earns its place with no redundant filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a two-parameter tool with rich schema coverage, annotations, an output schema, and a clear example, the description provides all essential call-time information. An agent can correctly select the tool, find the required position ID, format the update payload, and interpret the result.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% description coverage, so the baseline is 3. The description adds value with the example mapping '/position/effectiveDate' and clarifies that fields is a flat mapping from field IDs to new values, helping agents construct valid payloads beyond the schema's field list.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with 'Change details of an existing position,' naming a specific verb and resource, and is reinforced by the title 'Update a HiBob position.' This makes it clearly distinct from sibling tools like create, cancel, or opening/budget updates.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly instructs agents to use hibob_search_positions first to find the position ID, which is a concrete precondition. It does not enumerate when to avoid this tool versus update_position_opening or update_position_budget, but the 'existing position' scope together with sibling names provides adequate context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

hibob_update_position_budgetA

Idempotent

Change an existing position budget.

Use hibob_search_position_budgets to find the budget ID.

Args: position_id: Parent position ID. budget_id: The budget's ID. fields: Flat mapping of field IDs to new values.

Returns: str: JSON confirming the update, or an error message beginning with "Error:".

Rate limit: 10 requests/minute.

ParametersJSON Schema

Name	Required	Description
`fields`	Yes	Budget fields to change, as a flat mapping.
`budget_id`	Yes	ID of the budget to update.
`position_id`	Yes	Parent position ID.

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate the operation is not read-only, is idempotent, and is not destructive. The description adds useful behavioral context beyond annotations by specifying the return format (JSON confirmation or error message prefixed with 'Error:') and the rate limit of 10 requests/minute.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well structured and front-loaded: a one-line action, lookup guidance, parameter explanations, return behavior, and rate limit. Every section earns its place with no filler or repetition of the annotations.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 3-parameter update tool with an output schema, the description is nearly complete: it explains how to find the budget ID, what the fields parameter means, what the response looks like, and the rate limit. It could further clarify whether unspecified fields are left unchanged, but this is largely inferable from 'fields to change.'

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already covers all three parameters with descriptions, so the baseline is 3. The description adds meaningful semantics by explaining that 'fields' is a 'flat mapping of field IDs to new values' and that 'position_id' is the parent position ID, reinforcing the relationship between the required parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with 'Change an existing position budget,' a specific verb+resource phrase that precisely identifies the tool's function. It also points to hibob_search_position_budgets for finding the budget ID, which implicitly distinguishes this update operation from the search and create siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives a clear usage step: use hibob_search_position_budgets to find the budget ID before calling this tool. It does not explicitly list exclusions or alternatives beyond that prereq, but the 'existing position budget' wording and sibling names make the intended usage unambiguous.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

hibob_update_position_openingA

Idempotent

Change an existing opening, such as its expected start date or recruitment status.

Args: position_id: Parent position ID. opening_id: The opening's ID. fields: Flat mapping of field IDs to new values.

Returns: str: JSON confirming the update, or an error message beginning with "Error:".

Rate limit: 10 requests/minute.

ParametersJSON Schema

Name	Required	Description
`fields`	Yes	Fields to change, e.g. {"/positionOpening/recruitmentStatus": "onHold"}.
`opening_id`	Yes	ID of the opening to update.
`position_id`	Yes	Parent position ID.

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A3.9/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the annotations, the description discloses the return format ('JSON confirming the update, or an error message beginning with Error:') and the rate limit (10 requests/minute). It does not expand on side effects or permission needs, but the annotations already convey read/write and destructiveness signals.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact and front-loaded with the core purpose, then follows a clear Args/Returns structure. The Args block is somewhat redundant with the schema, but overall it is efficient and readable.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Combined with the rich input schema, output schema signal, and annotations, the description covers the key invocation details: parameters, return behavior, and rate limiting. It does not exhaustively list all updatable fields, but the examples plus open fields schema make the tool usable.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description largely restates the parameter names and adds no significant meaning beyond the schema, though the schema's 'fields' example already provides formatting guidance.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific action—'Change an existing opening'—and gives concrete examples of what can change ('expected start date or recruitment status'). This clearly distinguishes it from create, cancel, delete, and budget-related siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'existing opening' implies the tool is for updating already-created openings, and the sibling names clarify lifecycle alternatives. However, the description does not explicitly state when to choose this over create_position_opening or delete_position_opening, nor does it mention any preconditions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

13 tool updatesv0.1.0Sep 4, 2026
- First observedhibob_cancel_position
- First observedhibob_create_position
- First observedhibob_create_position_budget
- First observedhibob_create_position_opening
- First observedhibob_delete_position_opening
- First observedhibob_get_company_named_lists
- First observedhibob_list_workforce_fields
- First observedhibob_search_position_budgets
- First observedhibob_search_position_openings
- First observedhibob_search_positions
- First observedhibob_update_position
- First observedhibob_update_position_budget
- First observedhibob_update_position_opening

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.4/5.0

Scored 2026-09-04 12:26 across 13 tools

Disambiguation5/5

Each tool targets a distinct resource-action pair: positions, openings, budgets, and metadata lookups are clearly separated. The naming and descriptions make it easy to pick the right tool, even for close operations like create_position vs create_position_opening.

Naming Consistency5/5

All tools follow a consistent hibob_verb_noun pattern with snake_case throughout, e.g., hibob_search_positions, hibob_create_position_budget, hibob_delete_position_opening. Resource terms are plural and actions are predictable across the set.

Tool Count5/5

Thirteen tools is well-scoped for a workforce planning server covering positions, openings, budgets, and supporting metadata lookups. Each tool earns its place and the count is neither bloated nor thin.

Completeness4/5

The server covers core lifecycle operations for positions, openings, and budgets, including search, create, update, and delete/cancel where relevant. A minor gap is the absence of a delete operation for position budgets, though create and update are covered.

Maintenance

ActivityMaintained

ResponsivenessUnresponsive

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

isolved-jobs-apiOAuth
io.github.johnisanerd
isolved and ApplicantPro jobs, tenant discovery, and change detection as an MCP server.
Monitoring
1
mcp-serverOAuth
io.klokin
MCP server exposing klokin time-tracking operations (employees, time entries, stores) to AI clients.
Workplace & Productivity Project Management
2
jumpcloud-genaiOAuth
com.jumpcloud
An MCP server that provides an API to LLMs to manage their JumpCloud resources.
Cloud Platforms Security Developer Tools
2
LemonadoOAuth
io.github.lemonadolabs
MCP server for querying and analyzing data from ad platforms, analytics tools, and spreadsheets
Marketing Research & Data Databases
3

Related MCP Servers

Personnel Data MCP Server
ERP Systems Developer Tools
ag2-mcp-servers
F
license
Not graded
quality
D
maintenance
An MCP Server that provides access to Personio's HR and personnel data through the Personnel API, allowing interaction with employee records, HR systems, and personnel management functions.
Updated a year ago (2025-07-16 14:24 UTC)
-
humaans-mcp
Databases
ptorsten
A
license
B
quality
D
maintenance
Read-only MCP server for the Humaans HRIS API, providing tools to query people, reporting chains, compensation, time away, and more.
Updated 4 months ago (2026-05-16 22:21 UTC)
33
MIT
Tipsoi MCP
ERP Systems
the-abraar
F
license
A
quality
D
maintenance
Read-only MCP server for the Tipsoi HRM API, exposing 15 tools to read employee data, attendance, leave, overtime, and more.
Updated 3 months ago (2026-06-29 06:36 UTC)
15
1
-
MCP Employee Identity Server
Workplace & Productivity AI & Machine Learning Data Platforms
Anshuman-Gaur-AI-Builder
A
license
Not graded
quality
D
maintenance
This MCP server enables AI-assisted professional profile generation by connecting to verified employee work data (skills, career history, certifications, projects) from employer HCM systems.
Updated 6 months ago (2026-03-23 14:58 UTC)
MIT

hibob-advanced-mcp

HiBob setup

Configuration

Running it

Claude Desktop

Plugging into a sandboxed MCP integration

Tools

Read

Write (omitted when HIBOB_READ_ONLY is set)

Field cheat sheet

Development

License

Available Tools

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Tool Schema Changelog

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

Write (omitted when `HIBOB_READ_ONLY` is set)