Time Doctor MCP Server
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., "@Time Doctor MCP ServerShow productive vs unproductive time for user 42 this week."
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.
Time Doctor MCP Server
MCP server for Time Doctor's employee time-tracking / productivity-monitoring API - companies, users, projects, tasks, and time-use statistics, for AI assistants and the WYRE Conduit gateway.
Authentication
Time Doctor's current, officially documented API (https://timedoctor.redoc.ly, API Version 1.0.0) authenticates with the same email/password a user logs into app.timedoctor.com with - there is no separate client-ID/secret application-registration flow. POST /api/1.0/login exchanges the email/password for a JWT bearer token valid for six months (Authorization: JWT {token} on every subsequent call). This server handles that exchange (and re-login on rejection) internally - callers only ever need to supply the email/password.
Some Time Doctor accounts require a TOTP (2FA) code at login; accounts with 2FA enabled are not currently supported by this connector.
Related MCP server: TrackingTime MCP Server
Configuration
Env var | Description |
| Time Doctor account email address. |
| Time Doctor account password. |
|
|
|
|
| When set, the HTTP transport requires a valid |
|
|
Tools
Companies
timedoctor_list_companies- companies (workspaces) the authenticated user owns or administers.timedoctor_get_company- a single company by ID.
Users
timedoctor_list_users- users, optionally scoped to a company and filtered by email/name.timedoctor_get_user- a single user by ID.timedoctor_check_invitation- whether a company invitation exists for an email address (read-only).
Projects
timedoctor_list_projects- projects in a company.timedoctor_get_project- a single project by ID.
Tasks
timedoctor_list_tasks- tasks in a company, filterable by project, name, or open/closed status.timedoctor_get_task- a single task by ID.
Activity / Stats
timedoctor_get_worklog- detailed work-session log (start time, duration, task/project, mode) for a user or company within a time range.timedoctor_get_timeuse_stats- aggregated productivity statistics (time per application/category, productive vs. unproductive) for a user or company within a time range.
Scope
This is a v1 / MVP surface covering the core MSP time-tracking-oversight workflow: who's tracked where, and how their time breaks down. Explicitly out of scope for now: Files (screencasts/screenshots), Categories, Work Schedules (lower-value admin config), any user invitation/creation/deletion mutation, and the "login as" user-impersonation endpoint (a real security-sensitive feature). They can be added as a follow-up if there's demand.
Development
npm install
npm run build
npm test
npm run lint # tsc --noEmitDocker
docker build -t timedoctor-mcp .
docker run -p 8080:8080 -e TIMEDOCTOR_EMAIL=... -e TIMEDOCTOR_PASSWORD=... timedoctor-mcpAvailable Tools
11 toolstimedoctor_check_invitationA
Check whether a Time Doctor company invitation exists for an email address (read-only - does not send or manage invitations).
| Name | Required | Description | Default |
|---|---|---|---|
| Yes | Email address to check. | ||
| company | Yes | Company ID. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavior. It states 'read-only' and 'does not send or manage invitations', covering non-destructiveness. However, it does not describe the return format (e.g., boolean, object) or any edge-case behavior (e.g., invalid email, non-existent invitation). Given the lack of annotations, the description is partially transparent but leaves the exact output unspecified.
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 front-loads the core purpose and immediately adds the read-only qualifier. No filler, no redundancy. It is optimally concise for a simple check tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with two straightforward parameters and no output schema, the description covers the essential purpose and safety (read-only). It lacks explicit return-type information, which an agent might need to interpret results, but the phrasing 'check whether exists' strongly implies a boolean. Given the simplicity, the description is nearly complete; a minor gap on return format prevents a 5.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both parameters ('email' and 'company') having minimal descriptions ('Email address to check' and 'Company ID'). The tool description adds no extra meaning beyond the schema—it simply references checking an email. Baseline of 3 is appropriate since the schema already documents parameters and the description doesn't enrich them.
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 'Check' and the resource 'invitation existence for an email address'. It distinguishes itself from sibling tools by targeting invitations, which none of the others (companies, users, tasks, projects, worklogs, time use stats) cover. No 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 includes 'read-only - does not send or manage invitations', which clarifies when not to use it (for creating or modifying invitations). While it doesn't explicitly name an alternative (since no sibling handles invitations), the purpose is self-evident and the exclusion of management actions provides clear context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
timedoctor_get_companyA
Get a single Time Doctor company by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| companyId | Yes | Company ID. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full disclosure burden. It signals read-only 'get' behavior and that one company is returned, but it does not mention behavior for not-found/error cases, required scopes, or response structure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One short sentence that front-loads the action and resource, with no repeated information from the schema. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter lookup tool with no annotations and no output schema, the description is close to sufficient: it identifies the input and the intended result. Missing details are limited to error behavior and output shape, which are minor for such a simple 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 covers 100% of the single parameter, and the description's 'by ID' only restates that the companyId is the identifier. No additional format, validation, or edge-case semantics are added 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?
States exactly what it does: retrieves a single Time Doctor company, and the qualifiers 'single' and 'by ID' differentiate it from timedoctor_list_companies and other get_* siblings. The resource and identifier are both explicit.
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 only implies usage: an agent should call it when it has a companyId and needs one company, versus listing companies. It does not explicitly name timedoctor_list_companies or state when not to use it, so guidance is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
timedoctor_get_projectC
Get a single Time Doctor project by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| company | Yes | Company ID. | |
| projectId | Yes | Project ID. |
TDQS
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 'Get' which implies a read-only operation, but does not explicitly confirm non-mutating behavior, nor does it mention error handling, authentication requirements, or response format. For a simple get-by-ID tool, this is a minimal but acceptable 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, front-loaded sentence with no unnecessary words. It is efficient and to the point, though it could arguably include a little more context without losing 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?
For a straightforward get-by-ID operation with no output schema and no annotations, the description is mostly sufficient. It identifies the tool's purpose and required inputs (via schema). However, it does not specify what the response will contain or any potential edge cases (e.g., project not found), which would enhance completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (both 'Company ID.' and 'Project ID.' are present). The description adds no extra parameter context beyond the schema; it merely references 'by ID'. Since the schema fully documents the parameters, the 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 (Get) and resource (single Time Doctor project by ID). It distinguishes from list_projects by specifying 'single', but does not explicitly name the sibling alternative. It is specific enough for an agent to understand the core purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. The description implies it is for fetching a specific project by ID, but does not mention when not to use it (e.g., when needing a list, use timedoctor_list_projects). The context is minimal and left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
timedoctor_get_taskB
Get a single Time Doctor task by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| taskId | Yes | Task ID. | |
| company | Yes | Company ID. |
TDQS
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 only indicates a read operation via 'Get' and does not mention response format, error behavior, authentication needs, rate limits, or any side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single clear sentence with no fluff or unnecessary clauses. It is front-loaded with the core purpose, though 'Time Doctor' is somewhat redundant with the tool name.
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 and schema together are enough for basic invocation, but with no annotations and no output schema, there is no indication of what the successful response contains or what happens on failure. For a simple get-by-ID tool, this is minimal but acceptable with clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so taskId and company are already documented. The description adds little beyond the schema other than reinforcing that the task is fetched by ID, which is the baseline expectation for a schema-heavy low-complexity definition.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Get'), a clear resource ('a single Time Doctor task'), and the lookup method ('by ID'). The word 'single' differentiates it from the sibling timedoctor_list_tasks without requiring schema inspection.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool should be used when the caller already knows the task ID)Skip it does not explicitly say when to prefer it over list_tasks or another sibling, nor does it state exclusions. Usage is inferable but not directly guided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
timedoctor_get_timeuse_statsB
Get aggregated Time Doctor productivity statistics (time spent per application/category, productive vs. unproductive) for a user or company within a time range.
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | ISO 8601 end of range (exclusive). | |
| from | No | ISO 8601 start of range (inclusive). | |
| page | No | Number of results to skip. | |
| user | No | Comma-separated user IDs. Defaults to the authenticated user. | |
| limit | No | Maximum number of results to return. | |
| company | Yes | Company ID. | |
| category | No | Category to fetch the report for. |
TDQS
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 implies a read operation via 'Get' but doesn't explicitly state read-only behavior, authentication requirements, pagination limits, or error handling. It also does not describe the output format, which is critical since no output schema exists. The description is minimal in behavioral detail.
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. It has no redundant wording and is easy to parse. However, it could be slightly more structured by explicitly mentioning scope or alternatives, but it remains appropriately sized and clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 7 parameters, no output schema, and no annotations, the description is insufficient for an agent to use it correctly. It doesn't explain the difference from get_worklog, doesn't describe the return shape (e.g., aggregated per user or per day), and doesn't mention default behaviors like user defaulting to the authenticated user (though schema mentions it). The description lacks critical context for decision-making and expectation setting.
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 7 parameters with descriptions (100% coverage), so the baseline is 3. The description adds minimal meaning beyond the schema, only reinforcing that stats are 'for a user or company' which matches the user and company parameters. It does not explain how category, page, or limit interact, nor does it provide examples or format constraints, so it doesn't significantly enhance schema semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and the resource 'aggregated Time Doctor productivity statistics', specifying the dimensions (per application/category, productive vs. unproductive) and scope (user or company, time range). It is distinct from siblings like get_worklog which would provide detailed time entries, though it doesn't explicitly name alternatives. The purpose is unambiguous 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?
The description provides no guidance on when to use this tool versus alternatives such as timedoctor_get_worklog or timedoctor_get_task. It does not specify scenarios like 'use for productivity overview' or exclusions like 'for raw time entries use get_worklog'. The agent is left to infer the appropriate use case, which is a significant gap given the variety of sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
timedoctor_get_userA
Get a single Time Doctor user by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| userId | Yes | User ID. | |
| company | No | Company ID the user belongs to. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. The verb 'Get' implies a read-only, non-destructive operation, but the description does not explicitly state side-effect behavior, authentication requirements, or error handling. This is minimally transparent but not misleading.
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 redundant words. Every word contributes to the core purpose, making it easy for an agent to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-resource getter, the description plus the fully documented schema is mostly sufficient for an agent to invoke the tool correctly. The only minor gap is the lack of any mention of the return value shape, which is otherwise implied by the tool name.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both userId and company. The description adds no additional parameter meaning beyond what the schema provides, 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 states a specific action ('Get'), a clear resource (a single Time Doctor user), and the key scope ('by ID'). This distinguishes it from list-oriented siblings like timedoctor_list_users and from other getters like timedoctor_get_company.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'by ID' implicitly signals that this tool should be used when a specific user ID is known, as opposed to listing users. However, there is no explicit guidance about when to prefer this over list_users or when the optional company parameter should be supplied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
timedoctor_get_worklogA
Get detailed Time Doctor work-session log (start times, duration, task/project, mode) for a user or company within a time range. For best performance, query <=7-day windows at a time.
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | ISO 8601 end of range (exclusive). | |
| from | No | ISO 8601 start of range (inclusive). | |
| user | No | Comma-separated user IDs. Defaults to the authenticated user. | |
| company | Yes | Company ID. | |
| taskProjectNames | No | Resolve task/project names instead of only IDs. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral disclosure burden. It does disclose that this is a read-style operation, what data fields are included, and the performance implication of large time ranges. It does not mention pagination, response shape, permission requirements, or defaults for from/to, which would strengthen 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 deliver the purpose, scope, content, and a concrete performance tip without filler. The main action is front-loaded and the operational guidance is compact, so every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only log retrieval tool with a fully documented schema, the description covers the tool's purpose, scope, key returned fields, and the main operational concern (7-day windows). It does not explain behavior when from/to are omitted or describe the response structure, but those are minor gaps given the schema completeness and the absence of an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for all five parameters, so the schema already carries the parameter semantics. The description adds only a high-level mapping between user/company/time range and the parameters, without adding new detail, so the 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 uses a specific verb and resource ('Get detailed Time Doctor work-session log') and enumerates the returned fields: start times, duration, task/project, mode. It is distinguishable from siblings like timedoctor_get_timeuse_stats by its focus on session-log details, though it does not explicitly name a differentiating sibling.
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 makes it clear this tool is for retrieving work-session logs within a time range for a user or company, and it adds a useful operational guideline ('query <=7-day windows at a time'). However, it does not state when not to use it or name alternatives, so the routing guidance is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
timedoctor_list_companiesA
List Time Doctor companies (workspaces) the authenticated user owns or administers.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It does clarify that the result is limited to companies the user owns or administers, but it does not mention authentication requirements, empty-result behavior, pagination, or response shape. For a read-only list, this is a notable gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no filler. It front-loads the verb and resource, then adds the ownership scope, which is exactly the information an agent needs to select the tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a no-argument list tool, the description is largely complete: it names what is listed and the scope. The only minor gap is that with no output schema, it does not describe the returned company fields, but the operation is simple enough that an agent can infer a reasonable list of company objects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and the schema is fully descriptive by virtue of being empty. The description adds no parameter detail, but none is needed; the baseline of 4 for a zero-parameter tool 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 states a specific verb ('List'), a clear resource ('Time Doctor companies (workspaces)'), and a scope qualifier ('the authenticated user owns or administers'). This makes the tool's function immediately distinguishable from the singular 'timedoctor_get_company' sibling.
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 about when to use this tool versus alternatives such as timedoctor_get_company or timedoctor_list_users. The scope qualifier hints at the intended context, but there is no explicit when-to-use, when-not-to-use, or alternative routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
timedoctor_list_projectsC
List Time Doctor projects in a company.
| Name | Required | Description | Default |
|---|---|---|---|
| all | No | Return all company projects instead of only ones assigned to the caller. | |
| name | No | Filter: name starts with this value. | |
| page | No | Number of results to skip. | |
| limit | No | Maximum number of results to return. | |
| company | Yes | Company ID. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It only says 'list', implying a read operation, but does not disclose pagination behavior, filtering nuances, or whether only assigned projects are returned by default (which the 'all' parameter hints at but the description does not explain).
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 with no filler. However, it is so brief that it may be under-specified, though it avoids verbosity.
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 5 parameters, no output schema, and no annotations, this description is insufficient. It does not explain return values, pagination details, or when the 'all' flag is needed. An agent cannot fully understand the tool's behavior from the description alone.
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 each parameter has a description. The tool description adds no extra parameter context beyond the schema, which is acceptable given full coverage, but it does not clarify usage relationships among 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 action (List) and resource (Time Doctor projects) and includes context ('in a company'). It distinguishes from get_project by the verb, but does not explicitly name the sibling or contrast behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives like timedoctor_get_project. There is no mention of scenarios, prerequisites, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
timedoctor_list_tasksA
List Time Doctor tasks in a company, optionally filtered by project, name, or open/closed status.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Filter: name starts with this value. | |
| page | No | Number of results to skip. | |
| limit | No | Maximum number of results to return. | |
| status | No | Filter by task status. | |
| company | Yes | Company ID. | |
| projects | No | Comma-separated project IDs to filter by. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are absent, so the description carries the full burden of behavioral disclosure. It only states the action and filters, without mentioning pagination behavior, response format, permissions, or performance implications. For a list operation, this leaves the agent guessing about large result sets or required scopes.
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 sentence that front-loads the primary purpose and immediately notes optional filters. There is zero redundancy or filler, and every word contributes to the agent's understanding.
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 6 parameters and no output schema, the description is minimal. It does not explain the return shape, pagination conventions (e.g., the 'page' parameter meaning 'skip'), or how to interpret the results. While the core function is clear, an agent could benefit from a note about the list response and handling large result sets.
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 all parameters are already described in the schema. The description adds a summary of the filter options (project, name, open/closed status) which reinforces their purpose but provides no additional syntax, formatting, or interplay details 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 states a specific verb (List), resource (Time Doctor tasks), scope (in a company), and the available filters (project, name, open/closed status). It clearly distinguishes from siblings like timedoctor_get_task (singular) and timedoctor_list_projects (different resource) without 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 makes the context clear: use this to list tasks in a company, optionally filtered. It does not explicitly mention when NOT to use it or point to alternatives like get_task for a single task, but the purpose is self-evident given the sibling names. A 5 would require explicit exclusions or alternative routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
timedoctor_list_usersA
List Time Doctor users, optionally scoped to a company and filtered by email/name.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Filter: name starts with this value. | |
| page | No | Number of results to skip. | |
| No | Filter: email starts with this value. | ||
| limit | No | Maximum number of results to return. | |
| company | No | Company ID. If omitted, scope is global to the authenticated user. | |
| includeArchivedUsers | No | Include archived (hidden by default) users. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It conveys read-only listing behavior and optional company scoping, which is useful, but it does not mention pagination behavior, the default exclusion of archived users, or the global scope when company is omitted. These are partially covered by schema descriptions but not by the tool description itself.
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 front-loads the core action and resource, then immediately conveys scope and filter options. There is no redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a list operation with six fully documented optional parameters and no output schema, the description is sufficient for an agent to decide to invoke it. The schema fills in parameter-level details such as defaults and the meaning of company, page, and limit, so the description's brevity is not a critical gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3; the description does not need to repeat parameter details. It does add the high-level framing that filtering is by email/name and that company scoping is optional, but it contributes little 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 uses a specific verb ('List') and resource ('Time Doctor users'), and adds meaningful scope/filter context. It is clearly distinguishable from sibling tools like timedoctor_get_user (singular retrieval) and timedoctor_list_companies (different resource).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool—when listing users, optionally scoped by company or filtered by email/name—but it does not explicitly contrast it with alternatives like timedoctor_get_user for single-user lookups. No exclusions or alternative routing are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
11 tool updates
v0.1.0- First observed
timedoctor_check_invitation - First observed
timedoctor_get_company - First observed
timedoctor_get_project - First observed
timedoctor_get_task - First observed
timedoctor_get_timeuse_stats - First observed
timedoctor_get_user - First observed
timedoctor_get_worklog - First observed
timedoctor_list_companies - First observed
timedoctor_list_projects - First observed
timedoctor_list_tasks - First observed
timedoctor_list_users
TDQS
Scored across 11 tools
Most tools are clearly distinct by resource (companies, users, projects, tasks, worklogs, stats). The only mild overlap is between list_projects/list_tasks and get_project/get_task, but the list/get distinction is standard and clear. check_invitation is unique and well-scoped.
All tools follow a consistent timedoctor_verb_noun pattern (list/get/check). The only minor deviation is check_invitation instead of get_invitation or list_invitations, but it is still readable and consistent with the verb-first convention.
11 tools is well within the ideal range for a domain-specific server. Each tool covers a distinct resource or operation, and the count feels appropriate for Time Doctor's API surface without being bloated.
The server covers read operations well across companies, users, projects, tasks, worklogs, and stats, but lacks write operations entirely (no create/update/delete for projects, tasks, or users). For a read-only reporting/analytics server this would be complete, but the presence of check_invitation hints at broader management capabilities that are not fully covered.
Maintenance
Related MCP Connectors
Connect AI agents to 1000+ apps with managed authentication and tool-calling.
Manage Avaza projects, tasks, timesheets, expenses, invoices, and scheduling from AI assistants.
Task management for people and AI agents, with scoped OAuth access to issues, projects, and docs.
Task management for people and AI agents, with scoped OAuth access to issues, projects, and docs.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to interact with Clockify time tracking API to manage time entries, projects, tasks, and workspaces through natural language commands.22 npm5ISC
- AlicenseNot gradedqualityCmaintenanceConnects AI assistants to the TrackingTime API v4 for managing projects, tasks, and team assignments. Users can start or stop timers, log manual time entries, and organize project workflows using natural language.4 npmMIT

TrackingTime MCPofficial
FlicenseNot gradedqualityDmaintenanceConnects AI assistants to TrackingTime for querying time entries, projects, tasks, customers, and team data using natural language.4 npm-- AlicenseNot gradedqualityCmaintenanceEnables AI assistants to interact with the Toggl time tracking API to manage time entries, projects, and workspaces through natural language.22MIT