Click on "Install 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., "@Ashby MCP Server Show me the latest candidates for the Senior Backend Engineer role"
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 to your Ashby ATS. Browse jobs, manage candidates, track applications through your hiring pipeline, and more — all through natural conversation.
Python 3.10+
uv — a fast Python package manager
An Ashby API key with candidatesRead, jobsRead, and candidatesWrite permissions
Generate one at https://app.ashbyhq.com/admin/api/keys
Related MCP server: Ashby MCP
If you don't already have uv installed:
# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# macOS via Homebrew
brew install uvAfter installing, find the absolute path to the uvx command (you'll need this for the config):
which uvxThis will return something like /Users/yourname/.local/bin/uvx. Keep this path handy.
Go to https://app.ashbyhq.com/admin/api/keys and create a new API key. Make sure it has at least:
candidatesRead
jobsRead
candidatesWrite (if you want to create candidates, add notes, or move applications)
Open your Claude Desktop config file:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Add the following to the mcpServers section, replacing the placeholders with your actual values:
{
"mcpServers": {
"ashby": {
"command": "/absolute/path/to/uvx",
"args": [
"--from", "git+https://github.com/PlenishAI/mcp-ashby.git",
"ashby"
],
"env": {
"ASHBY_API_KEY": "your-ashby-api-key"
}
}
}
}Important: Replace
/absolute/path/to/uvxwith the output fromwhich uvx(e.g./Users/yourname/.local/bin/uvx). Claude Desktop does not inherit your shell's PATH, so the full path is required.
Quit and reopen Claude Desktop. The Ashby server should connect automatically. You can verify by asking Claude something like "list my open jobs in Ashby."
If the git+ URL method doesn't work (e.g. private repo or network restrictions), you can clone the repo locally:
git clone https://github.com/PlenishAi/mcp-ashby.git ~/projects/mcp-ashbyThen use uv (not uvx) in your config, pointing to the local directory:
{
"mcpServers": {
"ashby": {
"command": "/absolute/path/to/uv",
"args": [
"--directory", "/absolute/path/to/mcp-ashby",
"run", "ashby"
],
"env": {
"ASHBY_API_KEY": "your-ashby-api-key"
}
}
}
}Note: When using a local clone, run
which uvto get the path — the command isuv, notuvx.
To update, just git pull from the repo directory.
Tool | Description |
| List all jobs with optional status filter (Draft, Open, Closed, Archived) |
| Get details of a single job by ID |
| Search jobs by title |
Tool | Description |
| List all candidates with cursor pagination |
| Search candidates by email and/or name |
| Get full details of a candidate by ID |
| Create a new candidate |
| Add an HTML-formatted note to a candidate |
| List all notes for a candidate |
| Add a tag to a candidate |
| List all available candidate tags |
Tool | Description |
| List applications with optional jobId, status, and date filters |
| Get full details of an application by ID |
| Create an application linking a candidate to a job |
| Move an application to a different interview stage |
Tool | Description |
| List interview stages for a given interview plan |
| List all interview plans |
| List all interviews with cursor pagination |
| Get details of a single interview by ID |
Tool | Description |
| List all departments |
| List all users (team members) |
| List all candidate sources |
| List all archive reasons |
| List all locations |
Claude Desktop can't find uvx. Make sure you're using the full absolute path from which uvx in your config, not just "uvx".
If you see a PyPI resolution error, make sure the --from argument uses the git+https:// URL, not a package name.
You're running an older version of the server code against a newer MCP SDK. Pull the latest version of this repo.
Your Ashby API key is missing or doesn't have the required permissions. Verify it at https://app.ashbyhq.com/admin/api/keys.
This server communicates with the Ashby REST API:
Base URL: https://api.ashbyhq.com
Auth: Basic Auth (API key as username, empty password)
Method: All endpoints are POST with JSON bodies
Pagination: Cursor-based (moreDataAvailable + nextCursor)
MIT
Move an application to a different interview stage.
| Name | Required | Description | Default |
|---|---|---|---|
| applicationId | Yes | The application ID | |
| interviewStageId | Yes | Target interview stage ID | |
| archiveReasonId | No | Required when moving to an Archived stage |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden for behavioral disclosure. It states the action ('Move') but lacks critical details: whether this requires specific permissions, if it's reversible, what happens to associated data, or any rate limits. For a mutation tool with zero annotation coverage, this is a significant gap in transparency.
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, efficient sentence with zero wasted words. It's front-loaded with the core action and resource, making it immediately scannable and appropriately sized for the tool's complexity.
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 mutation tool with no annotations and no output schema, the description is incomplete. It lacks information on behavioral consequences (e.g., side effects, permissions), response format, or error conditions, which are critical for safe and effective use by an AI 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 description coverage is 100%, so parameters are fully documented in the schema. The description adds no additional semantic context beyond implying movement between stages, which the schema already covers with 'applicationId' and 'interviewStageId'. Baseline 3 is appropriate as the schema does the heavy lifting.
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 ('Move') and target resource ('an application to a different interview stage'), making the purpose immediately understandable. However, it doesn't differentiate from siblings like 'application_create' or 'application_info' beyond the basic verb distinction, missing explicit contrast with similar application-modification 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 no guidance on when to use this tool versus alternatives. With siblings like 'application_info' (for viewing) and 'application_create' (for creation), there's no indication of prerequisites, typical workflow context, or exclusion criteria, leaving usage entirely implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create an application linking a candidate to a job.
| Name | Required | Description | Default |
|---|---|---|---|
| candidateId | Yes | The candidate ID | |
| jobId | Yes | The job ID | |
| sourceId | No | Source ID for attribution | |
| interviewPlanId | No | Interview plan to use (optional) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states 'Create' implies a write/mutation operation, but doesn't cover critical aspects like permissions required, whether the action is idempotent or reversible, error handling, or what happens on success (e.g., returns an application ID). For a creation tool with zero annotation coverage, this is a significant gap.
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, efficient sentence that directly states the tool's purpose without unnecessary words. It's front-loaded and wastes no space, making it easy to parse quickly.
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 complexity of a creation tool with no annotations and no output schema, the description is incomplete. It doesn't explain what the tool returns (e.g., application object or ID), error conditions, or behavioral nuances like whether duplicate applications are allowed. For a mutation tool, this leaves too much undefined for reliable agent use.
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%, with clear descriptions for all parameters (e.g., 'candidateId' as 'The candidate ID'). The description adds no additional meaning beyond the schema, such as explaining relationships between parameters or usage examples. Baseline is 3 since the schema does the heavy lifting, but 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 action ('Create') and the resource ('an application linking a candidate to a job'), making the purpose evident. It distinguishes from siblings like 'application_change_stage' or 'application_info' by focusing on creation rather than modification or retrieval. However, it doesn't explicitly differentiate from 'candidate_create' or 'job_list', which are related but not direct alternatives.
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 doesn't mention prerequisites (e.g., existing candidate and job), exclusions, or compare to siblings like 'application_list' for viewing applications. Without such context, an agent must infer usage from the tool name and schema alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get full details for a single application by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| applicationId | Yes | The application ID (UUID) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states this is a read operation ('Get'), but doesn't clarify permissions, rate limits, error handling, or what 'full details' includes. For a tool with zero annotation coverage, this leaves significant gaps in understanding its behavior.
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, efficient sentence that front-loads the core purpose without unnecessary words. Every part of the sentence earns its place by specifying the action, scope, and required input, making it highly concise and well-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?
Given the tool's simplicity (one parameter, no output schema, no annotations), the description is adequate but incomplete. It covers the basic purpose but lacks behavioral details and usage context, which are important even for simple tools. It meets minimum viability but has clear gaps in guidance and transparency.
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 description coverage is 100%, with the parameter 'applicationId' documented as a UUID. The description adds minimal value beyond the schema, as it only reiterates the need for an ID without providing additional context like format examples or validation rules. Baseline 3 is appropriate when the schema does the heavy lifting.
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 ('Get full details') and resource ('for a single application by ID'), making the purpose immediately understandable. It distinguishes this as a retrieval tool for individual applications rather than bulk operations, though it doesn't explicitly differentiate from similar tools like 'candidate_info' or 'job_info' which follow the same pattern.
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 doesn't mention sibling tools like 'application_list' for multiple applications or 'candidate_info' for related data, nor does it specify prerequisites such as needing an application ID. Usage is implied but not articulated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List applications. Can filter by jobId and/or status. Uses cursor pagination.
| Name | Required | Description | Default |
|---|---|---|---|
| jobId | No | Filter by job ID (UUID) | |
| status | No | Filter by application status | |
| createdAfter | No | Only return applications created after this timestamp (ms since epoch) | |
| limit | No | Max results per page (default/max 100) | |
| cursor | No | Cursor for next page |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively adds context beyond the input schema by specifying 'Uses cursor pagination,' which is crucial for understanding how to handle large result sets. However, it doesn't mention rate limits, authentication needs, or what the return format looks like (e.g., structure of listed applications).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with three short sentences that are front-loaded and waste no words. Each sentence adds value: the first states the core action, the second specifies filtering options, and the third discloses pagination behavior.
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 moderate complexity (5 parameters, no output schema, no annotations), the description is adequate but has gaps. It covers the action, filtering, and pagination, but lacks details on return values, error handling, or performance considerations (e.g., default limits). With no output schema, more guidance on response structure would be helpful.
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 all parameters thoroughly. The description adds minimal value by mentioning filtering by 'jobId and/or status,' which is implied in the schema but not explicitly stated. No additional syntax or format details are provided beyond what the schema offers.
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 ('applications'), making the purpose immediately understandable. It distinguishes from siblings like 'application_info' (single application) and 'candidate_list' (different resource), though it doesn't explicitly contrast with 'application_change_stage' or 'application_create' which have different actions.
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 through 'Can filter by jobId and/or status,' suggesting when filtering might be appropriate, but doesn't explicitly state when to use this tool versus alternatives like 'candidate_list' or 'candidate_search' for related data. No guidance on prerequisites or exclusions is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all archive reasons (needed for application_change_stage to Archived).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions the tool lists reasons and its purpose for archiving, but doesn't add details like whether it's read-only, requires permissions, has rate limits, or what the return format is. It provides basic context but lacks rich behavioral traits beyond the minimal purpose.
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, efficient sentence that directly states the tool's purpose and usage context without any waste. It's front-loaded with the core action and provides necessary additional info concisely.
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 has 0 parameters, no annotations, and no output schema, the description is minimal but adequate for a simple list tool. It explains what the tool does and why it's used, but lacks details on output format or behavioral constraints. For its low complexity, it's complete enough but with clear gaps in transparency.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0 parameters with 100% coverage, so no parameter documentation is needed. The description doesn't add parameter info, which is appropriate. Baseline is 4 for 0 parameters, as the schema fully covers the absence of inputs.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose as 'List all archive reasons' with a specific verb and resource. It distinguishes from siblings by mentioning its relationship to 'application_change_stage to Archived', though it doesn't explicitly differentiate from other list tools like 'department_list' or 'source_list'. This is clear but lacks explicit sibling differentiation.
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 clear context for usage by stating it's 'needed for application_change_stage to Archived', which implies when to use this tool. However, it doesn't explicitly state when not to use it or name alternatives, such as whether other tools might list reasons for different purposes. This offers good guidance but not full alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add a tag to a candidate. Use candidate_tag_list to find tag IDs.
| Name | Required | Description | Default |
|---|---|---|---|
| candidateId | Yes | The candidate ID | |
| tagId | Yes | The tag ID to add |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states this is an 'Add' operation (implying mutation) but doesn't disclose permissions needed, whether the operation is idempotent, what happens if the tag already exists, rate limits, or error conditions. The description adds minimal behavioral context beyond the basic action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with just two sentences that both serve clear purposes: the first states the core functionality, the second provides implementation guidance. There's zero wasted language and it's appropriately front-loaded with the primary 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 mutation tool with no annotations and no output schema, the description is insufficiently complete. It doesn't explain what the tool returns, error conditions, side effects, or important behavioral characteristics. While concise, it leaves too many contextual gaps for a tool that modifies data.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the schema already documents both parameters adequately. The description adds marginal value by implying that tag IDs should be obtained from 'candidate_tag_list', but doesn't provide additional semantic context about parameter formats, validation, or relationships beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Add a tag') and target resource ('to a candidate'), providing a specific verb+resource combination. However, it doesn't explicitly differentiate from sibling tools like 'candidate_create_note' or 'candidate_tag_list' beyond mentioning the latter as a prerequisite.
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 implied usage guidance by referencing 'candidate_tag_list' as a way to find tag IDs, suggesting this tool should be used after tag discovery. However, it doesn't explicitly state when to use this tool versus alternatives or mention any exclusions or prerequisites beyond the tag ID requirement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new candidate in Ashby.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Full name of the candidate | |
| No | Primary email address | ||
| phoneNumber | No | Phone number | |
| linkedInUrl | No | LinkedIn profile URL | |
| githubUrl | No | GitHub profile URL | |
| sourceId | No | Source ID for attribution |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden for behavioral disclosure. While 'Create' implies a write/mutation operation, the description doesn't address permission requirements, whether this operation is idempotent, what happens on duplicate entries, error conditions, or what the response contains. For a creation tool with zero annotation coverage, this represents significant gaps in behavioral transparency.
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, efficient sentence that states the core purpose without unnecessary words. It's appropriately front-loaded with the essential information and contains zero wasted verbiage. This represents optimal conciseness for a basic tool description.
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 creation tool with no annotations and no output schema, the description is insufficiently complete. It doesn't address what happens after creation (return values, success indicators), error handling, or system behavior. Given the complexity of creating a candidate record and the lack of structured metadata, the description should provide more operational context to be truly helpful.
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 all 6 parameters thoroughly. The description adds no additional parameter information beyond what's in the schema. This meets the baseline expectation when schema coverage is complete, but doesn't provide any extra context about parameter relationships, constraints, or usage patterns.
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 ('Create') and resource ('new candidate in Ashby'), making the purpose immediately understandable. However, it doesn't differentiate itself from sibling tools like 'application_create' or 'candidate_add_tag', which would require more specific context about what distinguishes candidate creation from other candidate-related operations.
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. With sibling tools like 'candidate_add_tag', 'candidate_create_note', and 'application_create', there's no indication of when candidate creation is appropriate versus adding notes or creating applications. No prerequisites, exclusions, or contextual recommendations are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add a note to a candidate. Supports HTML formatting.
| Name | Required | Description | Default |
|---|---|---|---|
| candidateId | Yes | The candidate ID | |
| note | Yes | Note content (HTML supported) | |
| sendNotifications | No | Notify subscribed users (default false) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It states 'Add a note' (implying a write/mutation operation) and mentions HTML support, but lacks critical details: whether this requires specific permissions, if notes are editable/deletable, rate limits, or what happens on success/failure. For a mutation tool with zero annotation coverage, this is insufficient.
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 (one sentence) and front-loaded with the core purpose. Every word earns its place: 'Add a note to a candidate' establishes the action, and 'Supports HTML formatting' adds useful technical detail without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given this is a mutation tool (adding notes) with no annotations and no output schema, the description is incomplete. It doesn't explain what the tool returns (e.g., success confirmation, note ID, error details), behavioral constraints, or integration with sibling tools. For a write operation in a candidate management context, more context is needed for effective agent use.
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 all three parameters (candidateId, note, sendNotifications) with clear descriptions. The description adds minimal value beyond the schema by noting 'HTML formatting' (implied in the note parameter's schema description) and doesn't provide additional context like format examples or default behavior for sendNotifications. Baseline 3 is appropriate when the schema does the heavy lifting.
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 ('Add a note') and target resource ('to a candidate'), making the purpose immediately understandable. It also specifies 'Supports HTML formatting' as a key feature. However, it doesn't differentiate from sibling tools like 'candidate_list_notes' or 'candidate_info', which is why it doesn't reach a 5.
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 doesn't mention prerequisites (e.g., needing an existing candidate), exclusions, or comparisons with related tools like 'candidate_list_notes' (for viewing notes) or 'candidate_add_tag' (for other candidate modifications).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get full details of a single candidate by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The candidate ID (UUID) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states it 'Get full details' but doesn't specify what 'full details' includes, whether it's a read-only operation, requires authentication, has rate limits, or error behaviors. This leaves significant gaps for a tool that retrieves data.
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, efficient sentence that directly states the tool's function without unnecessary words. It's appropriately sized and front-loaded, making it easy to parse quickly.
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 complexity of retrieving candidate details, no annotations, and no output schema, the description is incomplete. It doesn't explain what 'full details' entails, potential response formats, or error handling, which are crucial for an AI agent to use this tool effectively.
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 description coverage is 100%, with the parameter 'id' documented as 'The candidate ID (UUID)'. The description adds no additional parameter semantics beyond this, such as format examples or constraints, so it meets the baseline for high schema coverage without extra value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Get') and resource ('full details of a single candidate'), making the purpose understandable. However, it doesn't distinguish this tool from sibling tools like 'candidate_list' or 'candidate_search' that also retrieve candidate information, which prevents a perfect score.
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 doesn't mention prerequisites like needing a candidate ID or compare it to sibling tools such as 'candidate_list' for multiple candidates or 'candidate_search' for filtering, leaving usage context unclear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all candidates with cursor pagination.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max results per page (default/max 100) | |
| cursor | No | Cursor for next page |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It mentions 'cursor pagination' which adds some behavioral context about handling large result sets, but doesn't disclose other important traits like rate limits, authentication requirements, error conditions, or what the response format looks like (especially critical without an output 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?
The description is extremely concise (6 words) and front-loaded with the core purpose. Every word earns its place, with no wasted verbiage or unnecessary elaboration.
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 annotations and no output schema, the description is incomplete. While it states the basic purpose and mentions pagination, it doesn't explain what data is returned, how errors are handled, or other contextual details needed for effective tool use. For a list operation with 2 parameters, this leaves significant gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already fully documents both parameters (limit and cursor). The description adds no additional parameter semantics beyond what's in the schema, maintaining the baseline score of 3 for when the schema does the heavy lifting.
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 ('all candidates'), making the purpose immediately understandable. However, it doesn't differentiate this tool from sibling tools like 'candidate_search' or 'candidate_info', which would require explicit comparison to achieve a score of 5.
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 like 'candidate_search' or 'candidate_info'. It mentions cursor pagination, which hints at usage for large datasets, but doesn't explicitly state when to choose this over other candidate-related tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all notes for a candidate.
| Name | Required | Description | Default |
|---|---|---|---|
| candidateId | Yes | The candidate ID | |
| limit | No | Max results per page | |
| cursor | No | Cursor for next page |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden for behavioral disclosure. It states it's a list operation, implying read-only behavior, but lacks details on permissions, rate limits, pagination (beyond schema hints), error handling, or what 'notes' entail (e.g., format, content). This is inadequate for a tool with parameters and no output 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?
The description is a single, efficient sentence with zero wasted words. It's front-loaded with the core purpose ('List all notes for a candidate'), making it easy to parse quickly. Every word earns its place, achieving 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?
Given no annotations, no output schema, and 3 parameters (with 100% schema coverage), the description is incomplete. It doesn't explain what 'notes' are, how they're returned, or behavioral aspects like pagination or errors. For a list tool in a candidate management context, more context is needed to guide effective use.
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 fully documents parameters (candidateId, limit, cursor). The description adds no additional meaning beyond implying 'candidateId' is required for listing notes, which is already clear from the schema. Baseline 3 is appropriate as the schema does the heavy lifting.
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 all notes') and resource ('for a candidate'), making the purpose immediately understandable. However, it doesn't differentiate from potential sibling tools like 'candidate_info' or 'candidate_create_note' that might also involve candidate notes, leaving room for improvement in specificity.
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. With sibling tools like 'candidate_info' (which might include notes) and 'candidate_create_note' (for adding notes), there's no indication of context, prerequisites, or exclusions, leaving the agent to guess based on tool names alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search candidates by email and/or name. Not paginated.
| Name | Required | Description | Default |
|---|---|---|---|
| No | Email to search for | ||
| name | No | Name to search for |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It adds value by stating 'Not paginated,' which is a key behavioral trait not inferable from the schema. However, it lacks details on permissions, rate limits, error handling, or response format, leaving gaps for a search tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise—two short sentences with zero waste. It front-loads the core purpose and efficiently adds a critical behavioral note ('Not paginated'), making it easy to parse and understand quickly.
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 moderate complexity (search with two parameters) and no annotations or output schema, the description is minimally adequate. It covers the purpose and a key behavioral trait (no pagination), but lacks details on response structure, error cases, or integration with sibling tools, leaving room for improvement.
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 ('email' and 'name') adequately. The description adds minimal semantic context by mentioning search 'by email and/or name,' but doesn't elaborate on search logic (e.g., partial matches, case sensitivity) beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Search') and resource ('candidates'), specifying search criteria ('by email and/or name'). It distinguishes from sibling tools like 'candidate_list' by focusing on search functionality, though it doesn't explicitly contrast with 'candidate_info' or 'job_search'.
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 searching candidates by email or name, but provides no explicit guidance on when to use this versus alternatives like 'candidate_list' (which might list all candidates) or 'candidate_info' (which might retrieve details for a specific candidate). The lack of pagination is noted, which hints at usage for small result sets.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all available candidate tags.
| Name | Required | Description | Default |
|---|---|---|---|
| includeArchived | No | Include archived tags (default false) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but only states the action without behavioral details. It doesn't disclose if this is a read-only operation, potential rate limits, authentication needs, or what the output looks like (e.g., list format, pagination). This is inadequate for a tool with zero annotation coverage.
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, efficient sentence with no wasted words. It's front-loaded with the core action and resource, making it easy to parse quickly.
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 low complexity (one optional parameter, no output schema, no annotations), the description is minimally adequate but lacks completeness. It doesn't explain the return values or usage context, which could help an agent understand how to integrate this with sibling tools like 'candidate_add_tag'.
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 description adds no parameter semantics beyond the input schema, which has 100% coverage for its single parameter. The baseline is 3 since the schema fully documents the parameter, but the description doesn't provide additional context like why archived tags might be included or excluded.
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 'all available candidate tags', making the purpose specific and understandable. However, it doesn't differentiate from sibling tools like 'candidate_add_tag' or 'candidate_list', which would require mentioning this is for metadata/tag enumeration rather than candidate operations.
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 doesn't mention prerequisites, context (e.g., for tagging candidates), or exclusions, leaving the agent to infer usage 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.
List all departments.
| Name | Required | Description | Default |
|---|---|---|---|
| includeArchived | No | Include archived departments |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but offers minimal behavioral insight. It doesn't disclose whether this is a read-only operation, if it requires authentication, how results are returned (e.g., pagination), or any rate limits. 'List all departments' implies a safe read, but lacks confirmation or details.
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—just three words—with zero wasted language. It's front-loaded and efficiently communicates the core action, though this brevity contributes to gaps in other dimensions.
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 no annotations, no output schema, and minimal description, this is incomplete. The agent lacks context on return format, error handling, or operational constraints. While the tool is simple (one optional parameter), the description doesn't provide enough information for reliable use beyond basic inference.
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%, with the single parameter 'includeArchived' fully documented in the schema. The description adds no parameter-specific information beyond implying a list operation, so it meets the baseline for high schema coverage without compensating value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'List all departments' clearly states the verb ('List') and resource ('departments'), making the basic purpose understandable. However, it lacks specificity about scope or format, and doesn't differentiate from sibling tools like 'location_list' or 'user_list' that follow similar patterns.
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. The description doesn't mention prerequisites, context, or exclusions, nor does it reference sibling tools like 'archive_reason_list' or 'candidate_tag_list' that might serve related purposes.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get details of a single interview by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The interview ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states it 'gets details' but doesn't specify what details are returned, whether this is a read-only operation, if authentication is required, or any rate limits. For a tool with zero annotation coverage, this leaves significant gaps in understanding its behavior.
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, efficient sentence that communicates the core purpose without any wasted words. It's appropriately sized for a simple lookup tool and front-loads the essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (1 parameter, no output schema, no annotations), the description is minimally adequate. However, it lacks context about what 'details' are returned, which is important since there's no output schema. For a basic read operation, it's functional but could be more informative about the response structure.
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 description coverage is 100%, with the single parameter 'id' clearly documented in the schema. The description adds no additional semantic context about the parameter beyond what's in the schema (e.g., format examples, valid ranges, or relationship to other tools), so it meets the baseline for high schema coverage.
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 ('Get details') and resource ('a single interview by ID'), making the purpose immediately understandable. However, it doesn't distinguish this tool from sibling tools like 'interview_list' or 'candidate_info' that might also provide interview-related information, preventing a perfect score.
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 like 'interview_list' or 'candidate_info' (which might include interview data). There's no mention of prerequisites, context for when this is appropriate, or what distinguishes it from similar tools in the sibling list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all interviews with cursor pagination.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max results per page | |
| cursor | No | Cursor for next page |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. While it mentions 'cursor pagination' which is valuable behavioral information, it doesn't address other critical aspects: whether this is a read-only operation, what permissions might be required, what format the results come in, or any rate limits. For a list operation with zero annotation coverage, this leaves significant behavioral questions unanswered.
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 - a single sentence that communicates the core functionality. Every word earns its place: 'List' (action), 'all interviews' (scope), 'with cursor pagination' (key behavioral characteristic). There's no wasted language or redundancy, making it highly efficient for an AI agent to parse.
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 that this is a list operation with 2 well-documented parameters (100% schema coverage) but no annotations and no output schema, the description provides the minimum viable information. It states what the tool does and mentions pagination behavior, but doesn't address the output format, error conditions, or how this tool relates to other listing tools in the system. For a tool with no output schema, more information about return values would be helpful.
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 description mentions 'cursor pagination' which provides context for the two parameters, but the input schema already has 100% description coverage with clear parameter documentation. The description doesn't add meaningful semantic information beyond what's already in the schema - it doesn't explain how the cursor is obtained, what typical limit values might be appropriate, or provide usage examples. With complete schema coverage, the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('List') and resource ('all interviews'), making the purpose immediately understandable. However, it doesn't differentiate this tool from sibling tools like 'candidate_list', 'job_list', or 'application_list' - all of which are also list operations. The description is specific about what it lists but not how it differs from other list tools in the system.
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. With multiple list tools available (candidate_list, job_list, application_list, etc.), there's no indication of what distinguishes interview_list from these other listing operations. The description doesn't mention prerequisites, use cases, or when this tool would be preferred over other listing mechanisms.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all interview plans.
| Name | Required | Description | Default |
|---|---|---|---|
| includeArchived | No | Include archived plans |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden for behavioral disclosure. While 'List' implies a read operation, it doesn't mention any behavioral traits like pagination, sorting, default ordering, rate limits, authentication requirements, or what happens when no plans exist. For a list tool with zero annotation coverage, this is insufficient.
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, efficient sentence with zero wasted words. It's perfectly front-loaded with the core action and resource, making it immediately scannable and understandable.
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 annotations and no output schema, the description is incomplete for a list operation. It doesn't explain what an 'interview plan' is, what fields are returned, whether results are paginated, or how this differs from similar list tools. The agent would need to guess about these important contextual details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents the single parameter 'includeArchived'. The description doesn't add any parameter semantics beyond what's in the schema, but since the schema coverage is complete, 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 clearly states the verb ('List') and resource ('all interview plans'), making the purpose immediately understandable. However, it doesn't differentiate this tool from other list tools like 'application_list', 'candidate_list', or 'interview_list', which would require mentioning what specifically distinguishes interview plans from those other 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?
The description provides no guidance on when to use this tool versus alternatives. With siblings like 'interview_list' and 'interview_stage_list', there's no indication of how interview plans relate to or differ from interviews or interview stages, leaving the agent to guess about appropriate usage contexts.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all interview stages for a given interview plan.
| Name | Required | Description | Default |
|---|---|---|---|
| interviewPlanId | Yes | The interview plan ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It states it's a list operation, implying read-only behavior, but doesn't disclose any behavioral traits such as pagination, sorting, error conditions, or authentication needs. The description is minimal and lacks context beyond the basic action.
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, efficient sentence with zero waste. It front-loads the core action ('List all interview stages') and specifies the context ('for a given interview plan'), making it easy to parse quickly. 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?
Given no annotations and no output schema, the description is incomplete for a tool that likely returns a list of stages. It doesn't explain what data is returned, format, or any limitations. For a read operation with minimal structured support, more context on behavior and output is needed.
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 input schema fully documents the single parameter 'interviewPlanId'. The description adds no additional meaning beyond implying the parameter is required for context. Baseline score of 3 is appropriate as the schema handles parameter documentation adequately.
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 ('interview stages') with scope ('for a given interview plan'), making the purpose unambiguous. It doesn't explicitly differentiate from sibling tools like 'interview_plan_list' or 'interview_list', but the specificity of 'stages' within a plan provides implicit distinction.
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. The description doesn't mention prerequisites, exclusions, or related tools like 'interview_plan_list' (which might list plans before selecting one for stages). Usage is implied by the parameter requirement but not explicitly stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get details of a single job by its ID.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The job ID (UUID) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool retrieves details but doesn't specify what those details include (e.g., job title, status, department), whether it requires authentication, potential error cases (e.g., invalid ID), or rate limits. For a read operation with zero annotation coverage, this leaves significant gaps in understanding the tool's behavior beyond the basic action.
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, efficient sentence that directly states the tool's purpose without any unnecessary words. It is front-loaded with the core action ('Get details'), making it easy to scan and understand quickly. Every part of the sentence contributes essential information, earning 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?
Given the tool's low complexity (single parameter, read-only operation) and high schema coverage, the description is adequate as a basic lookup tool. However, with no annotations and no output schema, it fails to disclose what details are returned or any behavioral traits like error handling. This leaves the agent with incomplete context for reliable use, though the simplicity mitigates some risk.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, with the 'id' parameter documented as 'The job ID (UUID)'. The description adds minimal value beyond this, only reiterating that it retrieves details 'by its ID'. Since the schema already fully describes the parameter, the baseline score of 3 is appropriate, as the description doesn't provide additional semantic context like format examples or usage notes.
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 ('Get details') and resource ('of a single job'), making the purpose immediately understandable. It distinguishes itself from sibling tools like 'job_list' and 'job_search' by specifying retrieval of a single job by ID rather than listing or searching multiple jobs. However, it doesn't explicitly contrast with 'application_info' or 'interview_info', which might retrieve related but 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?
The description implies usage when you need details for a specific job ID, which is straightforward for this simple lookup tool. It doesn't provide explicit guidance on when to use alternatives like 'job_list' for multiple jobs or 'job_search' for filtered searches, nor does it mention prerequisites like needing a valid job ID. The context is clear but lacks explicit comparison or exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all jobs (open, closed, archived). Supports cursor pagination and status filtering.
| Name | Required | Description | Default |
|---|---|---|---|
| status | No | Filter by status(es). If omitted, returns all non-Draft jobs. | |
| limit | No | Max results per page (default/max 100) | |
| cursor | No | Cursor for next page of results |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It discloses pagination behavior ('cursor pagination') and filtering capability, but doesn't mention rate limits, authentication requirements, error conditions, or what the response format looks like. It adequately describes core functionality but lacks operational details.
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 zero waste. First sentence states purpose and scope, second sentence adds key behavioral capabilities. Every word earns its place and information is front-loaded appropriately.
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 read-only listing tool with 3 parameters and no output schema, the description covers basic purpose and key behaviors (pagination, filtering). However, without annotations or output schema, it should ideally mention response format, error handling, or authentication needs to be more complete for agent usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already fully documents all three parameters. The description mentions 'status filtering' and 'cursor pagination' which align with parameters, but adds no additional semantic context beyond what the schema provides. Baseline 3 is appropriate when schema does the heavy lifting.
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 ('jobs') with scope ('all jobs (open, closed, archived)'). It distinguishes from sibling 'job_search' by focusing on listing rather than searching, but doesn't explicitly differentiate from 'job_info' which retrieves a single job.
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 listing jobs with pagination and filtering, but doesn't explicitly state when to use this tool versus alternatives like 'job_search' or 'job_info'. No guidance on prerequisites or exclusions is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for jobs by title. Not paginated; returns all matches.
| Name | Required | Description | Default |
|---|---|---|---|
| title | Yes | The job title to search for |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses key behavioral traits: the search is based on title, it's not paginated, and it returns all matches. This covers scope and output behavior but misses details like rate limits, authentication needs, or error handling. The description doesn't contradict annotations (none exist), but it's moderately informative.
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 and front-loaded: two short sentences with zero waste. The first sentence states the purpose, and the second adds critical behavioral context. Every word earns its place, making it easy for an agent to parse quickly.
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 low complexity (one parameter, no output schema, no annotations), the description is adequate but has gaps. It explains what the tool does and its non-paginated behavior, but lacks details on output format, error cases, or integration with siblings. For a simple search tool, it's minimally viable but not fully comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, with the 'title' parameter fully documented. The description adds no additional parameter semantics beyond implying the search uses this title field. Since schema coverage is high, the baseline is 3, and the description doesn't enhance or compensate beyond that.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Search for jobs by title.' It specifies the verb ('search'), resource ('jobs'), and search criteria ('by title'). However, it doesn't explicitly differentiate from sibling tools like 'job_list' or 'candidate_search,' which prevents a perfect score.
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 minimal guidance: it mentions 'Not paginated; returns all matches,' which hints at usage for retrieving complete result sets. However, it lacks explicit when-to-use advice, such as comparing to 'job_list' (which might list all jobs without filtering) or 'candidate_search' (which searches candidates, not jobs). No alternatives or exclusions are named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all locations.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. 'List all locations' implies a read operation but provides no information about permissions required, rate limits, pagination behavior, sorting, filtering capabilities, or what format the locations will be returned in. The description is minimal and lacks essential operational 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 maximally concise at just three words - 'List all locations.' It's front-loaded with the core action and resource, with zero wasted words or unnecessary elaboration. Every word earns its place in communicating the essential 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 the lack of annotations and output schema, the description is incomplete for a list operation. While concise, it doesn't address critical context like what fields locations include, whether results are paginated, how many locations might be returned, or any authentication requirements. For a tool that presumably returns data, more context about the return format would be helpful.
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 tool has 0 parameters with 100% schema description coverage, so the schema fully documents the parameter situation. The description doesn't need to compensate for any parameter documentation gaps. The baseline for 0 parameters with full schema coverage is 4, as there are no parameters whose semantics need explanation 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 'List all locations' clearly states the verb ('List') and resource ('locations'), making the tool's purpose immediately understandable. However, it doesn't differentiate from sibling list tools like 'department_list', 'user_list', or 'source_list' - it only specifies what resource it lists, not how it differs from other list operations.
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. With multiple list tools available (department_list, user_list, source_list, etc.), there's no indication of when location_list is appropriate versus other list operations, nor any mention of prerequisites or constraints for using this specific tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all candidate sources.
| Name | Required | Description | Default |
|---|---|---|---|
| includeArchived | No | Include archived sources |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the action ('List') but does not reveal any behavioral traits like whether it's read-only, requires authentication, has rate limits, or what the output format might be. For a tool with zero annotation coverage, this is a significant gap in transparency.
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 wasted words. It is front-loaded with the core action and resource, making it highly efficient. Every part of the sentence contributes directly to understanding 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 the lack of annotations and output schema, the description is incomplete for a list tool. It does not explain what 'candidate sources' are, the return format, or any behavioral aspects like pagination or error handling. For a tool with no structured support, the description should provide more context to be fully helpful.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 1 parameter with 100% description coverage, so the schema fully documents the parameter. The description does not add any parameter-specific information beyond what the schema provides. With 0 parameters needing extra semantics, a baseline of 4 is appropriate as the schema handles the heavy lifting effectively.
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 states the verb ('List') and resource ('candidate sources'), which provides a basic understanding of the tool's function. However, it lacks specificity about what 'candidate sources' are (e.g., recruitment sources, data origins) and does not differentiate from siblings like 'candidate_list' or 'job_list', making it somewhat vague. It avoids tautology by not merely restating the name.
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. There is no mention of context, prerequisites, or exclusions, such as how it differs from 'candidate_list' or when to include archived sources. This leaves the agent without direction on appropriate usage scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all users (team members) in the organization.
| Name | Required | Description | Default |
|---|---|---|---|
| includeDeactivated | No | Include deactivated users |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden for behavioral disclosure. It states this is a list operation but doesn't describe what 'list' entails—whether it returns all users at once, uses pagination, requires authentication, has rate limits, or what format the output takes. For a tool with zero annotation coverage, this leaves significant behavioral gaps.
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, efficient sentence with zero wasted words. It's appropriately sized for a simple list tool and front-loads the core purpose immediately.
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 low complexity (one optional parameter, no output schema), the description is minimally adequate but incomplete. It lacks behavioral context that would be crucial for an agent to use it effectively, especially since no annotations cover safety or operational traits. However, the simple nature of a list operation makes some gaps more tolerable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already fully documents the single parameter 'includeDeactivated'. The description doesn't add any parameter-specific information beyond what's in the schema, such as default behavior or implications of including deactivated users. This meets the baseline for high schema coverage.
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 all users') and resource ('team members in the organization'), providing a specific verb+resource combination. However, it doesn't explicitly differentiate from sibling tools like 'candidate_list' or 'department_list', which are conceptually similar list operations for different resources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites, context for usage, or comparisons to sibling tools like 'candidate_list' that might serve similar organizational listing purposes. The agent must infer usage from the tool 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. Dates show when Glama detected each change.
v0.1.0application_change_stageapplication_createapplication_infoapplication_listarchive_reason_listcandidate_add_tagcandidate_createcandidate_create_notecandidate_infocandidate_listcandidate_list_notescandidate_searchcandidate_tag_listdepartment_listinterview_infointerview_listinterview_plan_listinterview_stage_listjob_infojob_listjob_searchlocation_listsource_listuser_listEvery tool has a clearly distinct purpose with no ambiguity. For example, application_list and application_info are clearly separate from candidate_list and candidate_info, and specialized tools like archive_reason_list or candidate_tag_list serve unique functions. The descriptions reinforce distinct boundaries between tools.
All tools follow a consistent verb_noun pattern with underscores, such as application_change_stage, candidate_create, and job_list. There are no deviations in naming conventions, making the set predictable and easy to parse for an agent.
With 24 tools, the count is slightly high but reasonable for an ATS domain covering applications, candidates, jobs, interviews, and metadata. Each tool appears to earn its place by addressing specific aspects of the hiring workflow, though it borders on being heavy.
The tool surface provides comprehensive CRUD and lifecycle coverage for the Ashby ATS domain. It includes creation (e.g., candidate_create, application_create), retrieval (e.g., info and list tools), updates (e.g., application_change_stage, candidate_add_tag), and supporting metadata (e.g., department_list, source_list), with no obvious gaps that would cause agent failures.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
AI resume triage for recruiters. Query your candidate pool from Claude or ChatGPT.
Ashby MCP Pack — wraps the Ashby ATS API
Manage job applications — jobs, companies, boards, notes, and profile — from your AI client.
Your professional network in Claude — search contacts, log notes, and send warm intros.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/PlenishAI/mcp-ashby'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
