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., "@Crelate MCP Server list my recent job openings"
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.
Model Context Protocol (MCP) server for the Crelate ATS/CRM API. Enables Claude Code and other MCP clients to interact with Crelate recruiting and staffing workflows.
GitHub: https://github.com/mrchevyceleb/crelate-mcp
# Clone the repository
git clone https://github.com/mrchevyceleb/crelate-mcp.git
cd crelate-mcp
# Install dependencies
uv venv
uv pip install mcp httpx python-dotenv
# Configure your API key
cp .env.example .env
# Edit .env and add your CRELATE_API_KEY
# Add to Claude Code (see Configuration section below)Related MCP server: codebeamer-mcp
Contacts: List, get, create, update contacts
Candidates: List, get, create candidates
Jobs: List, get, create job positions
Companies: List, get, create companies
Notes: Create notes and attach to records
Tasks: Create tasks and attach to records
Activity Reports: Track interactions, touchpoints, and engagement history
Pipeline Reports: Analyze candidate flow through job pipelines
Placement Reports: Track successful hires and metrics
Source Tracking: Identify where candidates and contacts originated
User Activity: Monitor team productivity and activity
Financial Reports: Track invoicing and payment data
Aggregate Metrics: High-level counts and organization stats
Workflow Analysis: Analyze categorization and pipeline stages
Python 3.10+
uv (Python package manager)
Crelate API key
Log into your Crelate account at https://app.crelate.com
Navigate to Settings → My Settings & Preferences
Find your API key in the API section
Copy the key for configuration
Note: Your organization administrator controls API access via Settings → Advanced Settings → User Roles.
cd ~/mcp-projects/crelate-mcpcp .env.example .envEdit .env and add your Crelate API key:
CRELATE_API_KEY=your_actual_api_key_hereuv pip install -e .Edit your MCP configuration file at C:\Users\mtjoh\.claude.json:
{
"projects": {
"C:\\Users\\mtjoh": {
"mcpServers": {
"crelate": {
"command": "uv",
"args": ["run", "C:\\Users\\mtjoh\\mcp-projects\\crelate-mcp\\server.py"],
"env": {
"CRELATE_API_KEY": "your_api_key_here"
}
}
}
}
}
}Restart Claude Code after adding the configuration.
list_contacts(limit, offset, search) - List contacts with pagination and search
get_contact(contact_id) - Get detailed contact information
create_contact(first_name, last_name, email, phone, company_name, title) - Create new contact
update_contact(contact_id, ...) - Update existing contact
list_candidates(limit, offset, search) - List candidates with pagination and search
get_candidate(candidate_id) - Get detailed candidate information
create_candidate(first_name, last_name, email, phone, current_title, current_company) - Create new candidate
list_jobs(limit, offset, status) - List jobs with optional status filter
get_job(job_id) - Get detailed job information
create_job(name, company_name, location, description) - Create new job posting
list_companies(limit, offset, search) - List companies with pagination and search
get_company(company_id) - Get detailed company information
create_company(name, website, industry, location) - Create new company
create_note(body, contact_id, candidate_id, company_id, job_id) - Create note and attach to record
create_task(body, due_date, contact_id, candidate_id, company_id, job_id) - Create task and attach to record
Track interactions, touchpoints, and engagement history:
get_activities(limit, offset, activity_type) - List all activities with optional type filter
get_activity_count(activity_type) - Get total count of activities by type
get_contact_history(contact_id, limit, offset) - Get complete activity history for a contact
get_job_history(job_id, limit, offset) - Get complete activity history for a job
Analyze candidate flow through job pipelines:
get_applications(job_id, limit, offset) - List all applications for a specific job
get_application_count(job_id, status) - Count applications by job and optional status
get_job_contacts(job_id, limit, offset) - List all contacts associated with a job
get_job_contact_history(job_id, contact_id, limit, offset) - Get interaction history between job and contact
Track successful hires and placement metrics:
get_placements(limit, offset, start_date, end_date) - List placements with date range filtering
get_placement_info(placement_id) - Get detailed information about a specific placement
Identify where candidates and contacts originated:
get_contact_sources(limit, offset) - List all contact sources with usage stats
get_company_sources(limit, offset) - List all company sources with usage stats
Monitor team member activity and productivity:
get_users(limit, offset) - List all users in the organization
get_user_count() - Get total count of active users
get_user_info(user_id) - Get detailed information about a specific user
get_current_user() - Get information about the authenticated user
Track invoicing and payment data:
get_invoices(limit, offset, status) - List invoices with optional status filter
get_invoice_count(status) - Count invoices by status
get_invoice_info(invoice_id) - Get detailed information about a specific invoice
get_payments(invoice_id, limit, offset) - List payments for a specific invoice
High-level counts and organization information:
get_contact_count(search) - Get total count of contacts with optional search filter
get_job_count(status) - Get total count of jobs with optional status filter
get_company_count(search) - Get total count of companies with optional search filter
get_organization_info() - Get information about the Crelate organization/account
Analyze categorization and pipeline stages:
get_tags(limit, offset, entity_type) - List tags with optional entity type filter
get_tag_categories(limit, offset) - List all tag categories
get_workflow_statuses(entity_type, limit, offset) - List workflow statuses by entity type
Once configured, you can interact with Crelate using natural language:
"List the most recent 10 candidates"
"Get details for contact ID 12345"
"Create a new candidate named John Smith with email john@example.com"
"Add a note to candidate 67890 saying 'Great interview, moving to next round'"
"Create a task for job 54321 due tomorrow at 3pm"from server import list_contacts, get_contact, create_candidate
# List contacts
contacts = await list_contacts(limit=10, search="Smith")
# Get specific contact
contact = await get_contact("12345")
# Create candidate
new_candidate = await create_candidate(
first_name="Jane",
last_name="Doe",
email="jane@example.com",
current_title="Software Engineer"
)This MCP server wraps the Crelate API v3.
Official Documentation:
Swagger UI: https://app.crelate.com/api/pub/v1/docs/g/index
API Docs: https://app.crelate.com/api3/docs
Developer Guide: https://help.crelate.com/en/articles/4120536-crelate-api-developer-guide
Base URL: https://app.crelate.com/api3
Authentication: API key passed as query parameter
All dates must be in ISO 8601 format in UTC timezone:
2026-01-20T15:00:00ZCompany: name
Job: name
Note: body
Task: body
Contact: firstName, lastName
Candidate: firstName, lastName
When creating records with relationships (e.g., contact with company), Crelate supports:
Providing an existing record ID to link
Providing name fields only to auto-create new records
If you get authentication errors:
Verify your API key in Crelate settings
Check that the key is correctly set in .env or MCP config
Ensure your user role has API access enabled
# Test the server directly
cd ~/mcp-projects/crelate-mcp
uv run server.pyVerify configuration in ~/.claude.json
Check that the server isn't in disabledMcpServers array
Restart Claude Code
Use /mcp command to check server status
crelate-mcp/
├── server.py # Main MCP server implementation
├── pyproject.toml # Python dependencies
├── .env.example # Environment template
└── README.md # This fileTo add new Crelate API endpoints:
Add a new tool function with @mcp.tool() decorator
Use make_crelate_request() helper for API calls
Follow existing patterns for parameter handling
Update this README with the new tool
# Test individual tools
import asyncio
from server import list_contacts
async def test():
result = await list_contacts(limit=5)
print(result)
asyncio.run(test())Crelate API Support: https://help.crelate.com/en/collections/2434134-api-documentation
MCP Documentation: https://modelcontextprotocol.io
MIT License - See LICENSE file for details
Version: 0.1.0 Author: Matt Johnston Project: YourProfitPartners / Work With Your Handz Created: January 14, 2026
Create a new candidate in Crelate.
Args: first_name: Candidate's first name (required) last_name: Candidate's last name (required) email: Candidate's email address phone: Candidate's phone number current_title: Candidate's current job title current_company: Candidate's current company
Returns: JSON string containing the created candidate details including ID
| Name | Required | Description | Default |
|---|---|---|---|
| No | |||
| phone | No | ||
| last_name | Yes | ||
| first_name | Yes | ||
| current_title | No | ||
| current_company | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must cover behavioral traits. It indicates creation and return of candidate details, but does not disclose side effects, permissions, uniqueness constraints, or error scenarios.
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 concise with a clear structure: main sentence, bulleted Args, and Returns. No extraneous 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?
Covers all 6 parameters, required fields, and return type. Lacks details on error handling or idempotency, but sufficient for basic operation.
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 0% description coverage, so the parameter list in the description adds meaning beyond the schema (e.g., 'first_name: Candidate's first name (required)'). This compensates for missing schema annotations.
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 'Create a new candidate in Crelate' with a specific verb and resource. It effectively differentiates from sibling tools like create_company and create_contact.
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 (e.g., when to update instead of create). No prerequisites or context for invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new company in Crelate.
Args: name: Company name (required) website: Company website URL industry: Company industry location: Company location
Returns: JSON string containing the created company details including ID
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| website | No | ||
| industry | No | ||
| location | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavior. It only mentions creation and return format, omitting side effects, error handling, idempotency, or permission requirements.
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 concise and well-structured with a one-line summary followed by Args and Returns sections. No superfluous text.
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?
Description is adequate for a simple creation tool, providing parameter lists and return value. However, it lacks explanation of error responses or behavior on duplicates, which impacts completeness.
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 lists parameters with brief text (e.g., 'Company name (required)', 'Company website URL'), adding some context beyond the schema. However, with 0% schema description coverage, more detail would be needed for a higher score.
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 'Create a new company in Crelate', specifying the action and resource. It distinguishes from sibling tools like create_candidate, create_contact, etc.
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. The description does not mention context, prerequisites, or trade-offs with other create tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new contact in Crelate.
Args: first_name: Contact's first name (required) last_name: Contact's last name (required) email: Contact's email address phone: Contact's phone number company_name: Associated company name title: Contact's job title
Returns: JSON string containing the created contact details including ID
| Name | Required | Description | Default |
|---|---|---|---|
| No | |||
| phone | No | ||
| title | No | ||
| last_name | Yes | ||
| first_name | Yes | ||
| company_name | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description must cover behavioral traits. It states that the tool creates a contact and returns JSON details, but it does not disclose potential side effects (e.g., duplication checks, authentication needs, or rate limits). The description is adequate but leaves 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 structured with Args and Returns sections, making it easy to scan. It is not overly verbose, but the parameter list repeats schema information without significant condensation. A small trim would improve 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 the tool has 6 parameters (2 required), an output schema, and no annotations, the description covers the essential inputs and output. It lacks details on error handling or edge cases, but for a straightforward create operation it is nearly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, but the tool description provides explanations for all 6 parameters, including required labels. This adds meaning beyond the schema's type and title. However, it could be more precise (e.g., phone format) for a top score.
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 'Create a new contact in Crelate.' It uses a specific verb ('create') and resource ('contact'), and the tool name itself differentiates it from siblings like create_candidate or create_company.
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 the tool is for creating new contacts, but it does not provide explicit guidance on when to use this vs. alternatives (e.g., update_contact for existing contacts, or sister create tools). No exclusions or prerequisites are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new job/position in Crelate.
Args: name: Job title/name (required) company_name: Hiring company name location: Job location description: Job description
Returns: JSON string containing the created job details including ID
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| location | No | ||
| description | No | ||
| company_name | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavior. It only states 'Create' and returns JSON with details, missing side effects, permissions, idempotency, or error handling. This is minimal for a mutation 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 reasonably concise, using a clear list format for args and returns. It wastes few words but could be tightened by removing the 'Args:' and 'Returns:' headers if redundant.
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 4 parameters (1 required) and an output schema, the description covers all arguments and return type ('JSON string with details'). However, it omits error scenarios, prerequisites, or success conditions, making it adequate but not 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 0%, so the description compensates by providing basic semantics for all parameters: 'name: Job title/name (required)', 'company_name: Hiring company name', etc. It adds meaning beyond the schema but lacks detailed formats or constraints.
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 'Create a new job/position in Crelate', using a specific verb ('Create') and resource ('job/position'). It easily distinguishes from sibling tools like create_candidate or create_company.
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 explicit guidance on when to use versus alternatives (e.g., update_job or list_jobs). Usage is implied by the tool name and resource, but no when-not-to-use or context is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a note in Crelate and optionally attach it to a record.
Args: body: Note content (required) contact_id: Optional contact ID to attach note to candidate_id: Optional candidate ID to attach note to company_id: Optional company ID to attach note to job_id: Optional job ID to attach note to
Returns: JSON string containing the created note details
| Name | Required | Description | Default |
|---|---|---|---|
| body | Yes | ||
| job_id | No | ||
| company_id | No | ||
| contact_id | No | ||
| candidate_id | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It explains the creation action and optional attachments, but does not disclose behaviors like error handling for invalid record IDs, idempotency, or permissions. The return type is mentioned, but depth is limited.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with a docstring format. It front-loads the purpose, then lists arguments and return, all in few sentences. No redundant or unnecessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 5 parameters (1 required) and an output schema, so the description covers creation, parameter roles, and return value. It is complete for basic usage but could include more context on error conditions or validation of attached IDs.
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 0%, so the description must compensate. The Args section clearly explains each parameter: body is required content, and contact_id, candidate_id, company_id, job_id are optional IDs to attach the note. This adds meaning beyond the schema's type/default info.
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 and resource: 'Create a note in Crelate and optionally attach it to a record.' It distinguishes from sibling tools like create_candidate which create different entities, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for creating notes with optional attachments, but lacks explicit guidance on when not to use this tool (e.g., if only viewing notes) or alternatives. However, the context of sibling tools suggests no other note-creation tool exists.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a task in Crelate and optionally attach it to a record.
Args: body: Task description (required) due_date: Optional due date in ISO 8601 format (e.g., '2026-01-20T15:00:00Z') contact_id: Optional contact ID to attach task to candidate_id: Optional candidate ID to attach task to company_id: Optional company ID to attach task to job_id: Optional job ID to attach task to
Returns: JSON string containing the created task details
| Name | Required | Description | Default |
|---|---|---|---|
| body | Yes | ||
| job_id | No | ||
| due_date | No | ||
| company_id | No | ||
| contact_id | No | ||
| candidate_id | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must cover behavioral traits. It describes creating a task and returning details, but does not mention permissions, side effects, or error conditions. 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?
The description is concise with a clear purpose, then lists each parameter with formatting and optionality, and notes the return type. No superfluous 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?
The tool has 6 parameters and returns a JSON string. The description covers all input details and the return value. Given the output schema exists, no further explanation 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?
The schema has 0% description coverage, but the description provides detailed documentation for each parameter, including format (ISO 8601 for due_date) and purpose (e.g., which IDs for attaching). Adds significant value 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 'create' and the resource 'task in Crelate', with an optional attachment to records. This distinguishes it from siblings like create_candidate or create_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 explains the main use case and optional attachments, but does not explicitly list when not to use or provide contrast with alternatives. However, the purpose is clear enough for agents.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get activity/interaction history with optional filtering.
Args: limit: Maximum number of activities to return (default: 50) offset: Number of activities to skip for pagination (default: 0) contact_id: Filter by contact ID candidate_id: Filter by candidate ID job_id: Filter by job ID company_id: Filter by company ID
Returns: JSON string containing activity history (calls, emails, notes, etc.)
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| job_id | No | ||
| offset | No | ||
| company_id | No | ||
| contact_id | No | ||
| candidate_id | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries full burden. It discloses pagination via limit/offset and lists return types, but does not mention rate limits, authentication, data scope (e.g., user vs org), or whether activities are up-to-date.
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 well-structured with a brief purpose statement followed by a clear parameter list and return description. It is slightly lengthy due to the parameter list but remains focused 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 six parameters, no annotations, and an output schema, the description covers the parameters and return type adequately. However, it lacks details on how filters combine (AND/OR) and the scope of activities (current user vs entire org), leaving minor 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?
The schema has 0% description coverage, leaving the parameters undocumented in the schema itself. The tool description's Args section provides clear, meaningful explanations for all six parameters, adding essential semantics beyond the schema types and defaults.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves activity/interaction history with optional filtering by specific IDs. It is distinct from simple get tools but does not explicitly differentiate from sibling tools like get_contact_history or get_job_history, which may overlap.
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 such as get_activity_count, get_contact_history, or get_job_history. The description lacks context about typical use cases or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get total count of activities with optional filtering.
Args: contact_id: Filter by contact ID candidate_id: Filter by candidate ID job_id: Filter by job ID
Returns: JSON string containing activity count
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | No | ||
| contact_id | No | ||
| candidate_id | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility. The verb 'get' and the nature of counting imply a read-only, non-destructive operation, but this is not explicitly stated. No side effects or behavioral traits (e.g., rate limits, authentication needs) are disclosed.
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-line purpose followed by a clean list of parameters and return type. No redundant text; every sentence adds value. It is well-structured and front-loaded with the main purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the existence of an output schema (context indicates yes), the description still explains the return type ('JSON string containing activity count'), which is helpful. For a simple count tool with optional filters, this is nearly complete. Minor gaps: no mention of default behavior when no filters are applied.
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 0%, but the description explicitly lists each parameter (contact_id, candidate_id, job_id) with the phrase 'Filter by ...' This adds clear meaning beyond the schema titles, indicating they are optional filters. However, details like how multiple filters combine or required format are missing.
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 'Get total count of activities with optional filtering.' This identifies the specific action (get count) and resource (activities). It implicitly distinguishes from sibling such as get_activities (which returns list) and get_application_count (different resource), but does not explicitly differentiate.
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 given on when to use this tool versus alternatives (e.g., get_activities for details). There are no prerequisites, when-not conditions, or context for optimal usage. Agent must 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.
Get count of applications with optional filtering.
Args: job_id: Filter by specific job ID status: Filter by application status
Returns: JSON string containing application count
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | No | ||
| status | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries burden. Clearly indicates read-only count operation with optional filtering. Returns JSON string with count. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise: one sentence for purpose, then clearly structured Args and Returns. No wasted words. Front-loaded with main 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 simple count tool with two optional params and no output schema shown, the description provides everything needed: purpose, filters, and return type. No 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 coverage is 0%, but description adds meaningful descriptions for both parameters: 'Filter by specific job ID' and 'Filter by application status'. Compensates fully for lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Get count of applications' with optional filtering. Distinguishes from sibling 'get_applications' which returns a list. Specific verb 'get count' and resource 'applications'.
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 usage for totals vs details, but does not explicitly contrast with 'get_applications' or other count tools. Context is clear enough for a simple count operation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get job applications with filtering options.
Args: limit: Maximum number of applications to return (default: 50) offset: Number of applications to skip for pagination (default: 0) job_id: Filter by specific job ID candidate_id: Filter by specific candidate ID status: Filter by application status
Returns: JSON string containing applications (candidate pipeline data)
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| job_id | No | ||
| offset | No | ||
| status | No | ||
| candidate_id | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavior. It implies read-only via 'Get,' but lacks details on permissions, rate limits, or side effects. The mention of 'candidate pipeline data' 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 uses a docstring format with Args and Returns sections, which is structured but verbose. Some parameter descriptions simply restate schema info (e.g., limit default), making it longer than 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?
Given moderate complexity (5 parameters) and no annotations, the description covers parameters and return type but lacks usage guidance, behavioral context, and differentiation from sibling tools. Output schema exists but is not leveraged in 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 0%, so the description must clarify parameters. It provides brief descriptions for all 5 parameters (e.g., 'Filter by specific job ID'), adding meaning beyond the schema property names. However, it omits valid values (e.g., for status) and relies on the schema for defaults.
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 'Get job applications with filtering options,' specifying the verb and resource. It does not explicitly distinguish from sibling tools like get_application_count or list_candidates, but the purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives (e.g., list_candidates for broader candidate data). No prerequisites, examples, or context are included.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get detailed information about a specific candidate.
Args: candidate_id: The unique ID of the candidate
Returns: JSON string containing full candidate details including skills, experience, etc.
| Name | Required | Description | Default |
|---|---|---|---|
| candidate_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
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 the tool returns a JSON string with full details, but does not explicitly state it is read-only, what happens on missing ID, or any other behavioral traits. Adequate but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (4 lines), front-loaded with the purpose, and efficiently covers the argument and return value without extraneous text.
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 simple tool with one parameter and an output schema available, the description covers the essential information. Minor gaps like edge case behavior are not addressed, but overall sufficient.
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 0% schema description coverage, the description explains the sole parameter candidate_id as 'The unique ID of the candidate', adding necessary meaning beyond the schema's type and title.
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 'Get detailed information about a specific candidate', using a specific verb and resource, and distinguishes from sibling tools like list_candidates and create_candidate.
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 does not provide any guidance on when to use this tool versus alternatives, such as list_candidates for summaries or other get_ tools. No context on prerequisites or exclusions is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get detailed information about a specific company.
Args: company_id: The unique ID of the company
Returns: JSON string containing full company details
| Name | Required | Description | Default |
|---|---|---|---|
| company_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavior. It only mentions returning 'full company details' without specifying what that includes, authentication needs, or idempotency. Lacks transparency about side effects or constraints.
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 very concise, front-loading the purpose. It uses a simple structure but lacks sections or formatting that could improve readability. 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?
Given the tool has one parameter and an output schema (not shown), the description provides minimal context. It does not explain return value structure or when to use this over sibling tools. Adequate but not 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 schema has one required parameter (company_id) with 0% description coverage. The description adds basic meaning ('The unique ID of the company'), which is helpful but not rich. It meets a baseline for a single parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get detailed information about a specific company' with a specific verb and resource. It distinguishes itself from siblings like get_company_count and list_companies by focusing on a single entity.
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 list_companies or get_company_sources. The description does not provide context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get total count of companies with optional search filter.
Args: search: Optional search query to filter companies
Returns: JSON string containing company count
| Name | Required | Description | Default |
|---|---|---|---|
| search | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
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 the return format (JSON string with count) but does not mention potential side effects, caching, or error handling. The behavior is minimal and predictable, so a middling score is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the primary action. The 'Args' and 'Returns' sections are clear and free of unnecessary 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?
Given the tool's simplicity (one optional parameter, straightforward output) and the presence of an output schema (not shown), the description covers the essential aspects. It could be slightly enhanced by mentioning any limitations on the search filter, but overall it is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must add meaning. The description explains the 'search' parameter as an optional filter query, which is helpful. It adds context beyond the schema's type definition, though it could further clarify acceptable input 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 tool retrieves a total count of companies with an optional search filter, using a specific verb and resource. It distinguishes itself from sibling tools like 'get_company' (single company) and 'list_companies' (list details).
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 counting companies but does not provide explicit guidance on when to use this tool versus alternatives such as 'get_application_count' or 'get_contact_count'. No exclusions or trade-offs are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get all company sources for tracking where companies came from.
Args: limit: Maximum number of sources to return (default: 50) offset: Number of sources to skip for pagination (default: 0)
Returns: JSON string containing company source data
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| offset | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description adds value by documenting pagination parameters (limit, offset) and return format (JSON string). It implicitly indicates a read operation, but could explicitly state idempotency.
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 front-loaded with a clear purpose, followed by concise Args and Returns sections. Every sentence is necessary and to the point, with no fluff.
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 (2 parameters, read-only), the description covers retrieval and pagination. The return type is specified as 'JSON string containing company source data,' which is sufficient but could be more detailed about the 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?
Schema coverage is 0%, but the description fully explains both parameters: limit (max number, default 50) and offset (pagination skip, default 0), adding meaning beyond the bare 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 'Get all company sources for tracking where companies came from,' which specifies the verb 'Get' and resource 'company sources,' distinguishing it from sibling tools like get_contact_sources.
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 company sources but provides no explicit guidance on when to use this tool versus alternatives like get_company or get_contact_sources. No exclusions or context are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get detailed information about a specific contact.
Args: contact_id: The unique ID of the contact
Returns: JSON string containing full contact details
| Name | Required | Description | Default |
|---|---|---|---|
| contact_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. The description discloses the return format (JSON string) but lacks details on read-only behavior, authentication, or error handling. Minimal over the bare minimum.
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 no extraneous words. The Args/Returns structure 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?
Adequate for a simple get tool with one parameter and an output schema. However, it does not describe what 'full contact details' includes or mention possible errors.
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% coverage, but the description adds a clear semantic description for contact_id: 'The unique ID of the contact'. This compensates well.
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 gets detailed information about a specific contact, distinguishing it from sibling list or count tools. The verb 'Get' and resource 'contact' are specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like get_contact_history or list_contacts. The description does not mention any prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get total count of contacts with optional search filter.
Args: search: Optional search query to filter contacts
Returns: JSON string containing contact count
| Name | Required | Description | Default |
|---|---|---|---|
| search | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. The description states it returns a JSON string with contact count, but does not disclose side effects, auth requirements, or that it is a read-only operation.
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 very short and front-loaded with the core purpose. However, the parameter documentation could be more 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 a simple tool with one optional parameter and an output schema, the description sufficiently covers the basic functionality, though it lacks depth in behavioral 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?
The schema has 0% description coverage. The description merely repeats 'search: Optional search query to filter contacts' without adding formatting, constraints, or examples 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 tool's purpose: 'Get total count of contacts with optional search filter.' It uses a specific verb and resource, distinguishing it from sibling tools like get_contact or list_contacts.
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_contacts or get_contact. No mention of use cases or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get interaction history for contacts.
Args: contact_id: Specific contact ID (optional) limit: Maximum number of history items to return (default: 50) offset: Number of items to skip for pagination (default: 0)
Returns: JSON string containing contact interaction history
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| offset | No | ||
| contact_id | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must fully disclose behavioral traits. It only states the tool returns a JSON string and lists parameters, but omits details like whether it is read-only, authentication requirements, rate limits, or error handling (e.g., if contact_id is null). This is insufficient for safe invocation.
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, consisting of two short sentences plus a clear parameter list with 'Args' and 'Returns' sections. No extraneous words, and the structure aids quick comprehension.
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 an output schema (though not shown), the description adequately covers the return format as 'JSON string containing contact interaction history'. However, it lacks details on pagination behavior (e.g., what happens when limit is reached) or the effect of not providing a contact_id, leaving minor 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?
The description adds meaningful explanations for each parameter beyond the schema (e.g., 'Specific contact ID (optional)', 'Maximum number of history items', 'Number of items to skip for pagination'). Despite 0% schema coverage, the description effectively documents all three parameters.
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 'interaction history for contacts', directly conveying the tool's purpose. It distinguishes from sibling tools like 'get_contact' (which retrieves contact details) and 'get_job_contact_history' (which is job-specific).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide explicit guidance on when to use this tool versus alternatives, such as 'get_contact' or 'get_job_contact_history'. The use case is implied by the name and parameters but lacks explicit context or conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get all contact sources for tracking where contacts came from.
Args: limit: Maximum number of sources to return (default: 50) offset: Number of sources to skip for pagination (default: 0)
Returns: JSON string containing contact source data
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| offset | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. The description mentions parameters for pagination (limit, offset) and states the return format (JSON string). However, it does not disclose potential side effects, authentication requirements, or other behavioral traits.
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 brief, front-loaded with the main purpose, and uses a clear structured format for parameters and return value. No redundant or wasted sentences.
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?
With an output schema present, the description covers the main purpose and parameters adequately. However, it does not mention that results are paginated or that ordering is unspecified, leaving some minor 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?
Despite 0% schema description coverage, the description explains both parameters (limit and offset) with their defaults and purpose, adding value beyond the schema's type and default fields.
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 the resource 'contact sources', and specifies the purpose 'for tracking where contacts came from'. This effectively distinguishes it from sibling tools like get_company_sources.
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 (e.g., get_company_sources). Given the presence of similar sibling tools, explicit differentiation is missing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get information about the current authenticated user.
Returns: JSON string containing current user details
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description must disclose behavioral traits. It only mentions the return type (JSON string) but does not cover authentication requirements, potential errors, or any side effects beyond being a read operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (two short sentences) and front-loaded with the main purpose. The 'Returns' line adds minimal value but does not waste space.
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 presence of an output schema, the description need not detail return fields. However, it lacks context about when this tool is appropriate or any constraints, making completeness moderate.
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 zero parameters, so the schema provides full coverage. The description does not need to add parameter semantics; baseline is 4.
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 purpose: 'Get information about the current authenticated user.' It distinguishes from sibling tools like get_user_info by specifying 'current' and 'authenticated', making the scope unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for the current user but does not explicitly guide when to use this tool over alternatives like get_user_info. No direct comparison or exclusions are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get count of invoices with optional status filter.
Args: status: Filter by invoice status
Returns: JSON string containing invoice count
| Name | Required | Description | Default |
|---|---|---|---|
| status | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It states 'Get count' which implies a read-only operation, but does not explicitly confirm no side effects, permissions required, or limitations (e.g., maximum count, performance). This is insufficient for a mutation-free guarantee.
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 for the core purpose plus a brief parameter and return docstring. No unnecessary words or repetition, making it efficient and easy 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 the tool's simplicity and presence of an output schema (not shown), the description provides the essential purpose and parameter. However, it lacks details on error scenarios, return format specifics (beyond 'JSON string'), and edge cases (e.g., no invoices). It is minimally adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must add meaning beyond the parameter name. It merely restates 'Filter by invoice status' without specifying valid values, format, or behavior when omitted. This adds no value over 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 retrieves a count of invoices with an optional status filter. It distinguishes itself from sibling tools like 'get_invoices' which likely returns list data, and other count tools by specifying the resource (invoices) and the optional filter.
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 is provided on when to use this tool versus alternatives like 'get_invoices' for full data or other count tools. The description implies use for counts only, but lacks explicit context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get detailed information about a specific invoice.
Args: invoice_id: The invoice ID
Returns: JSON string containing detailed invoice information
| Name | Required | Description | Default |
|---|---|---|---|
| invoice_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description must cover behavioral traits. It does not disclose idempotency, read-only nature, error conditions, or rate limits. The word 'Get' implies a read operation but is not explicit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Very concise (2 sentences) but lacks essential information. Structured with Args/Returns, but the content is minimal. Conciseness should not sacrifice completeness.
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?
Despite having an output schema, the description does not leverage it to explain return value structure or content. Lacks coverage of behavioral aspects, usage scenarios, and parameter details. Insufficient for a tool with zero annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description should enrich parameter meaning. It only restates 'The invoice ID' which duplicates the schema title. No additional details like format, required length, or example values.
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?
Explicitly states the action 'Get detailed information' and the resource 'specific invoice'. Clearly distinct from sibling tools like get_invoices (list) and get_invoice_count (count).
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 over alternatives. Does not mention context such as prerequisites or whether it requires the invoice to exist.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get invoice records for financial reporting.
Args: limit: Maximum number of invoices to return (default: 50) offset: Number of invoices to skip for pagination (default: 0) status: Filter by invoice status
Returns: JSON string containing invoice data
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| offset | No | ||
| status | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It does not disclose whether the tool is read-only, requires specific permissions, or has any side effects. While it states it returns a JSON string, it lacks details about rate limits, data freshness, or potential authorization requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: one sentence for purpose followed by a clear list of parameters with defaults. It is front-loaded with the primary action, and every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the existence of an output schema (mentioned in context), the description adequately covers the purpose, parameters, and return type. However, it could mention that it returns a list of invoices or that pagination is handled via offset. Overall, it is nearly complete for a simple list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explicitly documents each parameter (limit, offset, status) with defaults and purpose, adding significant meaning beyond the schema titles. Schema coverage is effectively 100% via the description, enabling proper agent usage.
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 'Get invoice records for financial reporting,' specifying both the verb 'Get' and the resource 'invoice records.' This distinguishes it from sibling tools like get_invoice_count and get_invoice_info, which serve different purposes (count vs. single info).
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 use case context ('for financial reporting') but does not explicitly specify when to choose this tool over alternatives like get_payments or get_invoice_count. No when-not-to-use or exclusion criteria are provided, leaving selection to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get detailed information about a specific job/position.
Args: job_id: The unique ID of the job
Returns: JSON string containing full job details including description, requirements
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It states the tool returns a JSON string, implying a read operation, but does not explicitly confirm non-destructive behavior, authentication requirements, or error handling. The description is minimal, lacking transparency about side effects or prerequisites.
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 very concise: three lines with purpose, args, and returns. Every part is useful, no fluff. The structure is clear and front-loaded, with the core action stated first.
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 existence of an output schema, the return description is adequate. However, the description lacks context about error scenarios, prerequisite knowledge (e.g., job_id from list_jobs), and differentiation from siblings. It is minimally complete for a simple get tool but does not fully address agent decision-making.
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 0%, so the description must compensate. It adds the semantic meaning for the single parameter job_id: 'The unique ID of the job', which clarifies its purpose. While more detail (e.g., format, source) could improve, the current addition is valuable and 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 'Get detailed information about a specific job/position', which specifies the verb (Get) and resource (job). The additional return details ('full job details including description, requirements') further clarify the scope, distinguishing it from sibling tools like get_job_contacts or list_jobs.
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. Siblings include get_job_contacts, get_job_history, and list_jobs, but the description does not differentiate usage contexts, such as 'use this after obtaining a job ID from list_jobs' or 'use other tools for specific subsets'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get interaction history for contacts on a specific job.
Args: job_id: The job ID (required) limit: Maximum number of history items to return (default: 50) offset: Number of items to skip for pagination (default: 0)
Returns: JSON string containing job-contact interaction history
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| job_id | Yes | ||
| offset | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so description must carry behavioral info. It states returns JSON string but does not declare read-only nature, auth requirements, or potential side effects. Adequate but not rich.
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 concise with clear Args and Returns sections. No unnecessary words, each sentence adds value. Perfectly sized for a simple retrieval tool.
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 and existence of output schema, description is mostly complete. Parameter docs are thorough. Could briefly mention what 'interaction history' entails but not required.
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 no descriptions (0% coverage) but the description fully documents all three parameters: job_id required, limit with default, offset for pagination. Adds significant 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 it gets interaction history for contacts on a specific job, using specific verb and resource. It distinguishes from sibling tools like get_contact_history and get_job_history.
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 when to use (for contact interaction history per job) but provides no explicit guidance on when not to use or alternatives. Sibling tool names suggest differentiation but description doesn't mention them.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get all contacts/candidates associated with a job.
Args: job_id: The job ID (required) limit: Maximum number of contacts to return (default: 50) offset: Number of contacts to skip for pagination (default: 0)
Returns: JSON string containing contacts linked to the job
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| job_id | Yes | ||
| offset | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It explains the return type (JSON string) and mentions pagination parameters, but does not explicitly state that the operation is read-only and safe. It is clear and non-misleading, earning a high score.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with a clean docstring format: one sentence for purpose, then Args and Returns sections. It is front-loaded and efficient, though the Args could be slightly more streamlined without losing clarity.
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 covers the main purpose, all parameters, and the return type. Since an output schema exists, detailed return field documentation is not needed. However, it lacks information on error handling or behavior when job_id is invalid, which would enhance completeness.
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% description coverage, so the description fully compensates. It explains each parameter: job_id as required, limit as max contacts (default 50), and offset as pagination skip (default 0). This adds significant meaning beyond the schema's bare properties.
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 all contacts/candidates associated with a job', which is a specific verb-resource pairing. It differentiates from siblings like 'get_contact' (single contact) and 'list_contacts' (all contacts) by specifying the association with a 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 when retrieving contacts for a specific job, but it does not explicitly state when to use this tool over alternatives like 'list_contacts' or 'get_contact'. No guidance on exclusions or prerequisites is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get total count of jobs with optional status filter.
Args: status: Filter by job status (e.g., 'open', 'closed')
Returns: JSON string containing job count
| Name | Required | Description | Default |
|---|---|---|---|
| status | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It clearly indicates a read-only operation returning a count, and the optional filter is explained. No side effects or permissions are mentioned, but for a simple count query, this is sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: one sentence for purpose, followed by structured Args and Returns. No fluff, all sentences are necessary and 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 count tool with one optional parameter and an output schema, the description covers what, how to filter, and what will be returned (JSON string with count). It is 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?
Despite 0% schema description coverage, the description adds valuable context for the 'status' parameter with examples ('open', 'closed') and its purpose (filter). This compensates for the schema's lack of description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get total count of jobs') and the resource, distinguishing it from sibling tools like list_jobs (which returns a list) and other count tools (e.g., get_application_count).
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 a count is needed) and mentions the optional status filter, but does not explicitly state when to use alternatives like list_jobs for detailed data or other count tools for different entities.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get history for jobs/positions.
Args: job_id: Specific job ID (optional) limit: Maximum number of history items to return (default: 50) offset: Number of items to skip for pagination (default: 0)
Returns: JSON string containing job history
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| job_id | No | ||
| offset | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavior. It only indicates the output is a JSON string, failing to mention read-only nature, permissions, rate limits, or any side effects. This is insufficient for a data retrieval 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, using a clear Args/Returns structure. Every sentence provides necessary information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has three parameters and an output schema, the description is insufficient. It does not explain what constitutes history, ordering, pagination behavior, or any constraints. The minimal information leaves gaps for 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?
The description lists all three parameters (job_id, limit, offset) with their optionality and defaults, which adds value beyond the bare schema (0% coverage). However, it lacks details like description of limit's maximum or job_id's format.
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 'Get history for jobs/positions,' specifying the resource (history) and the associated entities (jobs/positions). This adequately defines the tool's purpose and distinguishes it from other get_* tools in the sibling list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like get_job, get_job_contacts, or get_activities. No usage context, prerequisites, or exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get information about the current organization.
Returns: JSON string containing organization details and settings
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description only states it returns a JSON string but does not disclose side effects, permissions needed, or that it is read-only. Minimal behavioral 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?
Description is two concise sentences with no redundant information. Efficiently conveys purpose and return type.
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 parameterless tool with an output schema, the description is adequate. It explains the tool's purpose and return type, though it could mention that the output is a JSON string containing organization details and settings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters, so description does not need to add parameter details. Baseline score of 4 is appropriate given 100% schema coverage and absence of params.
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 'Get' and clear resource 'organization info' with scope 'current organization'. It effectively distinguishes from sibling tools like get_current_user or get_company.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description implies usage for retrieving organization details but provides no explicit guidance on when to use this tool versus alternatives or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get payment records for financial tracking.
Args: limit: Maximum number of payments to return (default: 50) offset: Number of payments to skip for pagination (default: 0)
Returns: JSON string containing payment data
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| offset | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Only mentions return type (JSON string) but no details on authentication, rate limits, side effects, or pagination behavior beyond offset/limit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise docstring format with one-line purpose, then parameter descriptions. No redundant or irrelevant text.
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 output schema present. Lacks details on filtering, ordering, or the structure of returned data, but minimal completeness for straightforward 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 has no descriptions (0% coverage). Description explains 'limit' as maximum number to return and 'offset' as pagination skip, adding basic 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 'Get' and the resource 'payment records', with purpose 'for financial tracking'. Distinguishes from sibling tools like get_invoices or get_placements.
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 (e.g., get_invoices). No mention of prerequisites, context, or when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get detailed information about a specific placement.
Args: placement_id: The placement ID
Returns: JSON string containing detailed placement information
| Name | Required | Description | Default |
|---|---|---|---|
| placement_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description should disclose behavior. It only states 'get detailed information' without specifying if the tool is read-only, idempotent, or has any side effects. Minimal 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 very short but includes unnecessary formatting (Args/Returns headers). It could be more concise. Adequate but not optimized.
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 one parameter and an output schema (exists), the description is somewhat complete. However, it lacks details on return format (beyond 'JSON string') and error conditions. Adequate for a simple getter.
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 'The placement ID' for the parameter, but schema description coverage is 0%. No additional meaning is provided (e.g., format, source, constraints). Barely adds value over the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves detailed information for a specific placement, using a specific verb and resource. It distinguishes itself from sibling tools like 'get_placements' (plural) and other getters.
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, such as 'get_placements' for listing. The description lacks context on prerequisites or scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get placement records (successful hires).
Args: limit: Maximum number of placements to return (default: 50) offset: Number of placements to skip for pagination (default: 0) status: Filter by placement status
Returns: JSON string containing placement data including hire dates, salaries, etc.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| offset | No | ||
| status | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
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 the tool is a 'Get' operation (read-only) and returns a JSON string with data, but does not disclose additional traits like pagination limits beyond defaults, or potential performance considerations. This is sufficient for a simple read operation but lacks depth.
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 title line and a brief Args/Returns section. Every sentence provides necessary information without redundancy. It is front-loaded with the core purpose and then details parameters and return type efficiently.
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 3 optional parameters, a list output, and an output schema exists, the description covers the essential aspects: what the tool does, what it returns (with examples like hire dates and salaries), and how parameters work. It is missing explicit mention of ordering or default behavior for missing parameters, but it is complete enough for a basic listing tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must add meaning beyond the schema. It explains each parameter: 'limit' as maximum number, 'offset' for pagination skip, and 'status' for filtering. This adds clarity that the schema (with only titles and defaults) does not fully provide, earning a 4.
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 'Get placement records (successful hires),' which specifies the verb ('Get'), the resource ('placement records'), and the scope ('successful hires'). This distinguishes it from sibling tools like 'get_placement_info' (singular) or other list tools, making the purpose unmistakable.
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 does not explicitly state when to use this tool versus alternatives such as 'get_placement_info' for a single record. It implies use for listing placements but offers no exclusion criteria or context-based guidance, which is adequate but not exceptional.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get tag categories for organizational reporting.
Args: limit: Maximum number of categories to return (default: 50) offset: Number of categories to skip for pagination (default: 0)
Returns: JSON string containing tag category data
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| offset | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. Description only mentions return format but lacks details on behavior (e.g., read-only, pagination limits, error handling). Relies on tool name for basic inference.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Very concise with a one-line summary followed by parameter and return docs. Front-loaded and no redundant text.
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?
Adequately covers purpose, parameters, and return type for a simple list endpoint. Lacks guidance on pagination strategy or edge cases, but output schema may compensate.
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 0% description coverage, but the tool's description provides clear meaning for 'limit' and 'offset' parameters, explaining their roles in pagination and defaults.
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 'Get' and resource 'tag categories' with the purpose 'for organizational reporting'. Distinguishes from sibling 'get_tags' which likely retrieves individual tags.
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 or avoid this tool. Does not differentiate from alternative tools like 'get_tags' or mention any prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get tags for categorization and reporting.
Args: limit: Maximum number of tags to return (default: 50) offset: Number of tags to skip for pagination (default: 0) category: Filter by tag category
Returns: JSON string containing tag data
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| offset | No | ||
| category | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It mentions returning a JSON string and basic pagination, but does not disclose whether the operation is read-only, any side effects, authorization requirements, or default ordering. This is minimal 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 concise with a clear 'Args' and 'Returns' structure. Every sentence adds value, though it could be slightly more structured with bullet points for readability.
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 (no required params, output schema exists), the description adequately explains parameters and return type. However, it omits details like default ordering, potential empty results, or relationship to tag categories. Adequate but not 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 0%, so the description compensates by explaining each parameter's purpose: limit as max number, offset for pagination, category for filtering. This adds meaning beyond the schema's types and defaults.
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 the resource 'tags', with additional context about use for categorization and reporting. It distinguishes from sibling tool 'get_tag_categories' by focusing on tags themselves.
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 'get_tag_categories' or other retrieval tools. The description lacks any conditional or comparative context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get total count of users in the organization.
Returns: JSON string containing user count
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description covers the return type (JSON string) but does not disclose any behavioral traits such as authentication requirements, rate limits, or data freshness. For a simple read-only tool, this is adequate but minimal.
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 sentences) with no unnecessary words, and the key purpose is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description states the return format (JSON string with user count). Given no parameters and the simplicity of the tool, it is complete enough, though it could mention if the count is real-time or cached.
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 zero parameters, so the description need not add parameter information. Baseline score of 4 is appropriate as the description is sufficient.
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 total count') and the resource ('users in the organization'), distinguishing it from sibling tools like get_users (list) and get_user_info (specific user).
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 is provided. While the context of siblings implies it is for a simple count, no exclusions or specific use cases are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get detailed information about a specific user.
Args: user_id: The user ID
Returns: JSON string containing user details and activity information
| Name | Required | Description | Default |
|---|---|---|---|
| user_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must carry full burden. It states 'Get' implying read-only, but does not disclose any side effects, permission requirements, rate limits, or error conditions. The return type is mentioned ('JSON string'), but behavioral details are lacking.
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 short and to the point, with a clear structure (purpose, args, returns). Every sentence serves a purpose, and it avoids verbosity. However, it could be more structured (e.g., bullet points or explicit sections).
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?
With an output schema present, the description does not need to detail return values, but it does not explain what 'detailed information' includes or handle edge cases. Despite low complexity (1 param), the lack of usage context and behavioral details makes it incomplete.
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 0% description coverage. The description adds 'user_id: The user ID', which essentially restates the parameter name. No format, example, or constraints provided. Given zero schema coverage, the description fails to compensate.
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 specifies the action ('Get') and resource ('detailed information about a specific user'), and distinguishes from sibling tools like get_current_user (current user) and get_users (list). The mention of 'user_id' parameter further clarifies scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives (e.g., get_current_user, get_candidate). No prerequisites, exclusions, or context for when it is appropriate. The description only states what it does, leaving the agent to infer usage from the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get all users in the organization.
Args: limit: Maximum number of users to return (default: 50) offset: Number of users to skip for pagination (default: 0)
Returns: JSON string containing user data for team activity analysis
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| offset | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must cover behavioral traits. It mentions pagination and return format (JSON string for team activity analysis) but omits critical details like permission requirements, rate limits, or performance implications. The lack of annotation support leaves agents uninformed about safety and mutability.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise at three sentences, with the main purpose front-loaded. It follows a clear structure (purpose, args, returns). Minor improvements could remove the redundant parameter listing since the schema already defines them.
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 2 parameters with no enums, an output schema exists, and the tool is a list operation, the description adequately covers pagination and return format. However, it lacks details about sorting, filtering, or implicit ordering, which would help agents understand the full behavior.
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 restates the parameter names and defaults that are already in the input schema. For simple integer parameters, this adds minimal value. With schema coverage at 0%, the description does clarify usage (e.g., 'maximum number' and 'skip for pagination') but does not go beyond the schema's own information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get all users in the organization,' which is a specific verb and resource. However, it does not differentiate from sibling tools like get_user_info or get_user_count, which could lead to confusion about which tool to use for listing vs. single user retrieval.
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 get_user_info or get_current_user. It only explains pagination parameters but lacks context for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get workflow statuses for pipeline stage analysis.
Args: limit: Maximum number of statuses to return (default: 50) offset: Number of statuses to skip for pagination (default: 0)
Returns: JSON string containing workflow status data
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| offset | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
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 only mentions the return format (JSON string) and pagination parameters, but does not state read-only nature, potential side effects, or any prerequisites. This is minimal for a tool likely performing a read operation.
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 very concise, using a clean structure with Args and Returns sections. Every sentence adds value without redundancy. It is front-loaded with the core purpose and quickly lists parameters.
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 simple (list with pagination) and has an output schema, so the description need not detail return fields. However, it does not describe what a 'workflow status' is or any filtering capabilities beyond pagination. It is minimally complete but leaves some ambiguity about the data's nature.
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% description coverage, so the description must compensate. It explains both parameters clearly: limit (max number, default 50) and offset (skip for pagination, default 0). This adds essential meaning beyond the schema's type/default fields.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves workflow statuses for pipeline stage analysis. The verb 'Get' and resource 'workflow statuses' are specific, and the context distinguishes it from sibling tools focused on candidates, companies, contacts, jobs, etc.
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 or when not to use it. The description lacks explicit usage context or exclusions, leaving the agent without direction for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List candidates from Crelate.
Args: limit: Maximum number of candidates to return (default: 50) offset: Number of candidates to skip for pagination (default: 0) search: Optional search query to filter candidates
Returns: JSON string containing list of candidates
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| offset | No | ||
| search | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and the description lacks behavioral details. Does not mention pagination behavior, result ordering, or any side effects. Only lists parameters.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Very concise with a clear header, parameter list, and return type. Every sentence is informative and 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?
Adequate but missing details like ordering, search syntax, pagination for large result sets, and the actual fields in the response. Has output schema but description only says 'JSON string containing list of candidates'.
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 0%, but the description adds meaning by explaining each parameter (limit, offset, search) and their defaults. Adds value beyond the schema definition.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the action ('List') and resource ('candidates from Crelate'). Distinct from siblings like 'get_candidate' (single) and 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?
No guidance on when to use this tool vs alternatives. Doesn't mention when not to use it or contrast with get_candidate or 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 companies from Crelate.
Args: limit: Maximum number of companies to return (default: 50) offset: Number of companies to skip for pagination (default: 0) search: Optional search query to filter companies
Returns: JSON string containing list of companies
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| offset | No | ||
| search | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It only mentions return type as JSON string, but does not cover pagination behavior beyond offset/limit, sorting, or any side effects. Minimal disclosure.
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 a two-sentence summary, an Args block, and Returns. Every sentence serves a purpose and is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity (3 optional params, output schema exists), the description covers the essential behavior. It could mention search behavior when empty or sorting, but it's adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description adds meaning for all three parameters (limit, offset, search) by stating defaults and the search as optional filter. This adds value beyond the schema's type-only info.
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 'companies' clearly, and the tool name distinguishes it from siblings like list_candidates. However, the description does not explicitly differentiate from these siblings, which would warrant 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?
No guidance is provided on when to use this tool versus alternatives like get_company or search-based filtering. The description lacks context for selection among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List contacts from Crelate.
Args: limit: Maximum number of contacts to return (default: 50) offset: Number of contacts to skip for pagination (default: 0) search: Optional search query to filter contacts
Returns: JSON string containing list of contacts with id, name, email, phone
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| offset | No | ||
| search | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It implies a read-only listing operation and explains the return format, but it does not explicitly state it is non-destructive or disclose any potential side effects, though none are expected for a list function.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured, with a clear purpose statement followed by documented arguments and return value. Every sentence serves a purpose without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with three optional parameters and an output schema, the description adequately explains the return value (JSON with specific fields). It could mention pagination behavior more explicitly, but overall it 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 0%, but the description adds meaning by explaining each parameter's role (limit, offset, search) and their defaults. This compensates for the sparse schema, though parameter descriptions could be more detailed.
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 contacts from Crelate' with a specific verb and resource. It includes arguments and return value, distinguishing it from sibling tools like get_contact (single contact) and get_contact_count.
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, nor does it mention when not to use it or any prerequisites. It simply describes what the tool does without context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List jobs/positions from Crelate.
Args: limit: Maximum number of jobs to return (default: 50) offset: Number of jobs to skip for pagination (default: 0) status: Optional filter by job status (e.g., 'open', 'closed')
Returns: JSON string containing list of jobs with id, name, status, location
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| offset | No | ||
| status | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries the full burden. It mentions the return format (JSON with id, name, status, location) but does not disclose any behavioral traits such as rate limits, authentication requirements, or side effects. As a listing operation, it is likely safe, but not explicitly confirmed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with a clear structure: a one-line summary followed by Args and Returns sections. No redundant information, and every sentence serves a 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 tool's simplicity and the presence of an output schema, the description is fairly complete. It explains the return format and all parameters. Minor gaps: no mention of pagination behavior beyond offset/limit, and no examples.
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 includes an Args section that explains each parameter (limit, offset, status) with defaults and purpose. Since schema description coverage is 0%, this adds value beyond the schema. However, it could provide examples or constraints for the status parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists jobs/positions from Crelate, with a specific verb ('List') and resource ('jobs/positions'). It distinguishes from siblings like 'get_job' (single job) and 'get_job_count' (count).
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 or not use this tool vs alternatives. Usage is implied by the tool name and sibling context, but the description itself does not provide exclusion criteria or alternative tool references.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing contact in Crelate.
Args: contact_id: The unique ID of the contact to update first_name: Contact's first name last_name: Contact's last name email: Contact's email address phone: Contact's phone number title: Contact's job title
Returns: JSON string containing the updated contact details
| Name | Required | Description | Default |
|---|---|---|---|
| No | |||
| phone | No | ||
| title | No | ||
| last_name | No | ||
| contact_id | Yes | ||
| first_name | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It only states 'Update' but does not disclose permissions, idempotency, partial vs full update behavior, or what happens when optional fields are set to null. For a mutation without annotations, more is needed.
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 line for the action, then a clean parameter list. Every sentence adds value, and the main purpose is frontloaded.
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 the tool has an output schema and only 6 parameters, the description covers the basics well. However, it omits details about partial updates and error cases, which are minor gaps for a simple update tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description adds meaning by listing each parameter with a brief explanation (e.g., 'contact_id: The unique ID of the contact to update'). This goes beyond the schema's type/title, though it doesn't provide format constraints or defaults.
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 'Update an existing contact in Crelate', which is a specific verb+resource. It distinguishes this from 'create_contact' because it's an update operation, and the tool name reinforces this.
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 modifying a contact but does not explicitly state when to use versus alternatives like 'create_contact' or 'get_contact'. It lacks guidance on prerequisites (e.g., contact must exist) or when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0create_candidatecreate_companycreate_contactcreate_jobcreate_notecreate_taskget_activitiesget_activity_countget_application_countget_applicationsget_candidateget_companyget_company_countget_company_sourcesget_contactget_contact_countget_contact_historyget_contact_sourcesget_current_userget_invoice_countget_invoice_infoget_invoicesget_jobget_job_contact_historyget_job_contactsget_job_countget_job_historyget_organization_infoget_paymentsget_placement_infoget_placementsget_tag_categoriesget_tagsget_user_countget_user_infoget_usersget_workflow_statuseslist_candidateslist_companieslist_contactslist_jobsupdate_contactScored across 42 tools
Most tools have distinct purposes, e.g., get_candidate vs list_candidates. However, there is potential confusion between history tools like get_contact_history, get_job_history, and get_job_contact_history, which could overlap with get_activities. Overall, the set is largely disambiguated.
The naming follows a consistent verb_noun pattern with get_, list_, create_, and update_. However, update_contact is the only update tool, missing updates for candidates, companies, and jobs. There are no delete tools, breaking the expected CRUD pattern. The mix of get_ and list_ is acceptable but the absence of other operations is inconsistent.
With 42 tools covering candidates, companies, contacts, jobs, notes, tasks, activities, applications, placements, invoices, payments, users, tags, and workflow statuses, the count is high but justifiable for the breadth of the domain. Some tools like counts and sources could be merged, but overall it's reasonable.
The server is heavily read-focused with many get/list/count tools but lacks update operations for most entities (only update_contact) and has no delete tools at all. Missing operations like submitting applications, moving pipeline stages, or managing placements beyond reading leave significant gaps for a recruitment CRM lifecycle.
Model Context Protocol server for the Apideck Unified API. Connect any MCP-compatible agent framework to 100+ accounting systems, HRIS platforms, file storage providers, and more through one integration. More information https://www.apideck.com/mcp-server
API-first CRM for LLMs - contacts, companies, deals and activities over a native MCP server.
An MCP server that provides an API to LLMs to manage their JumpCloud resources.
MCP server that lets AI assistants use all OneSchema features exposed via the public API.
