Allows logging hours against Asana tickets synced to Everhour. Provides tools to look up Asana tasks by GID, log time directly using Asana task IDs, and supports workflows for daily/weekly logging.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@everhour-mcp-server log 2 hours on Asana task 1208034567890123"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MCP server for Everhour time tracking, with first-class support for logging hours against Asana tickets.
Asana tasks synced into Everhour have IDs of the form as:<asanaGid>. The
server exposes tools to look them up, log time, run timers, and review
timesheets — both directly via Everhour task IDs and via raw Asana GIDs.
Tool | Purpose |
| Verify the API key and read your Everhour user ID |
| List/search projects, filterable by platform (e.g. |
| Fetch a project by ID |
| Find Everhour tasks by name (also matches synced Asana tasks) |
| Fetch a task by Everhour ID |
| Resolve an Asana task GID → Everhour task |
| Log hours on an Everhour task |
| Log hours given an Asana GID (workflow shortcut) |
| Log many entries at once (day/week/month), with per-row results |
| Review your timesheet (date range, project, task filters) |
| Edit an existing time record |
| Delete a time record |
| Start the active timer on a task |
| Stop the active timer |
| Check whether a timer is running |
Related MCP server: Asana MCP Server
Get your Everhour API key: profile → Settings → API integration: https://app.everhour.com/#/account/profile
Install & build:
npm install
npm run buildRun locally with the MCP Inspector:
EVERHOUR_API_KEY=ev_xxx npm run inspectAdd an entry under mcpServers in your client config. For Claude Desktop on
macOS, ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"everhour": {
"command": "node",
"args": ["/absolute/path/to/mcp everhour/dist/index.js"],
"env": {
"EVERHOUR_API_KEY": "ev_your_personal_api_key"
}
}
}
}For Claude Code (~/.claude.json or .claude/settings.json):
{
"mcpServers": {
"everhour": {
"command": "node",
"args": ["/absolute/path/to/mcp everhour/dist/index.js"],
"env": { "EVERHOUR_API_KEY": "ev_..." }
}
}
}Restart the client. The 15 tools listed above will appear.
Log time on an Asana ticket from its URL.
The user pastes https://app.asana.com/0/1234567890/1208034567890123 and says
"log 2 hours, fixed the retry bug":
Extract the GID 1208034567890123 from the URL.
Call everhour_log_time_for_asana_task with
asana_task_gid=1208034567890123, duration={ hours: 2 },
comment="fixed the retry bug".
Find a task by name and start tracking.
everhour_search_tasks with query="login bug".
Pick the right task ID (as:1208...) from results.
everhour_start_timer with that task_id.
Later: everhour_stop_timer.
Review what you logged this week.
everhour_list_time_records with from=YYYY-MM-DD (Mon), to=YYYY-MM-DD (Sun).
The .claude/skills/log-everhour/ skill logs a day, week, or month of Asana-ticket work
in one pass. You give per-day entries (ticket + hours + a rough comment); it
resolves each ticket, rephrases the comments to the Time Registration
Guidelines (.claude/skills/log-everhour/rephrasing-rules.md), normalizes hours to
30-minute increments, warns about duplicates, shows a preview table, and logs
everything via everhour_log_time_batch after a single confirmation.
Everhour pulls Asana tasks via the official integration. A task is only visible in Everhour after:
The Asana project has been added in Everhour (Settings → Integrations → Asana), or
A user with the Everhour browser extension opens the task in Asana.
If everhour_find_task_by_asana_id returns a 404, sync hasn't happened yet.
Var | Required | Description |
| yes | Personal Everhour API key |
MIT
Permanently delete a time record. Cannot be undone.
Args:
record_id (number): ID of the time record to delete.
Returns a confirmation message on success.
Examples:
"Delete time record 12345" → record_id=12345
Error Handling:
404 → record not found (may already have been deleted)
403 → record locked or not yours
| Name | Required | Description | Default |
|---|---|---|---|
| record_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide destructiveHint=true and idempotentHint=true. The description adds context about irreversibility ('Cannot be undone') and error handling (404, 403), which are beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise, with purpose stated first, followed by args, returns, examples, and error handling. 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?
For a simple tool with one parameter and no output schema, the description covers purpose, parameter semantics, return value, example, and error conditions. It is 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 0%, so description must compensate. It describes record_id as 'ID of the time record to delete' and provides an example mapping, which adds meaning beyond the schema's type and constraint.
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 'Permanently delete a time record', which is a specific verb and resource. This distinguishes it from sibling tools like 'everhour_update_time_record'.
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. It implies usage for permanent deletion but lacks guidance on scenarios where update or logging would be more appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Look up an Everhour task by the underlying Asana task GID.
Everhour syncs Asana tasks with IDs of the form 'as:'. This tool builds that ID and fetches the task in one step. Use this before logging time when the user gives you an Asana ticket URL or GID.
Args:
asana_task_gid (string): Numeric Asana task GID. Found in the Asana URL after /0/ (e.g. https://app.asana.com/0/1234567890/1208034567890123 → '1208034567890123')
response_format ('markdown' | 'json'): Output format
Returns the full Everhour task record (same as everhour_get_task).
Examples:
User pastes 'https://app.asana.com/0/1234/1208034567890123' → asana_task_gid='1208034567890123'
Error Handling:
404 → the Asana task is not synced into Everhour. The user must add the project to Everhour or open the task in Asana with the Everhour browser extension to trigger a sync.
| Name | Required | Description | Default |
|---|---|---|---|
| asana_task_gid | Yes | Asana task GID (numeric string). Found in the Asana task URL after /0/. | |
| response_format | No | Output format: 'markdown' for human-readable text or 'json' for machine-readable structured data | markdown |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, indicating a safe read operation. The description adds value by explaining how it constructs the Everhour ID ('as:<asanaGid>'), that it fetches the task in one step, returns the same record as everhour_get_task, and handles 404 errors explicitly.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized with clear sections (Args, Returns, Examples, Error Handling). It is concise, using no more than two sentences per section, and every sentence adds essential information 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?
With two parameters (one required), no output schema, and clear annotations, the description is fully complete. It explains the tool's role in the workflow, the parameter formats, what the return value is (reference to everhour_get_task), and how to handle errors. No gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema itself documents both parameters. However, the description adds practical context: for asana_task_gid, it provides the extraction rule from Asana URLs (e.g., after /0/), and an example. For response_format, it clarifies the output types. This enhances the schema's 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 tool's purpose: 'Look up an Everhour task by the underlying Asana task GID.' It explains the ID mapping ('as:<asanaGid>') and distinguishes itself from siblings like everhour_get_task and everhour_log_time_for_asana_task by focusing on the Asana-to-Everhour lookup.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly advises: 'Use this before logging time when the user gives you an Asana ticket URL or GID.' It does not explicitly state when not to use, but the context implies that if you already have an Everhour task ID, you should use everhour_get_task. Error handling is also provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the state of the authenticated user's timer.
Args:
response_format ('markdown' | 'json'): Output format
Returns:
When running: { "status": "active", "duration": seconds, "today": seconds, "task": {...}, "startedAt": ISO-8601 }
When stopped: { "status": "stopped", "today": seconds }
Examples:
"Is my timer running?" → no args
"How long have I been working today?" → check .today (seconds)
| Name | Required | Description | Default |
|---|---|---|---|
| response_format | No | Output format: 'markdown' for human-readable text or 'json' for machine-readable structured data | markdown |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnlyHint, idempotentHint), the description details the exact return structure for both running and stopped states, including fields like duration, today, task, and startedAt. This fully discloses behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-organized: one-line purpose, structured Args/Returns/Examples sections. Every sentence adds value; 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?
The description fully explains the tool's operation, return values, and usage examples. It covers both timer states and provides sufficient context given the low complexity and rich annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description repeats the schema's parameter info but doesn't add new constraints or meaning beyond the schema's own 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 'Return the state of the authenticated user's timer', specifying the verb (return) and resource (timer state). It distinguishes from sibling tools like start/stop timer by being a read-only query.
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?
Examples like 'Is my timer running?' and 'How long have I been working today?' illustrate appropriate usage. However, it does not explicitly mention when not to use it or list alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns the Everhour user account associated with the configured EVERHOUR_API_KEY.
Use this to discover the caller's user ID, which is required by some endpoints (e.g. when listing time records for "me") and to verify the API key is valid before logging time.
Args:
response_format ('markdown' | 'json'): Output format (default: 'markdown')
Returns: JSON shape: { "id": number, "name": string, "email": string, "role": string, "status": string, "headline"?: string, "capacity"?: number // weekly capacity in seconds }
Examples:
"Who am I in Everhour?" → call with no args
"What is my Everhour user ID?" → call with response_format='json' and read .id
Error Handling:
401 → API key missing or invalid; check EVERHOUR_API_KEY
| Name | Required | Description | Default |
|---|---|---|---|
| response_format | No | Output format: 'markdown' for human-readable text or 'json' for machine-readable structured data | markdown |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds value by specifying the return shape, error handling (401 for invalid API key), and confirming it's a safe read operation. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections: purpose, usage guidelines, args, returns, examples, error handling. Every sentence is informative and earns its place; no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description provides a detailed JSON shape for the return value, covers error handling, provides concrete examples, and explains usage context. It is fully complete for this simple tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a single parameter 'response_format' having enum, default, and description. The description adds meaningful examples (e.g., 'call with response_format="json" and read .id') and ties usage to real queries, exceeding just restating 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 'Returns the Everhour user account associated with the configured EVERHOUR_API_KEY.' It specifies a specific verb and resource. However, it does not explicitly differentiate from sibling tools like everhour_list_users, though the usage guidelines imply it's for the current 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 provides explicit when-to-use context: 'Use this to discover the caller's user ID, which is required by some endpoints (e.g. when listing time records for "me") and to verify the API key is valid before logging time.' This clearly guides the agent on appropriate scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch a single project by its Everhour project ID.
Args:
project_id (string): Everhour project ID (e.g. 'as:1208034567890123')
response_format ('markdown' | 'json'): Output format (default 'markdown')
Returns the full project record including name, platform, status, workspace, billing, budget, and members.
Examples:
"Show project as:1208012345678901" → project_id='as:1208012345678901'
Error Handling:
404 → project not found / not visible to this API key
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | Everhour project ID. For Asana-synced projects this is 'as:<asanaProjectGid>'. | |
| response_format | No | Output format: 'markdown' for human-readable text or 'json' for machine-readable structured data | markdown |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds value by specifying error handling (404), return contents (name, platform, status, etc.), and an example. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with Args, Returns, Examples, and Error Handling sections. It is concise but includes some redundancy with the schema. The main purpose is front-loaded in the first sentence.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple tool with good annotations, the description covers input parameters, error cases, and return contents. It is sufficient for an agent to use correctly, though it could mention authentication requirements or rate limits.
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%, but description adds meaning beyond schema by providing example project_id format ('as:1208034567890123'), enum values for response_format, default value, and explanation of return fields. This compensates for the lack of output 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 explicitly states 'Fetch a single project by its Everhour project ID', using a specific verb and resource. It distinguishes from sibling tool everhour_list_projects by focusing on a single project, and mentions the return of the full project record.
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 includes an example and error handling but does not explicitly state when to use this tool versus alternatives like everhour_list_projects. The context is implied by the parameter requirement 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.
Fetch a single Everhour task by ID, including total tracked time, estimate, and per-user time breakdown.
Args:
task_id (string): Everhour task ID. For Asana tasks: 'as:'
response_format ('markdown' | 'json'): Output format
Returns the full task object with name, projects, status, estimate (seconds), time.total (seconds), URL, etc.
Examples:
"Show task as:1208034567890123" → task_id='as:1208034567890123'
Error Handling:
404 → task not found / not synced into Everhour. Use everhour_find_task_by_asana_id to verify Asana mapping.
| Name | Required | Description | Default |
|---|---|---|---|
| task_id | Yes | Everhour task ID. For Asana-synced tasks the ID is 'as:<asanaGid>' (e.g. 'as:1208034567890123'). | |
| response_format | No | Output format: 'markdown' for human-readable text or 'json' for machine-readable structured data | markdown |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate the tool is read-only, idempotent, and non-destructive. The description adds valuable behavioral context beyond annotations, including the structure of the returned data (total tracked time, estimate, per-user breakdown) and specific error handling (404 response).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (purpose, args, returns, examples, error handling). It is concise, front-loaded with the main purpose, and every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with 2 parameters, the description is complete. It explains what the tool returns (full task object with relevant fields), provides usage examples, and covers error handling. No output schema is needed as the description sufficiently clarifies return values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the schema already explains both parameters well. The description adds an example for task_id format and error handling context, but does not significantly enhance understanding 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?
The description clearly states the tool fetches a single Everhour task by ID and includes tracked time, estimate, and per-user breakdown. It uses a specific verb and resource, distinguishing it from siblings like everhour_search_tasks which searches multiple tasks.
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 indicates this tool is for fetching a known task by ID. It provides an alternative in the error handling section (everhour_find_task_by_asana_id) for verifying Asana mapping, giving context for when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List or search Everhour projects, optionally filtered by source platform (e.g. Asana).
Useful for:
Discovering project IDs needed by other tools
Confirming an Asana project has been synced into Everhour
Browsing what work the user has access to
Args:
query (string, optional): Filter by name substring
platform ('asana' | 'trello' | 'jira' | 'github' | 'basecamp' | 'everhour', optional)
archived (boolean, optional): Include archived projects
limit, offset: Pagination (default limit=25, max 250)
response_format ('markdown' | 'json'): Output format (default 'markdown')
Returns: JSON shape: { "total": number, "count": number, "offset": number, "items": [{ "id": "as:...", "name": string, "platform": string, "status": string, "client"?: { "name": string }, ... }], "has_more": boolean, "next_offset"?: number }
Examples:
"List my Asana projects in Everhour" → platform='asana'
"Find the 'Lynx Dashboard' project" → query='Lynx Dashboard'
Error Handling:
401 → check EVERHOUR_API_KEY
429 → rate-limited, wait and retry
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum results to return (1-250, default 25) | |
| query | No | Optional search string. Filters projects by name (Everhour /projects?query=). | |
| offset | No | Number of results to skip for pagination (default 0) | |
| archived | No | If true, include archived projects. | |
| platform | No | Filter by source platform. Use 'asana' to list only Asana-synced projects. | |
| response_format | No | Output format: 'markdown' for human-readable text or 'json' for machine-readable structured data | markdown |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds error handling details (401, 429) and the return shape, providing transparency beyond annotations. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with sections (use cases, args, returns, examples, error handling). It front-loads the main purpose and every sentence adds value. No unnecessary 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?
All relevant aspects are covered: parameter details, return shape, pagination, error handling, and example scenarios. With no output schema and 6 optional parameters, the description fully equips an AI agent to use this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all 6 parameters. The description further clarifies query as substring, platform values, archived flag, pagination defaults, and response_format. Examples reinforce parameter 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 title and description clearly state the tool lists or searches Everhour projects with optional platform filtering. It is distinct from sibling tools like everhour_get_project (single project) or everhour_search_tasks (tasks).
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 lists specific use cases (discovering project IDs, confirming sync, browsing) and includes examples. However, it does not explicitly contrast with alternative tools (e.g., everhour_get_project for a single project by ID), which could be helpful.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List time records for a user across an optional date range, with optional project/task filters. Use this to review what's already been logged before adding more, or to build a timesheet.
Args:
from, to (string, optional): Date range, YYYY-MM-DD. If omitted, returns recent records.
user_id (number, optional): Defaults to the authenticated user.
project_id (string, optional): Restrict to one project.
task_id (string, optional): Restrict to one task.
limit, offset: Pagination (default limit=25, max 250)
response_format ('markdown' | 'json'): Output format
Returns: { "total": number, "count": number, "offset": number, "items": [{ "id": number, "date": string, "time": number, "comment": string|null, "task": { "id": string, "name"?: string } }], "has_more": boolean, "next_offset"?: number } Markdown output also shows a 'total tracked' summary.
Examples:
"Show what I logged this week" → from='YYYY-MM-DD' (Mon), to='YYYY-MM-DD' (Sun)
"How many hours have I logged on task as:1208...?" → task_id='as:1208...'
Error Handling:
403 → not authorized to view that user's records
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | End date (inclusive), YYYY-MM-DD. | |
| from | No | Start date (inclusive), YYYY-MM-DD. | |
| limit | No | Maximum results to return (1-250, default 25) | |
| offset | No | Number of results to skip for pagination (default 0) | |
| task_id | No | Filter to records on this specific Everhour task. | |
| user_id | No | Everhour user ID. Defaults to the authenticated user. Only admins may pass other user IDs. | |
| project_id | No | Filter to records on tasks in this Everhour project. | |
| response_format | No | Output format: 'markdown' for human-readable text or 'json' for machine-readable structured data | markdown |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. Description adds error handling (403 for unauthorized), defaults (user_id, pagination, response_format), and response structure. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear sections (Args, Returns, Examples, Error Handling). Front-loaded with 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?
Despite no output schema, description provides a full return structure and mentions markdown summary. Covers error code. Tool has 8 parameters, all described with defaults and constraints. Complete for a read-only list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameters already have descriptions. Description adds context: rephrases parameters, explains response_format, and includes examples. Adds value beyond schema but not significantly more.
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 lists time records for a user with optional filters (date range, project, task). It distinguishes from sibling write tools by focusing on reviewing logged time. Verb 'list' and resource 'time records' 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?
Explicit usage guidance: 'Use this to review what's already been logged before adding more, or to build a timesheet.' Also provides examples for 'this week' and specific task. Does not explicitly list when not to use or alternatives, but siblings are distinct (mostly write tools).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the workspace's team members with their Everhour user IDs. Admin access required.
Use this to resolve a person's name to their numeric Everhour user ID, which you then pass as 'user_id' to everhour_log_time / everhour_log_time_batch to log time on their behalf (admins only).
Args:
query (string, optional): case-insensitive filter on name or email. Omit to list everyone.
response_format ('markdown' | 'json')
Returns an array of user objects: { id, name, email, role, status, ... }.
Examples:
"What's Gayathri's Everhour user ID?" → query='gayathri', then read .id
"List all team members" → no args
Error Handling:
403 → the API key is not an admin key; listing all users requires admin access.
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | Optional case-insensitive filter matched against each user's name or email. Omit to list everyone. | |
| response_format | No | Output format: 'markdown' for human-readable text or 'json' for machine-readable structured data | markdown |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Disclosures admin access requirement, return structure, error handling (403). Annotations already mark it as read-only and idempotent; description adds context beyond those.
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?
Well-structured with sections for purpose, usage, args, returns, examples, error handling. Front-loaded with main purpose. No unnecessary text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description details the return array structure and fields, provides examples, and covers error handling. 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 already covers both parameters with descriptions. Description provides usage examples but no new semantic info beyond what's in the schema. Baseline 3 for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it lists team members and resolves names to IDs, distinguishing it from sibling list tools like list_projects. The purpose is specific and actionable.
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 tells when to use: to resolve a name to an Everhour user ID for logging time, with examples and mention of admin requirement. Also indicates when not to use (non-admin will get 403).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Log (add) tracked time against an Everhour task. This is the primary tool for recording hours worked.
Args:
task_id (string): Everhour task ID. For Asana tasks: 'as:'.
duration ({ hours?: number } | { seconds?: number }): How long to log. Provide ONE of:
hours: decimal hours, 0-24 (e.g. 1.5 = 1h 30m)
seconds: integer seconds, 60-86400
date (string, optional): YYYY-MM-DD. Defaults to today.
comment (string, optional): Note describing the work.
user_id (number, optional): Defaults to the authenticated user (only admins can log for others).
response_format ('markdown' | 'json'): Output format
Returns the created time record: { "id": number, "date": "YYYY-MM-DD", "user": number, "time": number, // seconds "comment": string | null, "task": { "id": string, "name"?: string }, "createdAt": "ISO-8601" }
Examples:
"Log 2 hours on task as:1208... for today" → task_id='as:1208...', duration={ hours: 2 }
"Log 45 minutes on OPS-123 yesterday with comment 'fix flaky test'" → after resolving the task ID: duration={ seconds: 2700 }, date='YYYY-MM-DD', comment='fix flaky test'
For an Asana ticket where you only have the GID, prefer everhour_log_time_for_asana_task.
Error Handling:
404 → task not synced; verify with everhour_find_task_by_asana_id
409 → a time record already exists for that user/date — use everhour_update_time_record instead
422 → validation error (duration too long, future date, etc.)
| Name | Required | Description | Default |
|---|---|---|---|
| date | No | Date the time was worked, YYYY-MM-DD. Defaults to today if omitted. | |
| comment | No | Optional note describing the work performed. | |
| task_id | Yes | Everhour task ID. For Asana-synced tasks the ID is 'as:<asanaGid>' (e.g. 'as:1208034567890123'). | |
| user_id | No | Everhour user ID to log time for. Defaults to the authenticated user. | |
| duration | Yes | ||
| response_format | No | Output format: 'markdown' for human-readable text or 'json' for machine-readable structured data | markdown |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate write, non-destructive, non-idempotent, open-world. Description adds behavioral context: explains creation of time record, default user behavior (authenticated user, admin can log for others), error scenarios, and output structure. Does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear sections (Args, Returns, Examples, Error Handling). Each sentence adds value. Front-loaded with purpose. Appropriate length given complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Complete description for a tool with 6 params (2 required), nested duration object, and no output schema. Covers all parameters, output format, error handling, usage patterns, and examples.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 83%, so baseline is 3. Description adds significant value beyond schema: explains duration as mutually exclusive hours/seconds with examples, default date, response_format enum, and provides examples that clarify usage. Only minor redundancy with 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 'Log (add) tracked time against an Everhour task' and identifies itself as the primary tool for recording hours. It differentiates from siblings like everhour_log_time_for_asana_task (mentioned in examples) and everhour_update_time_record (in error handling).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says when to use this tool (primary for recording hours). Provides error handling that guides to alternatives: for 409 use everhour_update_time_record, for 404 use everhour_find_task_by_asana_id. Also advises preferring everhour_log_time_for_asana_task when only Asana GID is known.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Log a batch of time records in a single call — one entry per (task, date). Built for the log-everhour daily/weekly/monthly workflow: pass already-resolved task IDs and already-rephrased comments.
Each entry is logged sequentially. A single row failing (404 not synced, 409 already exists, etc.) does NOT abort the batch unless stop_on_error is true — failures are reported per row.
Durations are normalized to increment_hours (default 30 min). Comments are checked against absolute rules; a forbidden word or empty comment rejects that row unless allow_rule_violations is true.
Args:
entries (array, 1-60): { task_id: 'as:' | native, duration: { hours } | { seconds }, date: 'YYYY-MM-DD', comment: string }
increment_hours (number, optional): rounding grid, default 0.5
stop_on_error (boolean, optional): default false
allow_rule_violations (boolean, optional): default false
user_id (number, optional): defaults to caller
response_format ('markdown' | 'json')
Returns: { "results": [{ "ok": boolean, "task_id": string, "date": string, "hours": number, "rounded"?: boolean, "warnings"?: string[], "record_id"?: number, "error"?: string }], "summary": { "logged": number, "failed": number, "totalHours": number } }
Examples:
Log a full day: entries=[{ task_id:'as:1208...', duration:{hours:3}, date:'2026-06-12', comment:'Reviewed and submitted changes for review.' }, ...]
Error Handling:
Per-row 404 → that Asana task is not synced; other rows still log.
Per-row 409 → a record already exists for that user/date; fix with everhour_update_time_record.
| Name | Required | Description | Default |
|---|---|---|---|
| entries | Yes | Resolved, rephrased entries to log. The log-everhour skill prepares these (tickets already resolved to Everhour IDs, comments already rephrased). | |
| user_id | No | Everhour user ID to log for. Defaults to the authenticated user. | |
| stop_on_error | No | If true, stop at the first failing row. Default false: log every reachable row and report failures. | |
| increment_hours | No | Duration rounding grid in hours. 0.5 = 30 min (default). 0.25 = 15 min, consultant special cases only. | |
| response_format | No | Output format: 'markdown' for human-readable text or 'json' for machine-readable structured data | markdown |
| allow_rule_violations | No | If false (default), rows whose comment breaks a hard rule (forbidden word / empty) are rejected instead of logged. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Disclosures beyond annotations: sequential logging, no batch abort unless stop_on_error, duration rounding, comment rule checking, per-row error types (404, 409) with suggested fixes. Annotations only provide openWorldHint=true, so description adds critical 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?
Well-structured: front-loaded with purpose, then behavior, args, returns, examples, errors. Every sentence earns its place, though slightly verbose in parts. Could be tighter but overall 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?
Covers all aspects: purpose, prerequisites, behavior, complete parameter details, return format, examples, error handling. No gaps despite missing output schema and complex nested 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?
Despite 100% schema coverage, description adds meaning: explains entries structure, rounding grid (increment_hours), rule checking (allow_rule_violations), user_id default, response_format enum meaning, and return structure in detail with 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?
Description clearly states 'Log a batch of time records in a single call — one entry per (task, date)'. Distinguishes from siblings (everhour_log_time, everhour_log_time_for_asana_task) by emphasizing batch processing and the specific workflow it supports.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides strong guidance: 'Built for the log-everhour daily/weekly/monthly workflow', implying use after preparation. Describes sequential logging and per-row failure handling, guiding away from transactional all-or-nothing needs. Does not explicitly exclude single-entry tools but implies them.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Workflow tool: log time on the Everhour task that mirrors a given Asana task GID. Equivalent to calling everhour_log_time with task_id='as:', but spares you having to construct the ID.
Use this when the user gives you an Asana ticket URL/GID and asks to log hours.
Args:
asana_task_gid (string): Numeric Asana task GID
duration: same as everhour_log_time
date, comment, user_id: same as everhour_log_time
response_format ('markdown' | 'json')
Returns the created time record (same shape as everhour_log_time).
Examples:
User: "Log 1.5h on Asana ticket 1208034567890123 — implemented retry logic" → asana_task_gid='1208034567890123', duration={ hours: 1.5 }, comment='implemented retry logic'
Error Handling:
404 → Asana task not synced into Everhour
409 → a record already exists for that user/date (use everhour_update_time_record)
| Name | Required | Description | Default |
|---|---|---|---|
| date | No | ||
| comment | No | ||
| user_id | No | ||
| duration | Yes | ||
| asana_task_gid | Yes | Asana task GID (numeric string). Found in the Asana task URL after /0/. | |
| response_format | No | Output format: 'markdown' for human-readable text or 'json' for machine-readable structured data | markdown |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate the tool is not read-only (readOnlyHint=false) and not idempotent. The description adds context about error codes (404, 409) and the wrapper nature, which goes beyond annotations but does not contradict them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear purpose first, then usage, args, returns, examples, and error handling. It is slightly verbose in repeating 'same as everhour_log_time' for multiple params but efficiently uses front-loading.
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 params, no output schema, nested objects), the description covers purpose, usage, error handling, examples, and references sibling for param details. It is complete enough for an AI agent to invoke correctly, though it could include a note on the exact return shape.
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 33%, but the description adds significant value: it explains the asana_task_gid parameter thoroughly, provides examples, and references everhour_log_time for common parameters. This compensates for the lack of schema descriptions on three parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('log time') and the resource ('Everhour task that mirrors a given Asana task GID'). It distinguishes from siblings by noting it's equivalent to everhour_log_time with a constructed ID, avoiding the need to construct the ID manually.
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 says 'Use this when the user gives you an Asana ticket URL/GID and asks to log hours.' It also provides error handling with alternatives: 404 suggests Asana task not synced, 409 suggests using everhour_update_time_record.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search tasks in Everhour by name, optionally scoped to a project.
This is the primary way to find an Everhour task that mirrors an Asana ticket when you only know the ticket name. Asana-synced tasks appear with IDs like 'as:'.
Args:
query (string): Search string, 1-200 chars
project_id (string, optional): Scope search to this Everhour project ID
limit, offset: Pagination (default limit=25, max 250)
response_format ('markdown' | 'json'): Output format
Returns: { "total": number, "count": number, "offset": number, "items": [{ "id": "as:...", "name": string, "url": string, "status"?: string, "projects"?: string[] }], "has_more": boolean, "next_offset"?: number }
Examples:
"Find Everhour task for 'Fix login bug'" → query='Fix login bug'
"Find all design review tasks in project as:120801..." → query='design review', project_id='as:120801...'
Error Handling:
400 → query is empty
429 → rate-limited
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum results to return (1-250, default 25) | |
| query | Yes | Search string. Matches task name and (for synced tasks) the source platform's task name. Examples: 'login bug', 'OPS-123'. | |
| offset | No | Number of results to skip for pagination (default 0) | |
| project_id | No | Optional Everhour project ID to scope the search (e.g. 'as:120801...'). | |
| response_format | No | Output format: 'markdown' for human-readable text or 'json' for machine-readable structured data | markdown |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true, destructiveHint=false, idempotentHint=true, openWorldHint=true. The description adds behavioral details such as matching by name and source platform task name, return structure, error codes (400, 429), and pagination behavior. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured with clear sections (purpose, Args, Returns, Examples, Error Handling). Every sentence provides value, and the format is easy to parse. 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 five parameters, full schema coverage, no output schema, the description provides comprehensive information: usage examples, return format, pagination details, and error handling. An agent has all necessary context to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with parameter descriptions. The description adds meaningful context: query length constraints, project_id format (e.g., 'as:...'), pagination defaults and limits, and response_format options. Examples further clarify parameter 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 that the tool searches tasks by name with optional project scoping. It explicitly identifies itself as the primary way to find Asana-synced tasks when only the ticket name is known, distinguishing it from the sibling everhour_find_task_by_asana_id.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context ('primary way to find an Everhour task that mirrors an Asana ticket') and examples. However, it does not explicitly state when to avoid this tool or mention alternatives like everhour_find_task_by_asana_id for direct Asana ID lookup.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Start the active timer on an Everhour task. Only one timer can run at a time per user; starting a new one stops the previous.
Args:
task_id (string, optional): Everhour task ID. Use this OR asana_task_gid.
asana_task_gid (string, optional): Asana task GID. Will be resolved to 'as:'.
user_date (string, optional): YYYY-MM-DD, the user's local date. Defaults to today.
comment (string, optional): Note attached to the running timer.
response_format ('markdown' | 'json'): Output format
You must provide exactly one of task_id or asana_task_gid.
Returns the timer state (status='active', task, startedAt, today seconds, duration).
Examples:
"Start tracking Asana ticket 1208034567890123" → asana_task_gid='1208034567890123'
"Start a timer on task as:1208... with comment 'investigating bug'" → task_id='as:1208...', comment='investigating bug'
Error Handling:
404 → task not found / not synced into Everhour
| Name | Required | Description | Default |
|---|---|---|---|
| comment | No | Optional note attached to the timer. | |
| task_id | No | Everhour task ID. For Asana-synced tasks the ID is 'as:<asanaGid>' (e.g. 'as:1208034567890123'). | |
| user_date | No | The user's local date the timer is associated with. Defaults to today. | |
| asana_task_gid | No | Asana task GID (numeric string). Found in the Asana task URL after /0/. | |
| response_format | No | Output format: 'markdown' for human-readable text or 'json' for machine-readable structured data | markdown |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate non-read-only and non-destructive behavior. The description adds value by explaining that starting a new timer stops the previous one and details the return state. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, well-structured with clear sections for args, return, examples, and errors. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of an output schema, the description covers purpose, parameters, behavior, return value, and error handling, making it fully actionable for an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds context on mutual exclusivity, format examples, and default values, going beyond the schema alone.
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 ('Start the active timer on an Everhour task') and distinguishes from sibling tools like everhour_stop_timer by noting that only one timer can run at a time.
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 specifies that exactly one of task_id or asana_task_gid must be provided, includes examples, and mentions error handling. It could explicitly state when not to use it, but the context is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Stop the currently running timer for the authenticated user. Everhour will commit the elapsed time as a time record on the task.
Args:
response_format ('markdown' | 'json'): Output format
Returns the timer state after stopping (status='stopped', today total seconds).
Examples:
"Stop my timer" → no args needed
Error Handling:
404 → no timer is currently running
| Name | Required | Description | Default |
|---|---|---|---|
| response_format | No | Output format: 'markdown' for human-readable text or 'json' for machine-readable structured data | markdown |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate it's not read-only (mutating), not destructive, and idempotent. The description adds value by stating that it commits elapsed time and returns the timer state, which is beyond the annotations. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with zero wasted words, well-structured into sections (Args, Returns, Examples, Error Handling). Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given only one optional parameter and no output schema, the description fully covers inputs, outputs, errors, and usage examples. 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 a clear description of response_format. The description adds meaning by noting that no arguments are needed (due to default) and provides an example, improving usability.
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 stops the currently running timer and commits elapsed time, with a specific verb ('stop') and resource ('timer'). It distinguishes from siblings like everhour_start_timer and everhour_get_current_timer by focusing on the stopping action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use (to stop a running timer) and includes error handling (404 if no timer running). It does not explicitly state when not to use or mention alternatives, but the context is sufficient for the straightforward action.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Modify an existing time record (change duration, date, or comment).
Args:
record_id (number): The time record ID returned by everhour_list_time_records or everhour_log_time.
duration ({ hours? } | { seconds? }, optional): New duration. Omit to keep existing.
date (string, optional): New date YYYY-MM-DD. Omit to keep existing.
comment (string, optional): New comment. Pass empty string to clear it. Omit to keep existing.
response_format ('markdown' | 'json')
Returns the updated time record.
Examples:
"Change record 12345 to 3 hours" → record_id=12345, duration={ hours: 3 }
"Update the comment on record 12345 to 'pair session with Alex'" → record_id=12345, comment='pair session with Alex'
Error Handling:
404 → record not found
403 → record locked (period closed) or not yours
| Name | Required | Description | Default |
|---|---|---|---|
| date | No | ||
| comment | No | ||
| duration | No | ||
| record_id | Yes | ID of the time record to update. | |
| response_format | No | Output format: 'markdown' for human-readable text or 'json' for machine-readable structured data | markdown |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Descriptors 'Modify' and error for locked records add context beyond annotations. IdempotentHint is noted but not explained; still sufficient for understanding behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with Args, Returns, Examples, Error Handling. Every sentence adds value; 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 5-param update tool, description covers all aspects: parameter roles, examples, error cases, and return value. No gaps given simplicity of 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?
Despite 40% schema coverage, description fully explains all parameters: record_id source, duration format, date format, comment clearing, response_format options. Examples reinforce 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?
Clearly states 'Modify an existing time record' with specific attributes (duration, date, comment). Distinguishes from sibling tools like delete or log time.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides parameter guidance (e.g., record_id source, optional semantics, clearing comment) and error handling for 404/403. Lacks explicit when-not-to-use, but purpose implies it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0everhour_delete_time_recordeverhour_find_task_by_asana_ideverhour_get_current_timereverhour_get_current_usereverhour_get_projecteverhour_get_taskeverhour_list_projectseverhour_list_time_recordseverhour_list_userseverhour_log_timeeverhour_log_time_batcheverhour_log_time_for_asana_taskeverhour_search_taskseverhour_start_timereverhour_stop_timereverhour_update_time_recordScored across 16 tools
Every tool has a clearly distinct purpose with detailed descriptions. Potential overlaps like everhour_log_time and everhour_log_time_for_asana_task are clearly differentiated as a convenience wrapper, and all timer, task, project, user, and time record tools have unambiguous scopes.
All tools follow a consistent 'everhour_<action>_<target>' pattern using snake_case. Actions like get, list, log, start, stop, search, find, update, delete are used consistently, and longer names are descriptive without mixing conventions.
16 tools is well-scoped for a time tracking server. Each tool earns its place covering CRUD for time records, timer management, task/project queries, and user management, without being excessive.
The tool surface covers the full lifecycle of time tracking: creating, reading, updating, deleting time records; timer start/stop/status; task and project lookups; and user information. No obvious gaps for the intended domain.
Asana MCP — wraps the Asana REST API (OAuth)
Manage Timequip projects, tasks, comments, members, and dashboards through MCP.
Official Todoist MCP server for AI assistants to manage tasks, projects, and workflows.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
