The Harvest MCP Server provides comprehensive integration with the Harvest time tracking API, enabling AI assistants like Claude to manage time tracking, projects, clients, finances, and reporting through 40+ tools via natural language commands.
⏱️ Time Tracking
List, get, create, update, and delete time entries with rich filtering (by user, client, project, task, date range, billing status)
Start, stop, and restart timers in real-time
🏗️ Project Management
List, get, create, update, and delete projects with full configuration (budget, billing, rates, timelines)
Manage task assignments on projects
📝 Task Management
List, get, create, update, and delete tasks with billing defaults and hourly rates
🏢 Client Management
List, get, create, update, and delete clients with address, contact, and currency support
👥 User Management
List, get, create, update, and delete users with role and permission control
Get the current authenticated user's profile
💸 Expense Tracking
List, get, create, update, and delete expenses with category and billing details
Manage expense categories
🧾 Invoice Management
List, get, create, update, and delete invoices with tax, discount, and payment term support
Filter by state (draft, open, paid, closed)
📋 Estimate Management
List, get, create, update, and delete estimates with tax, discount, and currency support
Filter by state (draft, sent, accepted, declined)
📊 Reporting
Time reports — filter and group by user, client, project, task, or date
Expense reports — filter and group by user, client, project, category, or date
Project budget reports — track spending vs. budget, filter by over-budget projects
Uninvoiced reports — identify billable time and expenses not yet invoiced
🏢 Company Info
Retrieve company settings, billing configuration, and feature flags
Additional features include pagination support, date/status filtering, rate limiting compliance, and comprehensive input validation.
Unofficial Model Context Protocol (MCP) server for seamless integration with the Harvest time tracking API
⚠️ Disclaimer: This is an unofficial, third-party integration with the Harvest API. This project is not affiliated with, endorsed by, or sponsored by Harvest or Forecast (the company behind Harvest).
🔗 Complete Harvest API v2 Coverage - 40+ tools covering all major endpoints
🛡️ Type-Safe - Full TypeScript support with Zod validation
⚡ High Performance - Built with async/await and proper rate limiting
🧪 Thoroughly Tested - Comprehensive unit, integration, and contract tests
📊 Rich Logging - Structured logging for debugging and monitoring
🔄 Auto-Retry - Intelligent retry logic with exponential backoff
📖 MCP Compliant - Works with Claude Desktop and other MCP clients
Related MCP server: Harvest MCP Server
Node.js 18+
Harvest account with API access
MCP-compatible client (like Claude Desktop)
# Install globally
npm install -g @ianaleck/harvest-mcp-server
# Or install locally
npm install @ianaleck/harvest-mcp-serverGet your Harvest API credentials:
Go to Harvest → Settings → Developers → Personal Access Tokens
Create a new token
Note your Account ID (visible in URL or settings)
Configure your MCP client (e.g., Claude Desktop):
{
"mcpServers": {
"harvest": {
"command": "npx",
"args": ["-y", "@ianaleck/harvest-mcp-server"],
"env": {
"HARVEST_ACCESS_TOKEN": "your_harvest_personal_access_token",
"HARVEST_ACCOUNT_ID": "your_harvest_account_id"
}
}
}
}Start using with Claude!
Once connected, you can ask Claude to help with:
"Show me all my time entries for this week"
"Start a timer for the 'Development' task on the 'Website Project'"
"How many hours did I work on Project X last month?"
"List all active projects for client Acme Corp"
"Create a new project called 'Mobile App' for client TechStart"
"Show me project budget vs actual time spent"
"Who are all the users in our Harvest account?"
"Show me John's time entries for last week"
"Generate an expense report for Q4"
"Show me all unpaid invoices"
"What's our total billable hours this month?"
get_company - Get company information and settings
list_time_entries - List time entries with filtering
get_time_entry - Get specific time entry details
create_time_entry - Create new time entry
update_time_entry - Update existing time entry
delete_time_entry - Delete time entry
start_timer - Start a timer for a task
stop_timer - Stop running timer
restart_timer - Restart a previous time entry
list_projects - List all projects with filtering
get_project - Get specific project details
create_project - Create new project
update_project - Update project details
delete_project - Delete project
list_project_task_assignments - List task assignments for project
create_project_task_assignment - Assign task to project
update_project_task_assignment - Update task assignment
delete_project_task_assignment - Remove task assignment
list_tasks - List all tasks
get_task - Get specific task details
create_task - Create new task
update_task - Update task details
delete_task - Delete task
list_clients - List all clients
get_client - Get specific client details
create_client - Create new client
update_client - Update client details
delete_client - Delete client
list_users - List all users in account
get_user - Get specific user details
get_current_user - Get current authenticated user
create_user - Create new user
update_user - Update user details
delete_user - Delete user
list_expenses - List expenses with filtering
get_expense - Get specific expense details
create_expense - Create new expense
update_expense - Update expense details
delete_expense - Delete expense
list_expense_categories - List all expense categories
list_invoices - List invoices with filtering
get_invoice - Get specific invoice details
create_invoice - Create new invoice
update_invoice - Update invoice details
delete_invoice - Delete invoice
list_estimates - List estimates with filtering
get_estimate - Get specific estimate details
create_estimate - Create new estimate
update_estimate - Update estimate details
delete_estimate - Delete estimate
get_time_report - Generate time reports with filtering
get_expense_report - Generate expense reports
get_project_budget_report - Get project budget analysis
get_uninvoiced_report - Get uninvoiced time and expenses
git clone https://github.com/ianaleck/harvest-mcp-server.git
cd harvest-mcp-server
npm installcp .env.example .env
# Edit .env with your Harvest API credentials# Run all tests
npm test
# Run with coverage
npm run test:coverage
# Run specific test suites
npm run test:unit
npm run test:integration
npm run test:contract# Build for production
npm run build
# Start development server
npm run devThis server requires a Harvest account with API access. Users must comply with:
Harvest API Rate Limits (100 requests per 15 seconds)
We welcome contributions! Please see our Contributing Guidelines for details.
Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Make your changes with tests
Ensure all tests pass (npm test)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request
This project is licensed under the MIT License - see the LICENSE file for details.
Harvest for providing an excellent time tracking API
Model Context Protocol team for the MCP specification
Anthropic for Claude and the MCP SDK
🐛 Bug Reports: GitHub Issues
💡 Feature Requests: GitHub Discussions
📖 Documentation: MCP Documentation
Made with ❤️ for the MCP community
⭐ Star this project if you find it useful!
Create a new client for project management and billing. Requires client name and supports address and currency configuration.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Client name (required) | |
| address | No | Client address | |
| currency | No | 3-letter ISO currency code (e.g., USD, EUR) | |
| is_active | No | Whether the client is active |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden but only states creation and parameter support. Missing details on side effects, permissions, error handling, or idempotency. Minimal disclosure beyond the obvious.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, every word adds value. No redundancy, front-loaded with action and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple create tool, covers basics: purpose, required, optional fields. However, lacks description of return value (no output schema), uniqueness constraints, or outcome on success/failure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All parameters have schema descriptions (100% coverage), so baseline is 3. The description confirms required vs optional but adds no new semantics like dependencies or examples.
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 'client', with context 'for project management and billing'. It specifies required and optional parameters, distinguishing it from sibling tools like create_estimate or create_project.
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 vs alternatives like update_client or other create tools. An explicit statement about when not to use it or mention of update_client would improve this.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new estimate for a client with optional line items and terms. Supports custom pricing, taxes, and discounts.
| Name | Required | Description | Default |
|---|---|---|---|
| tax | No | Tax percentage (0-100) | |
| tax2 | No | Second tax percentage (0-100) | |
| notes | No | Estimate notes or description | |
| subject | No | Estimate subject line | |
| currency | No | 3-letter ISO currency code (e.g., USD, EUR) | |
| discount | No | Discount percentage (0-100) | |
| client_id | Yes | The client ID to create the estimate for (required) | |
| issue_date | No | Estimate issue date (YYYY-MM-DD) | |
| purchase_order | No | Client purchase order number |
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 does not disclose behavioral traits such as side effects, permissions, or response format. The description is generic.
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 (2 sentences) and front-loaded. However, it includes inaccurate information about line items and terms, which compromises 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?
Given 9 parameters and no annotations or output schema, the description is minimally complete. It covers client, items, pricing, but misses behavioral context and the line items discrepancy reduces 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?
Schema coverage is 100%, so baseline is 3. However, the description mentions 'optional line items and terms' which are not present in the input schema, creating a misleading expectation. This reduces the 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 estimate for a client' with specific verb and resource, and mentions optional features. It distinguishes from sibling tools like update_estimate, delete_estimate, 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?
Usage guidelines are implied but not explicit. The description says when to use (to create an estimate) but offers no when-not-to-use or alternatives (e.g., create_invoice).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new expense entry for a project with category and cost details. Supports receipt attachment and billable status.
| Name | Required | Description | Default |
|---|---|---|---|
| notes | No | Notes or description for the expense | |
| units | No | Number of units for unit-based expenses | |
| user_id | No | The user ID who incurred the expense | |
| billable | No | Whether the expense is billable to the client | |
| project_id | Yes | The project ID to associate the expense with (required) | |
| spent_date | Yes | Date the expense was incurred (YYYY-MM-DD) (required) | |
| total_cost | Yes | Total cost of the expense (required) | |
| expense_category_id | Yes | The expense category ID (required) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose all behavioral traits. It fails to mention whether permissions are needed, side effects, or what happens on duplicate entries. It also misleadingly states 'supports receipt attachment' when no such parameter exists, reducing transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is fairly concise, but it includes a misleading claim about receipt attachment. It front-loads the core action but sacrifices accuracy for brevity, resulting in moderate 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 complex input schema (8 parameters, 4 required) and no output schema/annotations, the description provides minimal context beyond the schema itself. It doesn't explain the return value, error handling, or constraints like uniqueness, leaving gaps for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides detailed descriptions for all 8 parameters (100% coverage). The tool description adds no new semantic value beyond mentioning 'receipt attachment' (not in schema) and 'billable status' (already described). This introduces confusion rather than clarity.
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 creates an expense entry for a project with category and cost details, distinguishing it from sibling tools like create_time_entry or create_invoice. However, it claims support for receipt attachment, which is not reflected in the input schema, causing slight ambiguity.
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 (creating an expense entry) but provides no explicit guidance on when not to use or alternatives among siblings like update_expense or list_expenses. The context is clear but lacks exclusions or comparative notes.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new invoice for a client with optional line items and billing details. Supports custom terms, taxes, and payment configurations.
| Name | Required | Description | Default |
|---|---|---|---|
| tax | No | Tax percentage (0-100) | |
| tax2 | No | Second tax percentage (0-100) | |
| notes | No | Invoice notes or description | |
| subject | No | Invoice subject line | |
| currency | No | 3-letter ISO currency code (e.g., USD, EUR) | |
| discount | No | Discount percentage (0-100) | |
| due_date | No | Invoice due date (YYYY-MM-DD) | |
| client_id | Yes | The client ID to invoice (required) | |
| issue_date | No | Invoice issue date (YYYY-MM-DD) | |
| payment_term | No | Payment terms (e.g., "Net 30") | |
| purchase_order | No | Client purchase order number |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fails to disclose behavioral traits such as what the tool returns, whether it is idempotent, or side effects. The claim 'optional line items' is unsupported by the schema, undermining 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 at two sentences, with the main action front-loaded. However, the inaccuracy regarding line items wastes space and could confuse, preventing a perfect score.
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 11 parameters and no output schema, the description should clarify return value and behavior. It omits key details like only client_id is required, and the mention of line items indicates missing schema coverage, making 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 coverage is 100%, so parameters are already well-documented. The description adds little new semantic value beyond repeating 'custom terms, taxes, and payment configurations' which are already in schema descriptions. The misleading 'line items' mention slightly detracts.
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 creates an invoice for a client, distinguishing it from update_invoice and other related tools. However, the mention of 'optional line items' is misleading as the schema does not include a line items parameter, which slightly reduces clarity.
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 create_estimate or update_invoice. The description lists features but does not explain context, exclusions, or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new project for a client. Requires project name and client ID. Supports extensive configuration including budget settings, billing preferences, and project timeline.
| Name | Required | Description | Default |
|---|---|---|---|
| fee | No | Fixed fee amount | |
| code | No | Project code for reference | |
| name | Yes | Project name (required) | |
| notes | No | Project notes | |
| budget | No | Project budget amount | |
| bill_by | No | How to bill for this project | |
| ends_on | No | Project end date (YYYY-MM-DD) | |
| budget_by | No | How budget is calculated | |
| client_id | Yes | The client ID this project belongs to (required) | |
| is_active | No | Whether the project is active | |
| starts_on | No | Project start date (YYYY-MM-DD) | |
| cost_budget | No | Cost budget for the project | |
| hourly_rate | No | Default hourly rate for the project | |
| is_billable | No | Whether the project is billable | |
| is_fixed_fee | No | Whether the project uses fixed fee billing | |
| budget_is_monthly | No | Whether budget resets monthly | |
| show_budget_to_all | No | Show budget information to all team members | |
| notify_when_over_budget | No | Send notifications when over budget | |
| cost_budget_include_expenses | No | Include expenses in cost budget calculations | |
| over_budget_notification_percentage | No | Percentage threshold for budget notifications |
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 discloses that the tool creates a project (a write operation) and supports extensive configuration. However, it lacks details on side effects, authentication needs, or error handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loads the core action and requirements, and includes no filler. 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?
For a tool with 20 parameters and no output schema, the description adequately summarizes the tool's capabilities. It covers the main functional areas but lacks mention of return values or potential side effects. Given the complexity, it is fairly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds value by grouping parameters into 'budget settings, billing preferences, and project timeline,' providing a higher-level understanding beyond individual 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?
The description clearly states 'Create a new project for a client' with a specific verb and resource. It distinguishes itself from sibling tools like create_client, create_estimate, etc., all of which target different resources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly requires 'project name and client ID' as prerequisites. While it doesn't mention when not to use or provide alternatives, the tool's purpose is clear among many create tools, and the requirement hints are helpful.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Assign a task to a project, making it available for time tracking on that project. Allows setting project-specific rates and budgets.
| Name | Required | Description | Default |
|---|---|---|---|
| budget | No | Budget allocation for this task | |
| task_id | Yes | The task ID to assign (required) | |
| billable | No | Whether time tracked on this task is billable | |
| is_active | No | Whether this assignment is active | |
| project_id | Yes | The project ID to assign the task to (required) | |
| hourly_rate | No | Hourly rate for this task on this project |
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 discloses the basic effect (making task available for time tracking) but does not cover important behaviors: idempotency, error handling, authorization requirements, or what happens if the assignment already exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long with no wasted words. It is front-loaded with the core action and efficiently adds extra detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of annotations and output schema, the description adequately covers purpose and key parameters but omits behavioral details like idempotency, error scenarios, and prerequisites. It is sufficient for basic understanding but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with good descriptions for each parameter. The description adds context that the 'hourly_rate' and 'budget' are project-specific, but this adds only minor value beyond the 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?
The description clearly states the action ('Assign a task to a project'), the outcome ('making it available for time tracking'), and the additional capability ('Allows setting project-specific rates and budgets'). It distinguishes from siblings like 'create_task' (which creates a new task) and 'update_project_task_assignment' (modifies an existing one).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you need to link a task to a project for time tracking with optional custom rates/budgets, but it does not explicitly state when NOT to use it (e.g., if the task is already assigned) or mention alternatives like 'create_task' or 'update_project_task_assignment'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new task that can be assigned to projects for time tracking. Tasks define what type of work is being performed.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Task name (required) | |
| is_active | No | Whether the task is active | |
| is_default | No | Whether this is a default task | |
| billable_by_default | No | Whether this task is billable by default | |
| default_hourly_rate | No | Default hourly rate for this task |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden but only states 'Create a new task.' It fails to disclose behavioral traits like side effects, permissions, or whether the created task is returned. The definitional second sentence adds no behavioral insight.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no wasted words. The first sentence is action-oriented, the second provides context. Could be slightly more concise but effective.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's 5 parameters and no output schema, the description lacks essential context such as return value (e.g., does it return the created task?), prerequisites, or typical use cases. It is too sparse for an agent to fully understand the tool's 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?
All 5 parameters are described in the input schema (100% coverage), so the description adds no parameter-level information. The general statement 'Tasks define what type of work is being performed' does not supplement schema details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a new task' with a specific verb and resource. It adds context that tasks are assignable to projects for time tracking, distinguishing it from other create tools like create_client or create_project.
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., create_project_task_assignment for assigning tasks). The description implies a straightforward creation use case but offers no exclusions or conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new time entry. Requires project_id, task_id, and spent_date. Must provide either hours OR both started_time and ended_time.
| Name | Required | Description | Default |
|---|---|---|---|
| hours | No | Decimal hours (e.g., 0.5 = 30min, 1.25 = 1h15m) | |
| notes | No | Notes for the time entry | |
| task_id | Yes | The task ID to log time against | |
| ended_time | No | End time in HH:MM format (24-hour) | |
| project_id | Yes | The project ID to log time against | |
| spent_date | Yes | The date the time was spent (YYYY-MM-DD) | |
| started_time | No | Start time in HH:MM format (24-hour) | |
| external_reference | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility. It discloses that the tool creates a new record and outlines required fields. However, it does not mention any destructive behavior, authentication needs, or potential side effects (e.g., duplicate handling). The information is 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?
Two sentences, front-loaded with purpose, then constraints. No extraneous information. Every word is meaningful.
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 8 parameters including a nested object, no output schema. The description covers core logic (required fields and time/hours constraint). It does not explain the external_reference object or notes, but the schema covers those. For a creation tool, it is contextually 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?
Input schema already provides detailed descriptions for 7 out of 8 parameters (88% coverage). The description adds the critical OR constraint between hours and started_time/ended_time, which is not captured in the schema. This provides additional guidance 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 action (Create) and resource (a time entry), specifying required fields (project_id, task_id, spent_date). This distinguishes it from sibling tools like start_timer or update_time_entry.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states the OR constraint for hours versus started_time/ended_time, providing a key decision rule. It implies that if you have hours you don't need time ranges, and vice versa. Lacks explicit exclusions or alternative tool suggestions, but the constraint is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new user with specified roles and permissions. Supports team member management and access control.
| Name | Required | Description | Default |
|---|---|---|---|
| Yes | Email address (required) | ||
| is_admin | No | Grant admin privileges | |
| timezone | No | User timezone | |
| cost_rate | No | Cost rate for internal calculations | |
| is_active | No | User active status | |
| last_name | Yes | Last name (required) | |
| telephone | No | Phone number | |
| first_name | Yes | First name (required) | |
| can_see_rates | No | Allow viewing of billing rates | |
| is_contractor | No | Mark as contractor | |
| weekly_capacity | No | Weekly capacity in seconds | |
| is_project_manager | No | Grant project manager role | |
| can_create_invoices | No | Allow invoice creation | |
| can_create_projects | No | Allow project creation | |
| default_hourly_rate | No | Default hourly rate | |
| has_access_to_all_future_projects | No | Grant access to all future projects |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description only states it creates a user but does not disclose behavioral traits such as whether it sends invitations, requires admin privileges, or what happens on duplicate email. Basic creation action is noted, but not enough for a full picture.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, 18 words, with the primary action in the first sentence and supplementary context in the second. No wasted words, and the structure 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 tool has 16 parameters and is a creation action, the description is too brief. It lacks information on return value, error handling, permissions required, or any side effects. The absence of output schema and annotations increases the need for completeness, which is not met.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the schema clearly defines each parameter. The description adds 'roles and permissions' context but does not enhance understanding beyond the schema. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool creates a new user with roles and permissions, differentiating it from sibling tools like create_client or create_project. The verb 'create' and resource 'user' 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 explicit guidance on when to use this tool versus updating an existing user with update_user, nor any prerequisites or exclusions. The description implies team management but lacks clear usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete (archive) a client. This action archives the client rather than permanently deleting it, preserving historical project and billing data.
| Name | Required | Description | Default |
|---|---|---|---|
| client_id | Yes | The ID of the client to delete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full transparency burden. It discloses that the client is archived, not permanently deleted, and that historical project and billing data are preserved. This provides important behavioral context, though additional details (e.g., permissions, reversibility) are absent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the action and key behavior. Every part is essential, with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete/archive tool with one parameter and no output schema, the description fully covers the necessary context: what the tool does (archive), what happens to data (preserved), and the parameter needed. No additional information is 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 coverage is 100% for the single parameter 'client_id', so the baseline is 3. The description adds no additional semantic information beyond what the schema provides, as both state the parameter's purpose.
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 ('Delete (archive) a client') and the specific resource ('client'), and distinguishes from other deletion tools by clarifying that it archives rather than permanently deletes, preserving historical data.
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 archival behavior and why historical data is preserved, giving implicit guidance on when to use this tool (when archival is desired). It lacks explicit when-not-to-use or alternative tool references, but the context is clear enough for agent decision-making.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete an estimate permanently. This action cannot be undone.
| Name | Required | Description | Default |
|---|---|---|---|
| estimate_id | Yes | The ID of the estimate to delete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of disclosing behavior. It correctly states the irreversibility, but lacks details about permissions, cascading effects, or return behavior. For a simple delete, this is adequate but not thorough.
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, just two sentences with no wasted words. Essential information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (one parameter, no output schema), the description is mostly complete. It covers the action and its irreversibility, though it could mention the expected return value (e.g., success confirmation).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description adds no extra meaning beyond what the schema already provides for the single parameter 'estimate_id'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it deletes an estimate permanently. The verb 'delete' and resource 'estimate' are specific and distinguish it from sibling tools like 'update_estimate' or 'create_estimate'.
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?
Implicitly warns that the action cannot be undone, suggesting careful use, but does not provide explicit guidance on when to use this tool versus alternatives (e.g., updating to a cancelled state) or any prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete an expense permanently. This action cannot be undone.
| Name | Required | Description | Default |
|---|---|---|---|
| expense_id | Yes | The ID of the expense to delete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that the action is permanent and irreversible, which is key. However, it lacks details on side effects, return values, or error conditions common for destructive operations.
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 consists of two concise sentences, front-loading the core action and consequence. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete operation with one well-described parameter, the description is almost complete. It covers the irreversibility, though it could mention what happens after deletion (e.g., return type or success indication).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with a description for expense_id. The tool description does not add any parameter information beyond what is already in the schema. Baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'delete' and the resource 'expense', and adds 'permanently' and 'cannot be undone', which distinguishes it from other potentially reversible operations. It is specific and 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 does not provide any guidance on when to use this tool versus alternatives. There are many sibling delete tools, but the description offers no context about prerequisites or selection criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete an invoice permanently. This action cannot be undone and will remove all associated billing data.
| Name | Required | Description | Default |
|---|---|---|---|
| invoice_id | Yes | The ID of the invoice to delete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden. It explicitly states the action is permanent and irreversible, and reveals the scope ('all associated billing data'). This provides strong transparency for a destructive operation, though it lacks details on authentication or error handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with zero waste. The first sentence states the primary action, and the second adds critical consequence. It is front-loaded and every word adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete operation with one required parameter and no output schema, the description covers the main behavior and side effects. It could be improved by mentioning expected response (e.g., success/failure) but is mostly complete given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the parameter 'invoice_id' is fully documented in the schema. The description adds no additional meaning beyond what the schema states, earning a baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Delete' and the resource 'invoice', and emphasizes permanence and scope ('all associated billing data'). This distinguishes it from sibling delete tools (e.g., delete_client, delete_estimate) by specifically naming the 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?
The description implies when to use (when you want to permanently remove an invoice) but provides no explicit guidance on when not to use or alternatives. Siblings exist for other entities, but no comparative context is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete (archive) a project. This action archives the project rather than permanently deleting it, preserving historical data while making it inactive.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | The ID of the project to delete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears full burden. It discloses the key behavior (archive vs. permanent delete) but lacks details on permissions, reversibility, or side effects. Adequate but incomplete.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no redundancy. The key information is front-loaded and every word adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and no output schema, the description covers the essential behavioral nuance. Missing return value info but acceptable given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single parameter, so the baseline is 3. The description adds no additional information beyond the schema's parameter 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 (delete/archive) and resource (project), and distinguishes it from permanent deletion by specifying the archival nature. It is specific and 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 archiving projects but does not explicitly state when to use this tool versus alternatives (e.g., update_project for deactivation, other delete tools). No when-not or exclusion criteria are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove a task assignment from a project, making the task unavailable for time tracking on that project.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | The project ID (required) | |
| task_assignment_id | Yes | The task assignment ID to delete (required) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It mentions the effect (makes task unavailable for time tracking), but fails to state that the operation is irreversible, whether it requires special permissions, or what happens if the assignment has time entries. The word 'Remove' implies deletion, but more details are needed for full transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that efficiently communicates the tool's purpose and effect without unnecessary words. It is front-loaded with the key action and provides immediate value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 parameters, no output schema), the description provides the core purpose but lacks information on return values, success indicators, or error conditions. While functionally adequate, it leaves some contextual gaps for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already describes both parameters thoroughly (e.g., 'The project ID (required)'), achieving 100% coverage. The description adds no additional parameter semantics, such as constraints or sources for the IDs. Baseline is 3 per rubric.
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 action ('Remove a task assignment') and its consequence ('making the task unavailable for time tracking'), using a specific verb and resource. It distinguishes from siblings like delete_task (deletes entire task) by focusing on the assignment removal.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you need to remove a specific task assignment from a project, but it does not provide explicit guidance on when to use this vs. alternative sibling tools (e.g., delete_task, update_project_task_assignment). No exclusions or references to alternatives are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete (archive) a task. This action archives the task rather than permanently deleting it, preserving historical data while making it inactive.
| Name | Required | Description | Default |
|---|---|---|---|
| task_id | Yes | The ID of the task to delete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It clarifies that the action archives rather than permanently deletes, which is a key behavioral trait. However, it omits details like required permissions or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, consisting of two sentences that front-load the core action. Every sentence adds value with no redundant or 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?
For a simple tool with one parameter and no output schema, the description adequately explains the archival behavior. It could mention the response format or error conditions, but the current level is sufficient for basic usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully describes the only parameter (task_id) with a description. The tool description does not add any additional meaning beyond what the schema provides, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool deletes (archives) a task, distinguishing it from other operations like create_task or list_tasks. The verb 'delete (archive)' and resource 'task' are specific and 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 mentions archival vs permanent deletion, implying a usage context but does not explicitly state when to use this tool over alternatives. No alternative tool for deleting tasks exists among siblings, so guidance on prerequisites or conditions is absent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a time entry permanently. This action cannot be undone.
| Name | Required | Description | Default |
|---|---|---|---|
| time_entry_id | Yes | The ID of the time entry to delete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries the burden. It discloses the irreversible nature but lacks details on side effects (e.g., impacts on linked entities) or 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?
Two concise sentences, perfectly front-loaded with essential information, no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete operation with one parameter, the description is fairly complete. It lacks error conditions or permissions but is acceptable for this simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the parameter description is clear. The tool description adds no extra 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 (delete), the resource (time entry), and the permanent consequence. It distinguishes from siblings like update_time_entry.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives, no prerequisites or when-not-to-use mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete (archive) a user. This action archives the user rather than permanently deleting them, preserving time tracking history.
| Name | Required | Description | Default |
|---|---|---|---|
| user_id | Yes | The ID of the user to delete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses the archiving behavior and preservation of time tracking history, which is valuable. However, it omits other behavioral details like required permissions, side effects, or reversibility.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, concise and front-loaded. Every sentence provides value: the first states the action, the second clarifies the nuance. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and no annotations, the description is fairly complete. It explains the key behavioral nuance. However, it could mention what happens to related data beyond time tracking, but overall adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the description adds no extra meaning beyond the schema's description of 'user_id'. The baseline of 3 applies as the description does not compensate for any gaps.
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 'delete (archive) a user' and distinguishes it from permanent deletion by specifying archiving behavior and preservation of time tracking history. This is specific and differentiates from sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use (when archiving is acceptable) but does not explicitly state when not to use or provide alternatives. The archiving nuance gives some guidance, but lacks explicit exclusions or comparisons to related tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve a specific client by its ID. Returns complete client details including contact information and billing configuration.
| Name | Required | Description | Default |
|---|---|---|---|
| client_id | Yes | The ID of the client to retrieve |
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 describes a read operation but does not disclose potential errors, authentication needs, or other behavioral traits beyond the return content. Adequate but could be more transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no superfluous words. The first sentence immediately states the purpose, making it efficient for an agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple retrieval tool with one parameter and no output schema, the description is sufficiently complete. It mentions what is returned (contact info, billing) and implies the operation is safe.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for the only parameter (client_id). The tool description adds no additional meaning; it simply uses the parameter name. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action ('Retrieve a specific client by its ID') and the resource. It also specifies what the return includes ('complete client details including contact information and billing configuration'), distinguishing it from sibling tools like list_clients.
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 implicitly suggests use when a single client's details are needed, but lacks explicit guidance on when not to use it or alternatives like list_clients or update_client.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve company information and settings for the authenticated account. Returns comprehensive company details including billing configuration, time tracking preferences, and enabled features.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavior. 'Retrieve' implies read-only operation, but it does not mention any authentication requirements, rate limits, or response structure beyond listing categories.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no unnecessary words, efficiently conveying the tool's purpose and scope.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters and no output schema, the description provides sufficient context by listing the categories of information returned. It is adequate for a simple retrieval tool, though it could mention if the response is a single object or array.
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 zero parameters with 100% coverage, so the description correctly adds value by explaining what information is returned (billing, time tracking, enabled features) 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 specifies the action ('retrieve') and the resource ('company information and settings for the authenticated account'), distinguishing it from sibling tools which deal with clients, tasks, 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?
The description does not provide explicit guidance on when to use this tool versus alternatives, nor does it mention prerequisites or exclusions. It is implied for retrieving company-level details, but no direct comparison to other get_* tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve the currently authenticated user's profile and permissions.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries burden. It states 'profile and permissions' but does not disclose return format, side effects, or authentication requirements beyond 'authenticated user'. Adequate but not detailed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with verb and object, 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?
For a 0-parameter tool with no output schema, description adequately conveys purpose and scope. Could specify that it returns the full user object for the authenticated user, but acceptable.
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 baseline 4. Description adds no param info beyond schema, but none needed.
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 specifies action 'Retrieve' and target 'currently authenticated user's profile and permissions'. Differentiates from sibling tools like get_user (which retrieves a specific user) and list_users.
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 vs alternatives, but the self-explanatory nature implies use for the current user. Lacks when-not or alternative mentions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve a specific estimate by ID with complete details including line items, terms, and client information.
| Name | Required | Description | Default |
|---|---|---|---|
| estimate_id | Yes | The ID of the estimate to retrieve |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It describes a read operation ('Retrieve') but does not disclose authorization needs, error handling, or rate limits. However, it adds context on returned data (line items, terms, client info), providing some transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of 15 words, efficiently conveying the core function without extraneous detail. Front-loaded with verb and resource, every word adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple retrieval tool with one parameter, the description adequately covers purpose and return content. No output schema exists, but the description's mention of included details compensates. It is complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with one parameter clearly described. The description adds 'by ID' but does not enrich parameter meaning beyond what the schema already provides. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Retrieve' and the resource 'estimate by ID', distinguishing it from list_estimates and other get tools. It specifies the scope 'by ID' and mentions what details are included, 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 does not explicitly state when to use this tool versus alternatives like list_estimates or other get tools. It implies usage for fetching a single estimate by ID, but lacks guidance on when not to use it or mention of alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve a specific expense by ID with complete details including receipts and billing information.
| Name | Required | Description | Default |
|---|---|---|---|
| expense_id | Yes | The ID of the expense to retrieve |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries the burden. It mentions returning 'complete details including receipts and billing information', implying a read-only operation. However, it does not explicitly state side effects or safety profile, which is acceptable for a simple get.
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?
A single, well-formed sentence that conveys all necessary information without filler. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema or annotations, the description is adequate for a simple retrieval tool. It tells the agent what it does and what data it returns. Minor gaps like return format are acceptable given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter expense_id is fully described in the schema ('The ID of the expense to retrieve'). The description adds no further semantics, so baseline 3 is appropriate given 100% coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Retrieve', the resource 'expense by ID', and the scope 'with complete details including receipts and billing information'. This distinguishes it from sibling tools like list_expenses.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or alternatives are provided. The usage is implicitly clear (when you need a single expense by ID), but explicit guidance versus list_expenses would improve it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate comprehensive expense reports with filtering by date range, users, clients, projects, and categories. Supports grouping and billing status filtering.
| Name | Required | Description | Default |
|---|---|---|---|
| to | Yes | End date for report (YYYY-MM-DD) (required) | |
| from | Yes | Start date for report (YYYY-MM-DD) (required) | |
| user_id | No | Filter by specific user ID | |
| billable | No | Filter by billable status | |
| group_by | No | Group report results by specified dimension | |
| client_id | No | Filter by specific client ID | |
| is_billed | No | Filter by billed status | |
| project_id | No | Filter by specific project ID | |
| updated_since | No | Filter by expenses updated since this timestamp | |
| expense_category_id | No | Filter by specific expense category ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose whether the report is read-only, what permissions are needed, or if it has side effects. It only states 'generate', which is ambiguous.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no wasted words; front-loaded with purpose and then details. Perfectly proportioned for a tool with many 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?
Given no output schema, the description could mention the expected return format or result limits. However, it covers all key features (filtering, grouping, billing status) and is fairly complete for a report 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 schema covers all parameters with descriptions (100% coverage). The description adds context by summarizing filtering dimensions and grouping, enhancing 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 it generates expense reports with filtering and grouping, distinguishing it from sibling report tools like get_time_report and get_uninvoiced_report.
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 use for expense reporting but does not explicitly state when to use this tool versus alternatives, nor does it mention prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve a specific invoice by ID with complete details including line items, payments, and billing information.
| Name | Required | Description | Default |
|---|---|---|---|
| invoice_id | Yes | The ID of the invoice to retrieve |
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 mentions included details (line items, payments, billing info) but does not address error handling, permissions, or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words, efficiently conveying the tool's action and scope.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple retrieval tool with one parameter and no output schema, the description covers the essential return scope (line items, payments, billing info) and is adequately complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (invoice_id described in schema). The description adds minimal additional meaning beyond that, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Retrieve' and the resource 'a specific invoice by ID', distinguishing it from sibling tools like list_invoices and other get_* tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when needing a single invoice by ID, but does not explicitly mention when not to use or alternatives like list_invoices for multiple invoices.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve a specific project by its ID. Returns complete project details including client information, budget settings, billing configuration, and project dates.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | The ID of the project to retrieve |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears full burden. It implies read-only behavior ('Retrieve'), but does not explicitly confirm safety, error handling (e.g., invalid ID), or any side effects. It does state the return content, adding some 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?
Two sentences: first defines action and key input, second summarizes return value. No extra words, front-loaded with purpose. Efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool with no output schema or annotations, the description covers the essential: what it does, what input it takes, and what it returns. It omits potential error cases (missing project) but is largely complete for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (one parameter with description). The description does not add meaning beyond the schema: both say retrieve by ID. Baseline 3 due to high coverage; no extra value provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the verb 'Retrieve' and specifies resource 'specific project by its ID', clearly distinguishing it from list_projects (which retrieves multiple) and other get_* tools. It also enumerates the categories of returned details (client info, budget, billing, dates).
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_projects or get_project_budget_report. No mention of prerequisites, required permissions, or scenarios where this is the right choice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate project budget reports showing spending vs budgets across projects. Helps track project profitability and budget utilization.
| Name | Required | Description | Default |
|---|---|---|---|
| client_id | No | Filter by specific client ID | |
| is_active | No | Filter by active projects only | |
| over_budget | No | Filter by projects that are over budget |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description should disclose behavioral traits. It only says 'generate', lacking information on read-only nature, permissions, or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two efficient sentences with no wasted words, but could be structured for better scannability.
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 does not explain return values, output format, or how the report is structured, which is essential for an agent to interpret results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear parameter descriptions. The description adds no additional meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description specifies the verb 'generate' and resource 'project budget reports' showing spending vs budgets, clearly distinguishing it from sibling report tools like get_expense_report and get_time_report.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions 'Helps track project profitability and budget utilization' but does not explicitly state when to use this tool over alternatives or provide any exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve a specific task by its ID. Returns complete task details including default billing settings and activity status.
| Name | Required | Description | Default |
|---|---|---|---|
| task_id | Yes | The ID of the task to retrieve |
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 describes the tool as retrieving data and returning details, which implies a read-only operation, but it does not explicitly state that it is safe, idempotent, or has no side effects. The description covers the basic behavior but lacks explicit safety or authorization information.
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 sentences that immediately state the purpose and the key contents of the response. No unnecessary words. It is well-structured and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity (1 parameter, no output schema), the description is fairly complete. It explains what the tool returns ('complete task details including default billing settings and activity status'), which is necessary since there is no output schema. It does not mention error handling or related tools, but overall it provides sufficient context for a simple retrieval 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?
Schema coverage is 100% with a description for 'task_id'. The tool description adds minimal meaning beyond the schema (just 'by its ID'). The schema already documents the parameter type and purpose, so the description does not significantly enhance understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Retrieve' and the resource 'a specific task by its ID', and specifies what the response includes ('complete task details including default billing settings and activity status'). It distinguishes from sibling tools like 'list_tasks' and 'create_task'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you need a specific task's details, but it does not explicitly state when to use this tool versus alternatives or any when-not-to-use conditions. No mention of prerequisites or context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve a specific time entry by its ID. Returns complete time entry details including project, task, user, and timing information.
| Name | Required | Description | Default |
|---|---|---|---|
| time_entry_id | Yes | The ID of the time entry to retrieve |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, description carries full burden. It states returns complete details but omits authentication, rate limits, or that it's read-only. Adequate for a simple read operation, but 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?
Two sentences, front-loaded with key action and return description. No unnecessary words; highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter tool with no output schema, description covers what is returned. Could mention error conditions or if full details means nested objects, but 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?
Input schema has 100% coverage with description 'The ID of the time entry to retrieve'. Description adds no additional meaning beyond that, so baseline score applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Retrieve a specific time entry by its ID' with verb and resource, and lists return contents including project, task, user, and timing. Differentiates from siblings like list_time_entries.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or alternatives are mentioned; usage is implied as 'when you need details of a specific time entry'. Lacks guidance compared to search or list alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate comprehensive time tracking reports with filtering by date range, users, clients, projects, and tasks. Supports grouping and billable status filtering.
| Name | Required | Description | Default |
|---|---|---|---|
| to | Yes | End date for report (YYYY-MM-DD) (required) | |
| from | Yes | Start date for report (YYYY-MM-DD) (required) | |
| task_id | No | Filter by specific task ID | |
| user_id | No | Filter by specific user ID | |
| billable | No | Filter by billable status | |
| group_by | No | Group report results by specified dimension | |
| client_id | No | Filter by specific client ID | |
| is_billed | No | Filter by billed status | |
| is_running | No | Filter by running timer status | |
| project_id | No | Filter by specific project ID | |
| updated_since | No | Filter by entries updated since this timestamp |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states 'Generate' without clarifying read-only nature, side effects, permissions, or output structure (e.g., pagination, aggregation). This is a significant gap for a report 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?
Single sentence with 20 words, efficiently listing key features. It is not overly verbose, though it lacks structure (e.g., bullet points) and could be more scannable.
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 11 parameters and no output schema. The description does not explain return format, pagination, data limits, or edge cases. Given the complexity, this description is insufficient for an agent to fully understand tool 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?
Schema coverage is 100%, so baseline is 3. The description summarizes main filter dimensions (date, users, clients, etc.) and grouping/billable filtering, but does not add meaning beyond the schema for parameters like 'is_billed' or 'updated_since'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Generate') and resource ('comprehensive time tracking reports'), and lists filtering and grouping capabilities. It implicitly distinguishes from siblings like 'get_time_entry' (single entry) and other report tools, 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 on when to use this tool versus alternatives such as 'get_expense_report' or 'get_project_budget_report'. The description does not provide when-not-to-use or prerequisite conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate reports of uninvoiced time and expenses within a date range. Essential for identifying billable work that hasn't been invoiced yet.
| Name | Required | Description | Default |
|---|---|---|---|
| to | Yes | End date for report (YYYY-MM-DD) (required) | |
| from | Yes | Start date for report (YYYY-MM-DD) (required) | |
| client_id | No | Filter by specific client ID | |
| project_id | No | Filter by specific project ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It does not disclose whether the operation is read-only, any authorization requirements, rate limits, or potential side effects. While the name and context suggest a read operation, the lack of explicit behavioral cues reduces 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 consists of two concise sentences that front-load the action and purpose without any fluff or redundant information. Every sentence serves a clear function: stating the functionality and indicating its business value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of output schema and annotations, the description is incomplete. It does not explain the return format, whether results are paginated, or how to handle potential errors. For a report tool, this information is important for correct invocation and interpretation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so each parameter is already documented in the input schema. The tool description adds minimal value beyond the schema, only restating the date range context. For a high-coverage schema, baseline is 3, and the description does not significantly enhance parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool generates reports of uninvoiced time and expenses within a date range, using a specific verb ('generate') and resource ('reports of uninvoiced time and expenses'). It distinguishes from sibling report tools like 'get_time_report' and 'get_expense_report' by focusing on uninvoiced items, and adds business context about identifying billable work.
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 identifying uninvoiced work but does not explicitly state when to use this tool over alternatives like 'get_time_report' or 'get_expense_report'. There is no mention of when not to use it or any prerequisite conditions, leaving room for ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve a specific user by ID. Returns complete user profile including roles, permissions, and billing rates.
| Name | Required | Description | Default |
|---|---|---|---|
| user_id | Yes | The ID of the user to retrieve |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Indicates read-only operation with 'retrieve' and 'returns', but no further details on permissions, rate limits, or error handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, no superfluous words. Purpose and return information are 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 simplicity of the tool (one parameter, no output schema), the description adequately covers purpose and return value. Could benefit from mentioning behavior when user not found, but not essential.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a single parameter described. The description reinforces 'by ID' but does not add meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Retrieve a specific user by ID', specifying the verb and resource. Distinguishes from sibling 'list_users' by focusing on a single user. Also describes what is returned (roles, permissions, billing rates), adding specificity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies usage for retrieving a specific user by ID, but does not explicitly state when to use this over alternatives like 'list_users' or provide conditions for use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve a list of clients with optional filtering by active status and updated date. Returns paginated results with client details including billing information.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number for pagination | |
| per_page | No | Number of clients per page (max 2000) | |
| is_active | No | Filter by active status | |
| updated_since | No | Filter by clients updated since this timestamp |
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 mentions 'retrieve' implying read-only but does not explicitly state it is non-destructive or discuss side effects, auth requirements, or rate limits. The mention of pagination is helpful.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that efficiently communicates purpose, filtering, pagination, and return content without extraneous words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 4-parameter list tool with no output schema, the description adequately covers filtering criteria, pagination, and return contents (including billing info). It could mention default pagination or ordering, but is reasonably complete for the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 100% description coverage for all 4 parameters. The description adds context that filtering is optional and results are paginated, but does not provide significant new meaning beyond what the schema already specifies. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves a list of clients with optional filtering and returns paginated results with client details and billing information. It distinguishes from sibling tools like get_client (single) and create_client (create).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for listing clients with filtering and pagination, but does not provide explicit guidance on when to use this tool versus other list tools (e.g., list_estimates) or mention any exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve estimates with filtering by client, state, and date ranges. Returns paginated results with estimate details.
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | End date for date range filter (YYYY-MM-DD) | |
| from | No | Start date for date range filter (YYYY-MM-DD) | |
| page | No | Page number for pagination | |
| state | No | Filter by estimate state | |
| per_page | No | Number of estimates per page (max 2000) | |
| client_id | No | Filter by client ID | |
| updated_since | No | Filter by estimates updated since this timestamp |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses pagination and filtering, but lacks details on rate limits, data freshness, or behavior with no results. With no annotations, the description carries full burden but only provides basic information.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences that are concise and front-loaded with purpose and key features. 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 no output schema, the description could elaborate on 'estimate details', but it is adequately informative for a list tool. It covers filtering and pagination, though some aspects like sorting are omitted.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already explains parameters. The description summarizes filtering options but doesn't add deeper semantics beyond what the schema provides, earning a baseline 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 'Retrieve estimates' and specifies filtering and pagination, making it distinct from tools like get_estimate or list_invoices.
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 like list_invoices or list_expenses. While filtering options are mentioned, context about appropriate use cases is missing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve available expense categories for expense classification and organization.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number for pagination | |
| per_page | No | Number of categories per page (max 2000) | |
| is_active | No | Filter by active status | |
| updated_since | No | Filter by categories updated since this timestamp |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description does not disclose any behavioral traits beyond retrieving. With no annotations, the description should mention pagination, filtering, or defaults, but it does not. The schema provides some detail, but the description adds no further transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no unnecessary words. It is front-loaded and concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and 4 optional parameters, the description is too minimal. It does not hint at return format, sorting, defaults, or error conditions. For a list tool, more context is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds no additional meaning beyond the schema. Parameters are documented in the schema, but the description does not elaborate on their purpose or 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 the verb 'Retrieve' and the resource 'expense categories', making the purpose clear. It distinguishes from siblings like 'list_expenses' which lists expense entries, not categories. However, the term 'available' is slightly vague.
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?
There is no guidance on when to use this tool versus alternatives, such as filtering or when to use 'get_expense' instead. No context is provided for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve expenses with filtering by user, client, project, billing status, and date ranges. Returns paginated results with expense details.
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | End date for date range filter (YYYY-MM-DD) | |
| from | No | Start date for date range filter (YYYY-MM-DD) | |
| page | No | Page number for pagination | |
| user_id | No | Filter by user ID | |
| per_page | No | Number of expenses per page (max 2000) | |
| client_id | No | Filter by client ID | |
| is_billed | No | Filter by billing status | |
| is_closed | No | Filter by closed status | |
| project_id | No | Filter by project ID | |
| updated_since | No | Filter by expenses updated since this timestamp |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It only discloses pagination behavior but fails to mention other important traits such as default sorting, result limits, or whether the operation is read-only (implicit but not stated).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no filler, front-loading the action and filtering options concisely. Every word 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 10 parameters and no output schema or annotations, the description covers the basic filtering and pagination but lacks details on parameter combination logic, default values, error handling, and output fields. 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?
Schema coverage is 100% with each parameter documented. The description reiterates filtering categories but adds no new meaning beyond the schema, so baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'retrieve expenses' and lists multiple filtering dimensions (user, client, project, billing status, date ranges), distinguishing it from sibling tools like get_expense (single expense) or create_expense.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for listing and filtering expenses but does not explicitly state when to use this tool over siblings like get_expense for a single expense or other report tools. No exclusions or alternatives are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve invoices with optional filtering by client, project, state, and date ranges. Returns paginated results with complete invoice details.
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | End date for date range filter (YYYY-MM-DD) | |
| from | No | Start date for date range filter (YYYY-MM-DD) | |
| page | No | Page number for pagination | |
| state | No | Filter by invoice state | |
| per_page | No | Number of invoices per page (max 2000) | |
| client_id | No | Filter by client ID | |
| project_id | No | Filter by project ID | |
| updated_since | No | Filter by invoices updated since this timestamp |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so description must carry behavioral burden. It mentions paginated results and complete details but omits ordering, side effects, or authentication needs.
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?
One sentence, 18 words, efficiently conveys main action and key features without 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?
Adequate for a list tool with full schema coverage; could mention default sorting or output structure given no output schema, but not critical.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. Description summarizes filter types and pagination but adds minimal new semantics beyond what schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Retrieve invoices' with specific filtering options and pagination, distinguishing it from sibling tools like get_invoice (single) and create_invoice.
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 use for filtering and pagination but lacks explicit when-to-use vs alternatives or exclusions, e.g., compared to get_invoice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve a list of projects with optional filtering by client, active status, and updated date. Returns paginated results with comprehensive project details.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number for pagination | |
| per_page | No | Number of projects per page (max 2000) | |
| client_id | No | Filter by client ID | |
| is_active | No | Filter by active status | |
| updated_since | No | Filter by projects updated since this timestamp |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses pagination behavior and mentions 'comprehensive project details', but does not state that the operation is read-only, nor does it cover auth requirements or rate limits. This is adequate for a list tool but lacks explicit safety 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 a single concise sentence that front-loads the primary purpose. Every word contributes meaning; no fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description adequately covers the basic purpose, filtering, and pagination. However, it does not describe the response structure or field details, which would be helpful for a list tool with 'comprehensive project details'.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds value by grouping the filter parameters into three categories (client, active status, updated date), which helps the agent understand the combined filtering intent beyond individual parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('retrieve') and resource ('list of projects'), clearly distinguishing it from sibling tools like list_clients or list_invoices. It also mentions optional filtering and pagination, leaving no ambiguity about the tool's function.
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 by stating 'optional filtering' and 'paginated results', but does not explicitly state when to use this tool vs alternatives (e.g., get_project for a single project). No when-not or alternative tool names are provided, leaving the decision partly implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve task assignments for a specific project. Shows which tasks are available for time tracking on the project and their specific settings.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number for pagination | |
| per_page | No | Number of assignments per page (max 2000) | |
| is_active | No | Filter by active status | |
| project_id | Yes | The project ID to get task assignments for (required) | |
| updated_since | No | Filter by assignments updated since this timestamp |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries the burden. 'Retrieve' suggests read-only operation, but no explicit statement of non-destructiveness, idempotency, or side effects. Description adds basic behavioral info but lacks safety guarantees or rate limit notes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, concise and front-loaded. First sentence states purpose, second adds relevant context. No extraneous 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?
No output schema or annotations. Description explains what the tool returns conceptually (task assignments with settings) but lacks details on pagination behavior, response structure, sorting, or default values. Adequate for a simple list tool but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with descriptions for each parameter. The tool description adds context ('available for time tracking on the project and their specific settings') but does not provide additional semantic value beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Retrieve task assignments for a specific project' and adds context about time tracking and settings. It distinguishes from sibling tools like list_tasks (which lists tasks, not assignments) and get_project (project details). Verb 'Retrieve' with resource 'task assignments for a specific project' is specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool vs alternatives. Description implies use when needing assignments for a project, but doesn't mention when not to use it or compare with siblings like create_project_task_assignment or update. Context signals show there are sibling tools for CRUD on assignments, but no differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve a list of tasks with optional filtering. Tasks are the building blocks for time tracking and can be assigned to projects.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number for pagination | |
| per_page | No | Number of tasks per page (max 2000) | |
| is_active | No | Filter by active status | |
| updated_since | No | Filter by tasks updated since this timestamp |
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 mentions 'retrieve' suggesting a read operation but does not explicitly state safety, idempotency, or lack of side effects. No rate limits, auth needs, or behavioral traits beyond the basic retrieval 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?
Two sentences: the first states the main purpose, the second adds contextual value. It is concise and front-loaded without superfluous words, though it could be slightly more specific about filtering.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (4 parameters, no output schema, no annotations, numerous sibling list tools), the description is too sparse. It does not mention pagination, response structure, or how the parameters interact. Users need to infer from the schema alone, which is insufficient for complete understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the input schema already explains all 4 parameters. The description adds the generic phrase 'optional filtering' but does not provide additional meaning or examples beyond what the schema offers. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (retrieve) and resource (tasks), with optional filtering. It effectively distinguishes from sibling tools like create_task, delete_task, and get_task by focusing on listing. The addition that tasks are building blocks for time tracking provides useful context.
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 multiple tasks with optional filters, but lacks explicit guidance on when to use this tool versus alternatives like get_task for single tasks or list_project_task_assignments for assignments. No when-not or alternative conditions are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve a list of time entries with optional filtering. Supports filtering by user, client, project, task, billing status, date ranges, and more. Returns paginated results.
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | End date for date range filter (YYYY-MM-DD) | |
| from | No | Start date for date range filter (YYYY-MM-DD) | |
| page | No | Page number for pagination | |
| task_id | No | Filter by task ID | |
| user_id | No | Filter by user ID | |
| per_page | No | Number of entries per page (max 2000) | |
| client_id | No | Filter by client ID | |
| is_billed | No | Filter by billing status | |
| is_running | No | Filter by running timer status | |
| project_id | No | Filter by project ID | |
| updated_since | No | Filter by entries updated since this timestamp |
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 optional filtering and pagination, but does not disclose rate limits, performance, or behavior when no results are returned. The read-only nature is implied but not stated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no wasted words. The first sentence states core purpose, the second adds optionality and examples. 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?
No output schema exists, so description should explain return format and pagination details. It mentions 'Returns paginated results' but does not describe how to iterate pages or the response structure. More completeness would be beneficial given 11 parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds little beyond listing some filter types; it does not clarify parameter interactions or defaults. The schema already covers parameter meanings.
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 list of time entries with optional filtering, which distinguishes it from sibling tools like get_time_entry for a single entry. The verb 'Retrieve' and resource 'list of time entries' 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?
The description implies use when you need multiple entries with optional filters, but does not explicitly mention when not to use it or alternatives like get_time_entry. However, the context of filtering and pagination provides useful guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve a list of users with optional filtering by active status and updated date. Returns paginated results with user profiles and permissions.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number for pagination | |
| per_page | No | Number of users per page (max 2000) | |
| is_active | No | Filter by active status | |
| updated_since | No | Filter by users updated since this timestamp |
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 pagination and return of user profiles and permissions, but does not disclose authentication needs, rate limits, or default ordering. This is adequate but not richer.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with key information. No extraneous words. Efficiently communicates purpose, filtering, and pagination.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description hints at the return structure ('pagination, user profiles, permissions'). For a simple list tool, this is mostly complete, though more detail on return fields would be beneficial.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description merely restates the filter options (active status and updated date) without adding meaning beyond what the schema already 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 'Retrieve a list of users' with optional filtering and pagination, which is a specific verb+resource combination. It distinguishes from sibling tools like get_user (single user) 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?
The description implies usage for listing users with filters, but does not explicitly state when to use this tool versus alternatives like list_clients or get_user. No exclusions or alternative recommendations are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Restart a previously stopped timer, creating a new running time entry based on an existing entry.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The ID of the time entry to restart the timer for |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that it creates a new running time entry based on an existing entry, which is key behavior. However, without annotations, it does not explain other traits like required permissions, side effects on the original entry, or error conditions, leaving some gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is concise and front-loaded with the essential action. No extraneous information is present, making it 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?
Given the tool's simplicity (one parameter, no output schema), the description is fairly complete. It explains the core functionality. However, it could be slightly improved by mentioning the result or return type, or clarifying prerequisites like the timer must be stopped.
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 already covers the single parameter 'id' with a clear description. The tool description does not add additional meaning beyond what is in the schema, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Restart' and the resource 'timer', and distinguishes from siblings like start_timer and stop_timer by specifying that it restarts a previously stopped timer and creates a new entry based on an existing one.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description indicates that the tool is for restarting a stopped timer, but does not explicitly state when not to use it or compare with alternatives such as start_timer or create_time_entry. It provides implicit context but lacks explicit guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Start a timer for a new time entry. Creates a running time entry that tracks time automatically.
| Name | Required | Description | Default |
|---|---|---|---|
| notes | No | Initial notes for the timer | |
| task_id | Yes | The task ID to start the timer for | |
| project_id | Yes | The project ID to start the timer for | |
| spent_date | Yes | Date for the timer (YYYY-MM-DD format) | |
| external_reference | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears full responsibility. It discloses that the tool 'starts a timer' and 'creates a running time entry', indicating mutation. However, it does not describe side effects (e.g., if another timer is already running) or auth requirements, which are critical 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 extremely concise with one clear sentence that is front-loaded with the key action. No filler 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?
Despite having 5 parameters and no output schema, the description omits critical context: return value, error handling, what happens on duplicate timers, or how to stop the timer. For a tool with no annotations, this is insufficient.
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 high (80%), so the baseline is 3. The description adds no extra meaning beyond the schema's parameter descriptions. It does not explain how parameters like external_reference affect behavior or provide formatting hints.
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 'start' and resource 'timer for a new time entry', and distinguishes from sibling tools like restart_timer and stop_timer by specifying it creates a 'running time entry that tracks time automatically'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. For example, it does not mention whether starting a new timer stops an existing one or what prerequisites are required (e.g., no overlapping timers). Implicit usage only.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Stop a running timer and finalize the time entry with calculated hours.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The ID of the running time entry to stop |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full disclosure burden. It mentions 'finalize with calculated hours' but omits side effects (e.g., no undo), error handling (e.g., calling on already stopped timer), or whether additional steps are required.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with no unnecessary words. Directly states action and result.
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 mutation with one required parameter and no output schema, the description covers the core purpose. However, it lacks details on behavior for invalid IDs or non-running timers, and doesn't clarify if calculation is automatic.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and parameter description is clear. The description adds no extra context beyond what the schema provides (e.g., format, constraints, or edge cases). Baseline score applied.
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 ('stop a running timer') and the outcome ('finalize the time entry with calculated hours'), using a specific verb and resource that distinguishes it from siblings like start_timer and restart_timer.
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 timer is running, but provides no explicit guidance on when not to use it or alternatives (e.g., restart_timer for paused timers). The agent must infer context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing client. Can modify name, active status, address, and currency. Only provided fields will be updated.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The ID of the client to update (required) | |
| name | No | Update client name | |
| address | No | Update client address | |
| currency | No | Update currency code | |
| is_active | No | Update active status |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. Description states it updates (mutation) and partial update behavior. Lacks disclosure of side effects (e.g., fails if ID not found), permissions, or idempotency. Minimal but not contradictory.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no filler. Front-loaded with verb and resource, then lists fields and behavior.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema; description does not mention return value (e.g., updated object). Required ID is in schema. Reasonably complete for a simple CRUD update, but could disclose error conditions or permissions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameters are well documented. Description reiterates field groups but adds little beyond schema (e.g., no value constraints or usage tips). Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it updates an existing client and lists the updatable fields (name, active status, address, currency). Distinguishes from get_client (read) and create_client (creation).
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?
Implicitly indicates when to use (when modifying a client), and notes partial update behavior ('Only provided fields will be updated'). No explicit when-not or alternatives, but sufficient for a typical update tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing estimate including subject, terms, taxes, and other details. Only provided fields will be updated.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The ID of the estimate to update (required) | |
| tax | No | Update tax percentage | |
| tax2 | No | Update second tax percentage | |
| notes | No | Update estimate notes | |
| subject | No | Update estimate subject | |
| currency | No | Update currency code | |
| discount | No | Update discount percentage | |
| client_id | No | Update the client ID | |
| issue_date | No | Update issue date | |
| purchase_order | No | Update purchase order number |
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 discloses partial update behavior ('Only provided fields will be updated'), but does not mention authorization needs, rate limits, or what happens on validation errors. Given no annotations, this is adequate but not thorough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero fluff. First sentence states purpose and scope, second clarifies partial update behavior. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 10 parameters and no output schema, the description is minimal. It covers the key partial update behavior but does not explain return value, validation constraints, or authentication requirements. It is adequate but not fully complete for a tool with this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so each parameter is already described in the schema. The description adds general categories ('subject, terms, taxes, and other details') but does not provide additional meaning beyond what the schema offers. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the verb 'Update' and the resource 'existing estimate', listing specific fields like subject, terms, taxes. It distinguishes from siblings like create_estimate (creation) and delete_estimate (deletion).
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?
Usage is implied: use when you need to modify an existing estimate. The description does not provide explicit when-not or alternatives, but the purpose is clear given sibling tool names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing expense including project, category, cost, and billing details. Only provided fields will be updated.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The ID of the expense to update (required) | |
| notes | No | Update the notes | |
| units | No | Update the units | |
| user_id | No | Update the user ID | |
| billable | No | Update the billable status | |
| project_id | No | Update the project ID | |
| spent_date | No | Update the spent date | |
| total_cost | No | Update the total cost | |
| expense_category_id | No | Update the expense category ID |
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 states 'Only provided fields will be updated,' indicating partial update (PATCH semantics). However, it lacks details on error handling, permissions, idempotency, or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single, front-loaded sentence with no extraneous content. Efficiently communicates purpose and behavior.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema is provided, so the description should explain what is returned (e.g., the updated expense object). It does not mention return values or error conditions. Schema covers parameters adequately but completeness is lacking for expected output.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 100% description coverage for all parameters, so the baseline is 3. The description adds a summary of fields but no additional semantic 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 it updates an existing expense and lists the updatable fields (project, category, cost, billing details). It distinguishes from sibling create/delete tools by specifying 'update'.
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 an existing expense needs modification but does not provide explicit when-to-use/not-to-use guidance or mention alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing invoice including subject, dates, terms, taxes, and other billing details. Only provided fields will be updated.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The ID of the invoice to update (required) | |
| tax | No | Update tax percentage | |
| tax2 | No | Update second tax percentage | |
| notes | No | Update invoice notes | |
| subject | No | Update invoice subject | |
| currency | No | Update currency code | |
| discount | No | Update discount percentage | |
| due_date | No | Update due date | |
| client_id | No | Update the client ID | |
| issue_date | No | Update issue date | |
| payment_term | No | Update payment terms | |
| purchase_order | No | Update purchase order number |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden for behavioral disclosure. It states 'Only provided fields will be updated', which hints at partial update behavior. However, it does not disclose idempotency, side effects, validation rules, error conditions, or required permissions. For a mutation tool, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description consists of two concise sentences with no filler. The first sentence states the action and scope, the second clarifies the update behavior. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool is a mutation with 12 parameters, no output schema, and no annotations, the description is too brief. It omits essential context such as return value (e.g., updated invoice object), error handling, prerequisite conditions, and the exact meaning of 'only provided fields' (e.g., if null vs omitted fields are treated differently).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 100% coverage with descriptions for all 12 parameters, so the schema already documents each parameter. The description adds no additional semantic detail beyond summarizing the schema fields. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it updates an existing invoice and lists the categories of fields (subject, dates, terms, taxes). This distinguishes it from sibling tools like create_invoice (create vs update) and get_invoice (read). The verb 'update' and resource 'invoice' 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?
The description implies usage for modifying existing invoices by stating 'Update an existing invoice'. However, it does not provide explicit guidance on when to use this tool versus alternatives (e.g., other update tools like update_client), nor does it mention when not to use it or prerequisites (e.g., invoice must exist, user must have permission).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing project. Can modify any project settings including name, billing configuration, budget settings, and project timeline. Only provided fields will be updated.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The ID of the project to update (required) | |
| fee | No | Update fixed fee | |
| code | No | Update project code | |
| name | No | Update project name | |
| notes | No | Update project notes | |
| budget | No | Update budget amount | |
| bill_by | No | Update billing method | |
| ends_on | No | Update end date (YYYY-MM-DD) | |
| budget_by | No | Update budget calculation method | |
| is_active | No | Update active status | |
| starts_on | No | Update start date (YYYY-MM-DD) | |
| cost_budget | No | Update cost budget | |
| hourly_rate | No | Update hourly rate | |
| is_billable | No | Update billable status | |
| is_fixed_fee | No | Update fixed fee billing | |
| budget_is_monthly | No | Update monthly budget reset | |
| show_budget_to_all | No | Update budget visibility | |
| notify_when_over_budget | No | Update budget notifications | |
| cost_budget_include_expenses | No | Update expense inclusion | |
| over_budget_notification_percentage | No | Update notification threshold |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It notes that only provided fields are updated (partial update), which is useful, but it omits any mention of return behavior, side effects, permissions required, rate limits, or error handling. For a mutation tool with 20 parameters, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no wasted words. The first sentence front-loads the core action, and the second adds critical detail about partial updates. Ideal length for 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?
With 20 parameters, no output schema, and no annotations, the description is minimal. It does not explain what the tool returns after update, what happens on invalid input, or any side effects. For a complex update tool, more context is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description groups parameters into categories (name, billing, budget, timeline), which adds some meaning, but it does not provide additional semantic nuance beyond what the schema descriptions already offer.
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 updates an existing project and lists categories of settings (name, billing, budget, timeline). This distinguishes it effectively from sibling tools like create_project (creation) and delete_project (deletion), as well as get_project (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 implies usage for modifying an existing project but does not explicitly state when to prefer this over alternatives (e.g., create_project for new projects) or what prerequisites are needed (e.g., project existence). No exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing project task assignment including rates, budget, and active status. Only provided fields will be updated.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The task assignment ID to update (required) | |
| budget | No | Update budget allocation | |
| billable | No | Update billable status | |
| is_active | No | Update active status | |
| project_id | Yes | The project ID (required) | |
| hourly_rate | No | Update hourly rate |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; the description carries the burden. It adds that only provided fields are updated, a useful behavioral trait, but lacks details on authorization, side effects, or atomicity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence that is front-loaded with action and resource, then additional info. 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?
Tool has 6 parameters, no output schema, and moderate complexity. The description explains what it updates but not the return value or error handling, leaving a gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema coverage is 100% with descriptions for all parameters. The tool description does not add additional meaning beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (update), resource (project task assignment), and scope (rates, budget, active status). It distinguishes from sibling tools that are get, list, create, delete, 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?
The description mentions 'Only provided fields will be updated', implying partial updates, but does not explicitly state when to use this tool versus alternatives (e.g., create) or any prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing task. Can modify task name, billing settings, and activity status. Only provided fields will be updated.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The ID of the task to update (required) | |
| name | No | Update task name | |
| is_active | No | Update active status | |
| is_default | No | Update default task status | |
| billable_by_default | No | Update default billing status | |
| default_hourly_rate | No | Update default hourly rate |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description mentions that only provided fields will be updated (partial update behavior), which is useful. However, it does not disclose other behavioral aspects like error handling on non-existent IDs, permission requirements, or side effects on related entities. With no annotations, the description carries the full burden, and it partially meets it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with two sentences, no redundant information, and the purpose is front-loaded. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (6 simple parameters, no output schema), the description is fairly complete. It covers what can be updated and the partial update behavior. It could mention that the task must exist and that the tool likely returns the updated task object, but it is adequate for an 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?
The input schema has 100% coverage with descriptions for all 6 parameters, so the description does not need to repeat them. However, it adds context by grouping parameters into 'task name, billing settings, and activity status' and clarifies that updates are partial ('Only provided fields will be updated'). This adds 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 action ('update') and the resource ('existing task'), and lists the types of fields that can be modified (name, billing settings, activity status). This differentiates it from sibling update tools for other entities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like create_task or delete_task. It does not specify prerequisites, such as the task needing to exist, or when it is appropriate to update versus other operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing time entry. Can modify project, task, hours, notes, and other fields. Only provided fields will be updated.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The ID of the time entry to update | |
| hours | No | Update decimal hours | |
| notes | No | Update notes | |
| task_id | No | Update the task ID | |
| ended_time | No | Update end time in HH:MM format | |
| project_id | No | Update the project ID | |
| spent_date | No | Update the spent date (YYYY-MM-DD) | |
| started_time | No | Update start time in HH:MM format | |
| external_reference | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses update behavior and partial update, but lacks details on side effects, required permissions, or error conditions. No annotations are provided to supplement.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences that front-load the purpose. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema or annotations, but the description covers the basic action. Missing details on return value or error handling, which would be helpful.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is high (89%), so baseline is 3. The description adds minimal value by listing a few fields, but does not explain the external_reference object or constraints beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Update an existing time entry') and lists specific modifiable fields. It distinguishes from sibling tools like create_time_entry and delete_time_entry.
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?
Mentions 'Only provided fields will be updated' which implies partial updates, but does not provide explicit when-to-use vs. alternatives or exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing user's profile, permissions, and rates. Only provided fields will be updated.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The ID of the user to update (required) | |
| No | Update email address | ||
| is_admin | No | Update admin privileges | |
| timezone | No | Update timezone | |
| cost_rate | No | Update cost rate | |
| is_active | No | Update active status | |
| last_name | No | Update last name | |
| telephone | No | Update phone number | |
| first_name | No | Update first name | |
| can_see_rates | No | Update rate visibility | |
| is_contractor | No | Update contractor status | |
| weekly_capacity | No | Update weekly capacity | |
| is_project_manager | No | Update project manager role | |
| can_create_invoices | No | Update invoice creation permission | |
| can_create_projects | No | Update project creation permission | |
| default_hourly_rate | No | Update default hourly rate | |
| has_access_to_all_future_projects | No | Update future project access |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility for disclosing behavioral traits. It reveals the partial-update behavior ('Only provided fields will be updated') but omits details about required permissions, whether the update is reversible, or what response to expect.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that imparts both the purpose and a key behavioral detail (partial updates). Every word serves a purpose with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the large number of parameters (17) and the absence of an output schema, the description is adequate but minimal. It covers the core action and partial update behavior but leaves out expected return values, error handling, or idempotency, which would improve completeness for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers all 17 parameters with descriptions, achieving 100% coverage. The description adds no additional parameter-level detail beyond grouping them as 'profile, permissions, and rates,' which is marginally helpful.
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 (update), the target (existing user), and scope (profile, permissions, rates). The phrase 'Only provided fields will be updated' clarifies the semantics, distinguishing it from sibling tools like create_user or delete_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?
The description does not explicitly state when to use this tool versus alternatives, nor does it mention prerequisites or when not to use it. However, the name and sibling context make the intended use case (modifying an existing user) relatively clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Each tool targets a distinct resource and action (e.g., create_client, create_invoice, create_project). Even similar actions like start_timer/stop_timer/restart_timer are clearly differentiated. No ambiguity between tools.
All tools follow a consistent verb_noun pattern in snake_case (e.g., create_client, list_projects, get_time_entry). Report and timer tools also follow this pattern (get_time_report, start_timer). No mixing of conventions.
With 54 tools, this is far beyond the typical well-scoped range (3-15). Even for a comprehensive Harvest API, this many tools overwhelm agents and increases the risk of misselection. Extreme mismatch.
The tool set covers core CRUD operations for clients, projects, tasks, time entries, expenses, estimates, invoices, and users, plus reporting. Minor gaps exist (e.g., expense categories only have list, no create/update/delete; no invoice payment tools), but the surface is largely complete for the domain.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
An MCP server that provides access to Testiny projects, test cases and test runs
MCP server for Linear project management and issue tracking
MCP server exposing klokin time-tracking operations (employees, time entries, stores) to AI clients.
The official Planning Center MCP server for interacting with your ministry's data.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/ianaleck/harvest-mcp-server'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
