This server is a read-only MCP connector that lets AI assistants query a PeopleForce HRIS/ATS with 27 tools.
Browse employees, filter by employment status, fetch full profiles, and look up employees by email.
View employee position history, documents, and assigned assets.
Check time-off: leave requests, leave types, and company holidays.
Explore recruitment data: vacancies, candidates, pipelines, and sources.
Access reference data: departments, positions, locations, divisions, teams, job levels, job profiles, legal entities, employment types, genders, skills, competencies, assets, and tasks.
Use the raw api_request escape hatch to GET any PeopleForce v3 endpoint not covered by dedicated tools.
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., "@peopleforce-mcp Who is on vacation next week in the Engineering team?"
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.
A Model Context Protocol (MCP) server that connects Claude, Cursor, Claude Desktop, and any MCP-compatible LLM client to the PeopleForce HRIS / ATS.
27 read-only tools cover the PeopleForce v3 REST API — employees, time-off, recruitment, and all reference data — so your AI assistant can answer HR questions grounded in live company data without bouncing you back to the web app.
Built and maintained by Empat — a Ukrainian custom software development company. We ship this connector as open source to make AI-assisted HR automation a commodity for every PeopleForce customer.
PeopleForce is one of the fastest-growing HRIS platforms in Eastern Europe, but as of 2026 it has no official MCP connector. That means Claude, Cursor, and other LLM agents can't answer questions like:
"Who is on vacation next week in the Back-end department?"
"How many people are currently on probation?"
"List all open Senior iOS vacancies we haven't filled for 30+ days."
"What leave balance does jane.doe@example.com have left this quarter?"
peopleforce-mcp fixes that. It is a minimal, read-only, fetch-based TypeScript server that lives on GitHub and plugs into any MCP client in a couple of commands.
Related MCP server: Tipsoi MCP
✅ 27 tools across employees, time-off, recruitment, tasks, assets, and reference data.
✅ Read-only by design — the 0.x line never mutates your PeopleForce data.
✅ Clone & run — no registry accounts required, deploy from GitHub in under a minute.
✅ Actionable errors — 401 tells you to check your key, 404 tells you the endpoint isn't on v3.
✅ Built-in pagination plus a find_employee_by_email workflow tool that paginates for you.
✅ Escape hatch — api_request lets your agent hit any v3 GET endpoint not yet modelled.
✅ Node.js 18 / 20 / 22 — covered by CI.
✅ Typed end-to-end, smoke-tested over stdio.
PeopleForce → Settings → Open API keys → Generate.
Pick the Company API key (full read access to employee data). Optionally restrict it to your IP range on the PeopleForce allow-list.
Requires Node.js 18 or newer and git.
git clone https://github.com/EmpatDevelopment/peopleforce-mcp.git ~/peopleforce-mcp
cd ~/peopleforce-mcp
npm install
npm run buildThat produces ~/peopleforce-mcp/dist/index.js, which is the only file your MCP client needs to launch.
Claude Code
claude mcp add peopleforce --scope user \
--env PEOPLEFORCE_API_KEY=your_key_here \
-- node "$HOME/peopleforce-mcp/dist/index.js"Claude Desktop — edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):
{
"mcpServers": {
"peopleforce": {
"command": "node",
"args": ["/absolute/path/to/peopleforce-mcp/dist/index.js"],
"env": { "PEOPLEFORCE_API_KEY": "your_key_here" }
}
}
}Cursor — paste the same JSON into ~/.cursor/mcp.json under mcpServers.
Detailed per-client guides with screenshots-friendly JSON snippets are in examples/.
All configuration is passed via environment variables.
Variable | Default | Purpose |
| required | Your PeopleForce Company API key. |
|
| Override if PeopleForce hosts you on a non-default endpoint. |
|
| Per-request timeout. Slow PeopleForce responses are aborted and retried. |
|
| Max automatic retries for |
|
| Base for exponential backoff with full jitter. Retry-After headers are honoured. |
cd ~/peopleforce-mcp && git pull && npm install && npm run buildRestart your MCP client after each update.
"How many people are on probation right now, and which departments are they in?"
The model will call peopleforce_list_employees with status=probation, paginate through the results, and summarise.
Every tool is prefixed with peopleforce_ and is read-only. All list tools accept page (≥ 1) and per_page (≤ 100).
Tool | Purpose |
| Paginated roster; filter by |
| Full profile by numeric |
| Looks up an employee by work or personal email; paginates internally. |
| Position / role history for one employee. |
| Documents attached to one employee. |
| Assets assigned to one employee. |
Tool | Purpose |
| Filter by |
| Vacation, sick, optional holiday, etc. |
| Official company holidays. |
Tool | Purpose |
| Open & closed jobs. |
| Candidates in the pipeline. |
| Pipelines and their stages. |
| Where candidates came from. |
list_departments, list_positions, list_locations, list_divisions, list_teams, list_job_levels, list_job_profiles, list_legal_entities, list_employment_types, list_genders, list_skills, list_competencies, list_assets, list_tasks.
api_request — raw GET against any /api/public/v3/<path> with an optional query object. Use it when the endpoint you need isn't modelled above, and consider opening a PR to promote it to a first-class tool.
Could not attach to MCP server peopleforce / Server disconnected
Check the client log for the underlying stderr — the toast never carries it.
Log | Client |
| Claude Desktop (macOS) |
| Claude Code |
Two failure modes account for almost all of these:
Error: Cannot find module '.../dist/index.js' — the absolute path in your client config no longer exists. Every client config stores its own copy of that path, so moving or re-cloning the repo breaks each one independently. Fix the args entry, then fully restart the client (config is read at startup).
ERROR: PEOPLEFORCE_API_KEY env var not set — the key is missing from the env block of that config. The server refuses to start without it rather than failing later on every call.
If the path and key are both correct, run the server by hand — a clean handshake rules out the server itself:
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"probe","version":"1"}}}' \
| PEOPLEFORCE_API_KEY=your_key_here node dist/index.jsThis server requires a PeopleForce Company API key, which is effectively read access to your entire employee database. Read SECURITY.md for full guidance — tl;dr:
Store it only in PEOPLEFORCE_API_KEY (env var or your MCP client's encrypted config).
Never commit it; never paste it into chat, Slack, or Notion.
Rotate immediately if leaked (PeopleForce → Settings → Open API keys → Revoke + Generate).
Restrict to allow-listed IPs where your MCP client runs.
git clone https://github.com/EmpatDevelopment/peopleforce-mcp.git
cd peopleforce-mcp
npm install
npm test # unit + stdio smoke tests (no PeopleForce account required)
npm run build
PEOPLEFORCE_API_KEY=xxx node dist/index.js # run locallyFull contribution guide: CONTRIBUTING.md.
Does it write to PeopleForce? No. 0.x is read-only by design. Mutating tools would be opt-in via a future feature flag.
Does it store my data anywhere? No. The server is a stateless stdio proxy between your MCP client and the PeopleForce API. Requests never leave the process.
Is it rate-limited? PeopleForce rate-limits the API itself. The server surfaces any 429 responses as actionable errors; it does not retry automatically.
Which PeopleForce plans are supported? Any plan that exposes the v3 API. The Career key has a narrower scope (vacancies only) and will 404 on most tools — use a Company key.
Can I self-host it? Yes — it's pure Node.js 18+. Run node dist/index.js inside any container with the env var set.
Empat is a product-focused custom software development company based in Lviv, Ukraine. Since 2013 we have delivered 300+ projects across 23 markets — including fintech software development, AI software development, SaaS development, and custom mobile app development for Y Combinator alumni, Fortune 500 companies, and 19 Forbes 30 Under 30 founders.
Ways we work with clients:
Full product development — Discovery, PoC, MVP, launch, growth.
CTO as a service for early-stage founders.
Dedicated developer hiring and IT staff augmentation (iOS, Android, Flutter, React Native, Node.js, Python, .NET, QA, DevOps, Design).
Product validation and consulting.
Industries we serve: healthcare (remote monitoring, tele-consultations), fintech (payments, banking, commissions), social networks, education, entertainment & gaming, e-commerce.
5.0 on Clutch · Top 100 Fastest Growth 2026 · 300+ delivered products · $380M raised by clients in 2023.
👉 empat.tech — tell us what you're building.
MIT © 2026 Empat.
Escape hatch: perform a raw GET against any PeopleForce v3 API path (relative to /api/public/v3). Use when no dedicated tool covers the endpoint. Example path: 'employees/12345' or 'leave_requests?state=approved'.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Path relative to /api/public/v3 (no leading slash needed). | |
| query | No | Optional query params as key-value pairs. Values will be stringified. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, destructiveHint=false. Description adds context about raw GET and escape hatch nature, aligning with annotations 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?
Two sentences, every word earns its place. Front-loaded with 'Escape hatch' and clearly structured.
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 an escape hatch tool with good annotations and two parameters, description covers purpose, usage, and examples. No output schema needed for raw GET.
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 example paths but does not significantly extend beyond schema details.
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 performs a raw GET against any PeopleForce v3 API path, and distinguishes itself from sibling tools by positioning as an escape hatch when no dedicated tool covers the 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 says 'Use when no dedicated tool covers the endpoint' and provides example paths. Does not explicitly state when not to use, but implication is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find a single employee by work or personal email. Paginates internally until a match is found. Returns the full employee object or null.
| Name | Required | Description | Default |
|---|---|---|---|
| Yes | Work or personal email (case-insensitive). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare read-only and non-destructive; description adds internal pagination detail and return value (full object or null), providing 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?
Two concise sentences with no wasted words, front-loaded with the core action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter tool with no output schema, the description sufficiently covers purpose, internal behavior, and return value.
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 description; the tool description adds case-insensitivity but little new 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 that the tool finds a single employee by email, distinguishing it from siblings like peopleforce_get_employee (by ID) and list 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 implies usage for finding by email but does not explicitly state when to use this versus peopleforce_get_employee 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.
Get a single employee by PeopleForce id. Returns full profile including position, department, manager, custom fields.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Employee id (numeric). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations (readOnlyHint, openWorldHint, destructiveHint) already indicate safe, non-destructive read with complete data. The description adds value by specifying the returned content (position, department, manager, custom fields), going 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?
Single sentence, front-loaded with action and resource, no waste. Every word is necessary and clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple retrieval tool with one parameter, no output schema, and strong annotations, the description is complete. It explains purpose, identifier, and return scope without 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 coverage is 100% with clear parameter description ('Employee id (numeric)'). The description does not add further meaning beyond 'by PeopleForce id', so baseline of 3 applies.
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 a single employee by PeopleForce id and lists the returned fields (full profile, position, department, manager, custom fields). It distinguishes from sibling tools like peopleforce_list_employees (multiple) and peopleforce_find_employee_by_email (different lookup).
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 when you have a specific employee id and need full details, but does not explicitly state when to use this tool versus alternatives (e.g., for listing or email lookup). No exclusions or context provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all assets/equipment in the company.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number (1-based). Default 1. | |
| per_page | No | Items per page (max 100). Default 50. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the description is consistent. However, it adds no extra behavioral context beyond 'list all', such as pagination behavior or the fact that no filtering is possible. With annotations, this is adequate but not enhanced.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the core purpose. No unnecessary words or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with two parameters and full schema coverage, the description is adequate. However, it could be more complete by noting that it returns a paginated list of all assets (no employee filter), especially given many similar list siblings.
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% for both parameters (page and per_page). The description does not add any additional meaning beyond what the schema already provides. 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?
The description clearly states the tool lists assets/equipment in the company, with a specific verb and resource. However, it does not differentiate from sibling tools like 'peopleforce_list_employee_assets', which lists assets for a specific employee.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. For example, it does not mention that this lists all company assets, while 'peopleforce_list_employee_assets' is for a specific employee. Also, no instruction on pagination or filtering.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List competencies used in performance reviews.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number (1-based). Default 1. | |
| per_page | No | Items per page (max 100). Default 50. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only and non-destructive behavior. Description adds minimal context about the domain (performance reviews) but does not deepen transparency 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?
Single sentence with no wasted words, front-loaded with verb and resource. Appropriate length for its simplicity.
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?
Adequate for a simple list tool with pagination parameters, but lacks mention of return format or pagination metadata. Given annotations and schema richness, it is minimally complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters fully. Description adds no additional parameter-specific meaning beyond 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?
Description clearly states verb 'List' and resource 'competencies' with context 'used in performance reviews', distinguishing it from sibling tools like 'peopleforce_list_skills'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives. With many sibling list tools, such direction would be helpful.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all departments with manager and parent info.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number (1-based). Default 1. | |
| per_page | No | Items per page (max 100). Default 50. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate the tool is read-only and non-destructive. The description adds that the response includes manager and parent info, but does not cover pagination or rate limits, which are partially addressed by schema descriptions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no redundancy, front-loaded with key information. 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?
Given the simplicity of the tool (list with pagination), good annotations, and full schema coverage, the description is nearly complete. It lacks return format details but output schema is absent, so the description adequately covers the core functionality.
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 both parameters having clear descriptions. The tool description does not add any further meaning beyond what the schema already provides, so 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?
The description clearly states the verb 'List', the resource 'departments', and specifies that it includes 'manager and parent info', distinguishing it from sibling tools like list_divisions or list_teams.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. Among many sibling list tools, the description does not help an agent decide when to choose this one.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List organizational divisions.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number (1-based). Default 1. | |
| per_page | No | Items per page (max 100). Default 50. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnly and non-destructive behavior. The description does not add behavioral context beyond what annotations provide, but it does not contradict 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?
Single sentence that is front-loaded and contains no fluff. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is sufficient for a simple list tool with well-schema'd parameters, but it does not clarify the return format or that results are paginated, which would be helpful without 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?
The schema has 100% coverage with descriptions for page and per_page. The description adds no additional parameter 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 verb 'list' and resource 'organizational divisions', distinguishing it from sibling tools like list_departments or list_teams. However, it lacks additional detail about scope or hierarchy.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus the many sibling list tools. It does not provide any context for selection or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List assets/equipment assigned to a specific employee.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | ||
| per_page | No | ||
| employee_id | Yes | Employee id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the description adds no new behavioral context. It restates the resource scope but not additional traits like pagination behavior or data freshness.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence front-loading the purpose with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is straightforward (list by employee), but with no output schema and incomplete parameter descriptions, the description leaves gaps about return structure and pagination. Adequate but not thorough.
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 33%, with only 'employee_id' having a description in the schema. The tool description reinforces the employee-specific nature but does not explain 'page' and 'per_page' parameters, which remain undocumented.
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 assets/equipment assigned to a specific employee, distinguishing it from the sibling 'peopleforce_list_assets' which likely lists all 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 getting assets of a specific employee but does not explicitly state when to use it versus 'peopleforce_list_assets' or other siblings. No exclusion or alternative guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List documents attached to a specific employee's profile.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | ||
| per_page | No | ||
| employee_id | Yes | Employee id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the bar is lower. The description adds no additional behavioral context beyond what annotations provide, which is acceptable but not additive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no unnecessary words, front-loaded with action and resource.
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 3 parameters and no output schema, the description is too minimal. It does not mention pagination, expected response format, or any constraints, leaving the agent with incomplete context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 33%, and the description does not explain the meaning or purpose of 'page' or 'per_page' parameters. Only employee_id is described in the schema; the description adds no extra clarification.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (list) and resource (documents attached to a specific employee's profile), distinguishing it from sibling tools like peopleforce_list_employees or peopleforce_list_employee_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?
No guidance on when to use this tool vs alternatives, no mention of required employee_id or pagination parameters, and no context about prerequisites or use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List position history for a specific employee (promotions, role changes, compensation).
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | ||
| per_page | No | ||
| employee_id | Yes | Employee id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and destructiveHint. Description adds that it covers promotions, role changes, compensation. However, no mention of pagination, ordering, or whether it includes current position.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with verb and resource, no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with 3 params and no output schema, description adequately explains what the tool returns. Could add a note about pagination to be 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 low (33%); only employee_id has a description. The description reinforces employee_id usage but does not clarify page and per_page parameters. Schema already provides types, but description should explain pagination.
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 position history for a specific employee, with specific examples (promotions, role changes, compensation). Distinct from siblings like peopleforce_list_positions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies use with specific employee via employee_id, but no explicit guidance on when to use vs alternatives or when not to use. Siblings like peopleforce_list_positions exist, but no comparison.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List employees with pagination. Only the status filter is applied server-side; filter other attributes client-side or use peopleforce_find_employee_by_email.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number (1-based). Default 1. | |
| status | No | Employment status filter (server-side). | |
| per_page | No | Items per page, max 100. Default 50. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnlyHint, destructiveHint), description adds that pagination is supported and only status filter is server-side, giving operational constraints. Could mention if pagination metadata is returned, but still good.
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: first states purpose, second provides essential usage guidance. No redundancy, perfectly concise.
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?
Lacks output schema and does not describe return structure (e.g., fields per employee), but given many related tools likely share same employee object, it's acceptable. Still could be more 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 already covers all parameters with descriptions (100% coverage), but description adds context that status is the only server-side filter, enhancing meaning 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 'List employees with pagination' and distinguishes from sibling tool by specifying that only status filter is server-side, implying other filters are not supported server-side, thus differentiating from peopleforce_find_employee_by_email.
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 advises to filter other attributes client-side or use peopleforce_find_employee_by_email, providing clear when-to-use and alternative pathways.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List employment types (Full-time, Part-time, Contractor, etc).
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number (1-based). Default 1. | |
| per_page | No | Items per page (max 100). Default 50. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint: true and destructiveHint: false, so the description's main behavioral addition is providing example values (Full-time, Part-time, Contractor). It does not disclose ordering, caching, or rate limits beyond what annotations indicate. With strong annotations, the bar is lower, but the description only adds minimal context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is front-loaded and contains no unnecessary words or details. It efficiently conveys the tool's purpose without excess.
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 adequate for a simple paginated list tool. It explains what is being listed and provides examples. No output schema exists, but pagination parameters are standardly documented in the schema. The description could hint at return fields but is not required. It is mostly complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (both page and per_page are described in the input schema). The description does not add any additional meaning about parameters. Per guidelines, baseline is 3 when schema coverage is high, and no extra value is provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' and the resource 'employment types', with examples (Full-time, Part-time, Contractor) making the purpose specific and unambiguous. It distinguishes from sibling tools which list other entities (e.g., employees, departments).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context (when you need employment types) but does not provide explicit when-to-use, when-not-to-use, or alternative comparisons among the 26 sibling list tools. No guidance on prerequisites or limitations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List gender reference values used in profiles.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number (1-based). Default 1. | |
| per_page | No | Items per page (max 100). Default 50. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. Description adds no new behavioral insights beyond listing reference values.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, zero waste. Efficiently conveys the tool's 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?
Given simple tool, full schema coverage, and annotations, the description is sufficient. No output schema needed for listing reference values.
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 covers 100% of parameters with descriptions (page, per_page). Description adds no additional 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?
The description clearly states the tool lists gender reference values from profiles, distinguishing it from other list tools. Specific verb 'List' and resource 'gender reference values'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool vs siblings like peopleforce_list_employment_types. The context of gender values is implied but not differentiated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List official company holidays.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number (1-based). Default 1. | |
| per_page | No | Items per page (max 100). Default 50. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds no behavioral context beyond what annotations already provide. Annotations indicate readOnlyHint=true and destructiveHint=false, but the description does not elaborate on return format, pagination behavior, or any side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence with no extraneous information. It is front-loaded and every word is necessary.
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 pagination parameters documented in the schema, the description is fairly complete. It could mention that it returns a paginated list of holidays, but the core purpose is clear.
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% (both 'page' and 'per_page' have descriptions). The description does not add any additional meaning beyond what the schema provides, so the baseline of 3 applies.
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 'List official company holidays' clearly states the action (list) and the resource (official company holidays). It distinguishes the tool from other list_* siblings such as list_leave_requests or list_employees by specifying the exact resource.
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 lacks any guidance on when to use this tool versus alternatives, such as when you need holiday data for a specific period. No when-to-use or when-not-to-use information is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List job levels (Junior/Middle/Senior/etc).
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number (1-based). Default 1. | |
| per_page | No | Items per page (max 100). Default 50. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and destructiveHint=false, so the description doesn't need to restate safety. The description adds the example values but no additional behavioral traits like pagination or rate limits. With good annotations, this is adequate.
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?
Ultra-concise single sentence that conveys all necessary information without extraneous content. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with no output schema, the description is sufficient. It could optionally mention the return format, but not required. Annotations and schema cover the essentials.
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% (both parameters have descriptions). The description adds no extra meaning 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.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the action (list) and resource (job levels) with examples (Junior/Middle/Senior/etc), making the purpose very clear. It distinguishes itself among the many sibling list tools by specifying job levels.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like list_competencies or list_departments. While the purpose is clear, the description lacks any contextual or comparative usage advice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List job profiles (role descriptions).
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number (1-based). Default 1. | |
| per_page | No | Items per page (max 100). Default 50. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a read-only, non-destructive operation. The description adds no further behavioral context beyond the resource type, but does not contradict annotations. A score of 3 is appropriate given annotations provide baseline safety info.
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 at 5 words, with no wasted text. It is front-loaded with the core action. However, it may be too brief for some contexts, but as conciseness is valued, a 4 is fair.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and the complexity of a paginated list, the description lacks details on pagination behavior, result structure, or filtering. It does not fully equip the agent to understand the tool's capabilities.
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 no parameter-specific details; page and per_page are explained only by the schema. This is adequate but does not enhance understanding.
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 job profiles and clarifies they are 'role descriptions'. It uses a specific verb+resource pattern, distinguishing it from sibling tools like list_employees or list_positions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites, exclusions, or preferred contexts, leaving the agent without decision support.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List leave/time-off requests. Useful for 'who's on vacation', balance queries, approvals. Supports employee_id and state filters.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | ||
| state | No | Filter by approval state. | |
| per_page | No | ||
| employee_id | No | Filter by employee. | |
| leave_type_id | No | Filter by leave type id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations (readOnlyHint=true, destructiveHint=false) already establish safety. Description adds the fact that filtering by employee_id and state is supported, which goes beyond annotations. However, it does not disclose pagination behavior (page, per_page) or potential rate limits. Behavioral details are adequate but not exhaustive.
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 purpose, no redundant words. Every sentence adds distinct value: purpose, usage scenarios, and filter support. Ideal conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for a simple read-only list tool: covers purpose, usage, and key filters. Lacks explanation of pagination (page/per_page) and response format (no output schema). With 5 parameters and no output schema, more context would help agents invoke 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?
Schema description coverage is 60% (page and per_page lack descriptions). The description mentions support for employee_id and state filters, adding value. However, it does not explain page and per_page (pagination) or leave_type_id, which the schema does describe. The description partially compensates for schema gaps but not fully.
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 verb 'List' and resource 'leave/time-off requests'. Gives concrete use cases ('who's on vacation', balance queries, approvals). However, does not explicitly differentiate from sibling list tools (e.g., list_employees, list_leave_types), which slightly reduces uniqueness clarity for an agent.
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 contextual usage hints ('who's on vacation', balance queries, approvals) but offers no guidance on when NOT to use this tool versus alternatives. Missing conditions like 'use list_leave_types for type definitions' or 'use list_employees for employee directory'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List leave/time-off types (Vacation, Sick, Optional holiday, etc) with units and colors.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number (1-based). Default 1. | |
| per_page | No | Items per page (max 100). Default 50. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, indicating a safe read operation. The description adds that it lists with units and colors but does not disclose additional behavioral traits like pagination or rate limits. The description 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?
The description is a single, front-loaded sentence with no superfluous words. It efficiently communicates the tool's purpose and output content.
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 pagination parameters but no output schema, the description is somewhat complete in stating what is returned (units, colors). However, it omits details on pagination behavior or response structure, leaving gaps for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 100% coverage for its two parameters (page, per_page), each described in the schema. The tool description does not add any parameter-specific information beyond what the schema provides, so it meets 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 uses specific verb 'List' and resource 'leave/time-off types', provides examples (Vacation, Sick, Optional holiday), and mentions output fields (units, colors). This clearly distinguishes it from sibling list 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 implies usage for retrieving leave types, but provides no explicit guidance on when to use it versus alternatives or any prerequisites. It is adequate but lacks direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List legal entities employees are contracted under.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number (1-based). Default 1. | |
| per_page | No | Items per page (max 100). Default 50. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and destructiveHint, so the description adds scope context but doesn't disclose pagination behavior or return format 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 a single, front-loaded sentence with no wasted words, efficiently conveying the tool's 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 read-only list tool with well-documented pagination parameters and no output schema, the description is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for both parameters; the description adds no additional 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?
The description clearly states the tool lists legal entities and specifies the scope (employees are contracted under), distinguishing it from other list 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 provides a clear context (listing legal entities for employee contracting) but does not include explicit when-to-use or when-not-to-use guidance or alternatives among sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List office/remote locations.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number (1-based). Default 1. | |
| per_page | No | Items per page (max 100). Default 50. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. Description adds the scope 'office/remote locations' but provides no further behavioral details 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 single sentence that is front-loaded and contains no wasted words. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool is simple with two parameters and no output schema. Description states the resource type but omits hints about response structure or pagination behavior, leaving some gaps for a 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?
Input schema has 100% coverage with descriptions for both parameters (page, per_page). Description adds no additional meaning beyond the schema, so baseline 3 applies.
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 uses specific verb 'List' and resource 'office/remote locations', clearly distinguishing it from sibling list tools for different entities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool vs alternatives. While siblings list different entities, no context is provided for typical use cases or when to prefer this over the generic api_request tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all position titles used in the company.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number (1-based). Default 1. | |
| per_page | No | Items per page (max 100). Default 50. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, destructiveHint, and openWorldHint, so the description does not add new behavioral context. It confirms the read operation but adds nothing beyond 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no unnecessary words. It is front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with good annotations and schema coverage, the description is nearly complete. It could mention pagination or output format, but the basic function is clear.
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% (both parameters have descriptions). The description does not add any parameter meaning beyond the schema, so 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?
The description clearly states it lists all position titles in the company, using a specific verb and resource. It distinguishes itself from sibling tools that list other entities like employees or departments.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention when not to use it or any prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List candidates in the ATS pipeline.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number (1-based). Default 1. | |
| per_page | No | Items per page (max 100). Default 50. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the read-only nature is clear. The description adds no further behavioral details (e.g., pagination behavior, ordering, or total count availability), but 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?
The description is a single, clear sentence with no fluff. Every word adds value, making it highly concise and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (two integer parameters, no output schema), the description is adequate but lacks details on default ordering, filtering capabilities, or return format. This is a minor gap for a paginated list.
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%. Both parameters (page, per_page) are fully described in the schema. The description adds no additional parameter semantics 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 'List candidates in the ATS pipeline,' specifying the verb (list), resource (candidates), and scope (ATS pipeline). This distinguishes it from siblings like peopleforce_list_recruitment_pipelines.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. There is no mention of exclusions, prerequisites, or context for choosing this over other list tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List recruitment pipelines with their stages.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number (1-based). Default 1. | |
| per_page | No | Items per page (max 100). Default 50. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds no additional behavioral traits beyond stating the basic function. 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?
Single sentence with no filler. Front-loaded with the action and resource. Every word is necessary.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool is simple with paginated list. Description could mention pagination behavior or ordering, but given the annotations and schema, it is mostly complete. No output schema to explain. Minor gap.
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% for both parameters (page, per_page). The description adds no extra meaning or formatting details beyond the schema, so 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 'List recruitment pipelines with their stages.' clearly states the verb (list), resource (recruitment pipelines), and scope (with stages), distinguishing it from sibling tools like list_recruitment_candidates.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives. The name implies a straightforward list, but context like pagination or relationships to other entities is missing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List recruitment sources (where candidates came from).
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number (1-based). Default 1. | |
| per_page | No | Items per page (max 100). Default 50. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, and destructiveHint, so the description carries less burden. It adds the context of what sources represent, but does not describe pagination behavior, rate limits, or any side effects beyond what annotations imply.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with action and resource, no extraneous words. Every part earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with no output schema and 100% schema coverage, the description is minimally adequate. However, it lacks any explanation of sorting, filtering, or expected response structure, which could be helpful for a tool with many sibling list operations.
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 both parameters described. The description adds no additional meaning beyond the schema, so baseline score 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 verb 'List' and the resource 'recruitment sources', adding the clarifying parenthetical 'where candidates came from'. This distinguishes it from sibling list tools like peopleforce_list_employees.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives such as peopleforce_list_recruitment_candidates or other list tools. Context implies it's for listing source options, but no explicit when-to-use or when-not-to-use information.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List open and closed vacancies in the ATS.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number (1-based). Default 1. | |
| per_page | No | Items per page (max 100). Default 50. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds minimal behavioral info (returns both open and closed vacancies). No mention of pagination behavior, rate limits, or response structure.
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 single sentence with no redundancy. Front-loaded key information: verb, resource, and scope.
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 paginated list with good annotations and full schema coverage, the description is sufficiently complete. It identifies the resource and status filter, though it omits output format details (but no output schema exists).
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% for both parameters (page, per_page). The description adds no extra meaning beyond the schema, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List', the resource 'vacancies', and the scope 'open and closed'. It distinguishes the tool from sibling list tools (e.g., peopleforce_list_recruitment_candidates) by specifying vacancies.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives, prerequisites, or when not to use. The description lacks contextual usage instructions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List skills tracked in the skills matrix.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number (1-based). Default 1. | |
| per_page | No | Items per page (max 100). Default 50. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the description adds no behavioral context beyond the verb 'list'. It does not mention pagination behavior, response size limits, or any side effects beyond what annotations already convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence with no wasted words. It is appropriately sized for a simple listing function.
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 no output schema, the description provides the basic purpose but does not specify what fields are returned (e.g., skill names, IDs). It is minimally viable but lacks completeness for an agent to fully infer the response format.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for both parameters (page, per_page). The tool description does not add further meaning, so the baseline score 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 'List skills tracked in the skills matrix' clearly states the verb (list), resource (skills), and scope (skills matrix), distinguishing it from sibling list tools like peopleforce_list_departments or peopleforce_list_locations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, no prerequisites, and no mentioned context that would help an agent decide. It is purely a statement of function.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List tasks assigned across the organization (onboarding, offboarding, HR actions).
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number (1-based). Default 1. | |
| per_page | No | Items per page (max 100). Default 50. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true and destructiveHint=false. The description adds task types but doesn't disclose additional behavioral traits like rate limits or auth needs 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?
Single sentence with no redundancy. Front-loaded with key information about what the tool does.
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?
Adequate for a safe read tool with good annotations, but lacks details on pagination, response structure, or any specifics beyond the description.
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% for the two parameters (page, per_page), which are fully described. The description does not add parameter 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?
The description clearly states the verb 'list', resource 'tasks', and scope 'assigned across the organization (onboarding, offboarding, HR actions)'. It distinguishes this tool from siblings like peopleforce_list_employees.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or when-not-to-use guidance, nor alternatives mentioned. The context of sibling tools implies distinct resources, but no direct comparison.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List teams (cross-functional groupings).
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number (1-based). Default 1. | |
| per_page | No | Items per page (max 100). Default 50. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false. The description adds 'cross-functional groupings' but provides no additional behavioral traits (e.g., pagination behavior, rate limits, or result structure beyond schema).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with parenthetical is concise and front-loaded. No wasted words, though it could be slightly more 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?
For a simple list tool with no output schema and only pagination parameters, the description is adequate but lacks usage context that would help an agent decide when to use it over similar tools.
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 adequate descriptions for 'page' (1-based, default 1) and 'per_page' (max 100, default 50). The tool description adds no parameter-specific information, so 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?
The description clearly states the verb 'List' and resource 'teams', with parenthetical explanation 'cross-functional groupings' to clarify the concept. This distinguishes it from sibling tools like peopleforce_list_departments or peopleforce_list_divisions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs. alternatives. The description does not mention any context, prerequisites, or exclusions, leaving the agent to infer from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.2.0peopleforce_api_requestpeopleforce_find_employee_by_emailpeopleforce_get_employeepeopleforce_list_assetspeopleforce_list_competenciespeopleforce_list_departmentspeopleforce_list_divisionspeopleforce_list_employee_assetspeopleforce_list_employee_documentspeopleforce_list_employee_positionspeopleforce_list_employeespeopleforce_list_employment_typespeopleforce_list_genderspeopleforce_list_holidayspeopleforce_list_job_levelspeopleforce_list_job_profilespeopleforce_list_leave_requestspeopleforce_list_leave_typespeopleforce_list_legal_entitiespeopleforce_list_locationspeopleforce_list_positionspeopleforce_list_recruitment_candidatespeopleforce_list_recruitment_pipelinespeopleforce_list_recruitment_sourcespeopleforce_list_recruitment_vacanciespeopleforce_list_skillspeopleforce_list_taskspeopleforce_list_teamsScored across 28 tools
Each tool targets a distinct entity or action. List tools all differ by the entity they list (e.g., assets, competencies, departments), and lookup tools (get, find) are clearly separated from lists. No overlap in purpose.
All tools follow a consistent pattern: 'peopleforce_' + verb (list, get, find) + '_' + entity. The verb clearly indicates the action, and all names use lowercase with underscores, ensuring predictability.
With 28 tools, the server exceeds the typical well-scoped range of 3-15 and falls into the 'too many' category (25+). While the HR domain has many entities, the sheer number of list tools feels excessive, especially since many are simple reference data lookups.
The tool set is heavily skewed towards read-only list operations. Missing dedicated create/update/delete tools for core entities like employees and leave requests, forcing agents to rely on the raw API escape hatch. This leaves significant gaps in typical HR workflows.
Read and edit GA4, Search Console and Google Tag Manager from any MCP client. 29 tools.
Query your org's data in natural language — read-only MCP access to SQL, NoSQL, files & warehouses.
Read-only MCP server for Muovi, Argentina's trust-first local services marketplace (6 tools).
Read-only MCP tools for AI agent discovery, structured resources, and NIULAI information.
