todo.vu
Server Details
Model Context Protocol server for todo.vu task management and time tracking.
- Status
- Healthy
- Last Tested
- Transport
- Streamable HTTP
- URL
Glama MCP Gateway
Connect through Glama MCP Gateway for full control over tool access and complete visibility into every call.
Full call logging
Every tool call is logged with complete inputs and outputs, so you can debug issues and audit what your agents are doing.
Tool access control
Enable or disable individual tools per connector, so you decide what your agents can and cannot do.
Managed credentials
Glama handles OAuth flows, token storage, and automatic rotation, so credentials never expire on your clients.
Usage analytics
See which tools your agents call, how often, and when, so you can understand usage patterns and catch anomalies.
Tool Definition Quality
Average 4.2/5 across 18 of 18 tools scored. Lowest: 3.5/5.
Each tool has a clearly distinct purpose. For example, add_time_entry, create_task, list_tasks, and timer target different aspects without overlap. Even combined tools like change_tasks handle batch updates, clearly separated from individual operations.
Most tools follow a verb_noun pattern (e.g., create_client, list_tasks, add_time_entry). However, task_add_comment and task_stats start with the noun, deviating from the pattern. get_health also differs, but overall consistency is maintained.
With 18 tools, the server is slightly above the typical 3-15 range but still reasonable for a domain covering tasks, clients, projects, time tracking, and workspace management. Each tool serves a clear purpose without being excessive.
The tool set covers creation and listing for main entities (clients, projects, tasks) and batch updates via change_tasks. However, missing explicit delete operations and dedicated update tools for clients and projects. Fetching single entities relies on list with ids, which is functional but less direct.
Available Tools
18 toolsadd_time_entryAInspect
Add a time entry to a task.
Args: workspace_id: Workspace slug (required). task_id: ID of the task to log time against (required). start: Start datetime (ISO 8601) in the user's local timezone, e.g. '2026-03-11T09:00:00' (required). duration: Duration of the time entry in seconds, e.g. 300 for 5 minutes. Mutually exclusive with 'end' — exactly one must be provided. end: End datetime (ISO 8601) in the user's local timezone, e.g. '2026-03-11T10:30:00'. Mutually exclusive with 'duration' — exactly one must be provided. description: Optional description of the work done. user_id: User to log time for. Defaults to the authenticated user. is_billable: Whether the time entry is billable. Defaults to True. rate: Hourly rate for billing, e.g. '150.00'.
| Name | Required | Description | Default |
|---|---|---|---|
| end | No | ||
| rate | No | ||
| start | Yes | ||
| task_id | Yes | ||
| user_id | No | ||
| duration | No | ||
| description | No | ||
| is_billable | No | ||
| workspace_id | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry full behavioral disclosure. It covers required parameters and defaults but omits error handling, authentication needs, or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is structured with an Args section and front-loaded purpose. Though somewhat lengthy, every sentence adds necessary parameter information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists, return values are covered. The description thoroughly documents parameters but lacks high-level context like typical use cases or validation behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description fully explains all 9 parameters with types, examples, constraints (mutual exclusivity), and defaults, adding significant meaning beyond names.
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 starts with 'Add a time entry to a task,' providing a clear verb and resource. It distinguishes from siblings like list_time_entries (read) and timer (alternative method).
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?
Parameter usage is detailed (e.g., mutual exclusivity of duration and end), but no explicit guidance on when to use this tool versus siblings like timer or list_time_entries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
change_tasksAInspect
Update one or more tasks by ID.
Each provided field is applied to all task IDs given. Internally, four separate API endpoints are used depending on which fields are being changed:
workflow_state → @rTasksBatchStatus (action: reopen/complete/close/snooze)
name, client_id, project_id, fuzzy_due_date, assigned_to_id, is_important → @rTasksBatchChange
description (HTML) → @rTaskEditDescription — only allowed when exactly one task ID is provided. Passing description with multiple IDs returns an error.
label_ids_add / label_ids_remove → @rBatchUpdateTaskLabels (state_diff)
Args: ids: List of task IDs to update (required). workspace_id: Workspace slug (required). workflow_state: New state — one of: active, completed, archived, snoozed. name: New task title. client_id: New client ID (or 0 to clear). project_id: New project ID (or 0 to clear). fuzzy_due_date: Due date string, e.g. 'today', 'tomorrow', '2026-04-01', or '' to clear. assigned_to_id: User ID to assign the task to. is_important: Mark the task as important or not. description: HTML description — only allowed when exactly one task ID is given. label_ids_add: List of label IDs to add to the tasks. label_ids_remove: List of label IDs to remove from the tasks. follower_ids_add: List of user IDs to add as followers. Current followers are fetched first and the lists are merged. follower_ids_remove: List of user IDs to remove from followers. Applied after follower_ids_add. bookmark: 'add' to bookmark (star) the tasks, 'remove' to unbookmark them.
| Name | Required | Description | Default |
|---|---|---|---|
| ids | Yes | ||
| name | No | ||
| bookmark | No | ||
| client_id | No | ||
| project_id | No | ||
| description | No | ||
| is_important | No | ||
| workspace_id | Yes | ||
| label_ids_add | No | ||
| assigned_to_id | No | ||
| fuzzy_due_date | No | ||
| workflow_state | No | ||
| follower_ids_add | No | ||
| label_ids_remove | No | ||
| follower_ids_remove | No |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description effectively discloses internal API routing, batch behavior, parameter constraints, and follower merging. It adds significant behavioral context beyond basic semantics, though it omits error handling or idempotency details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear purpose, internal details, and parameter list. While lengthy, every sentence adds value. Minor brevity improvements are possible, but it remains efficient for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's 15 parameters, batch mutation behavior, and output schema existence, the description covers all critical aspects: constraints, internal endpoints, and parameter semantics. It is fully adequate for an AI agent to correctly invoke the 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?
All 15 parameters are described with examples, allowed values, and constraints (e.g., 'fuzzy_due_date' examples, 'description' single-ID limit, follower merge logic). This is far beyond the schema which has 0% coverage, fully compensating for the gap.
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 'Update one or more tasks by ID,' specifying the action and resource. The description further explains batch application and internal API endpoints, making the tool's purpose distinct from siblings like create_task or list_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?
Provides clear context for use, including constraints like description only working with a single ID and follower merge behavior. However, it does not explicitly state when to avoid this tool or compare to alternatives, missing a full exclusion guideline.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
create_clientAInspect
Create a new client in the workspace.
Only name is required. Contact details (first_name, last_name, email,
phone, mobile) and address fields are all optional.
Args: workspace_id: Workspace slug (required). name: Client/company name (required). email: Primary contact email address. phone: Phone number. mobile: Mobile phone number. website: Website URL. city: City. state: State or region. country: Country. postcode: Postcode / ZIP code. street_address: Street address line 1. street_address2: Street address line 2. fax: Fax number. currency_code: Billing currency code, e.g. 'USD', 'AUD'. first_name: Primary contact first name. last_name: Primary contact last name.
| Name | Required | Description | Default |
|---|---|---|---|
| fax | No | ||
| city | No | ||
| name | Yes | ||
| No | |||
| phone | No | ||
| state | No | ||
| mobile | No | ||
| country | No | ||
| website | No | ||
| postcode | No | ||
| last_name | No | ||
| first_name | No | ||
| workspace_id | Yes | ||
| currency_code | No | ||
| street_address | No | ||
| street_address2 | No |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. The description lacks details on side effects, permissions, idempotency, or error conditions. Only states the action without 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 with brief intro and Args list. Sentences are efficient, though slightly verbose with full parameter list. Front-loaded with purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 16 parameters, 0% schema coverage, and no annotations, description covers parameter meanings but lacks behavioral details. Output schema may compensate for 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 0%, but description adds meaningful explanations for each parameter (e.g., 'Workspace slug', 'Primary contact email address'). Value is added beyond raw 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 'Create a new client in the workspace' with clear verb and resource. It distinguishes from siblings like list_clients by specifying creation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implicit usage for client creation, but no explicit guidance on when to avoid or alternatives. The context signals show siblings but description doesn't leverage them.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
create_projectAInspect
Create a new project in the workspace.
Only name is required. The project will be created in the 'active'
workflow state. Use the client_id parameter to associate the project
with an existing client.
Note: The API also accepts a blocks field for rich-text project
description (Slate JSON format), which is not exposed here. Use
project_details / a direct API call to set rich-text content
after creation if needed.
Args: workspace_id: Workspace slug (required). name: Project name (required). client_id: Associate the project with this client ID. time_budget: Time budget for the project as a duration string, e.g. '10:00:00' (10 hours) or '02:30:00' (2.5 hours).
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| client_id | No | ||
| time_budget | No | ||
| workspace_id | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries burden. Discloses default workflow state and limitation of blocks field, but does not mention permissions, side effects, or whether creation is reversible. Adequate but could be more comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Efficiently structured: clear opening sentence followed by bulleted args. No redundant information; every sentence adds value. The note about blocks is helpful and concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers required/optional parameters, workflow state, and workaround for rich-text. Lacks response description, but output schema exists. Sufficient for accurate tool invocation, but could mention prerequisites or error conditions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema coverage, description fully explains all 4 parameters: workspace_id (slug), name (required), client_id (associate), time_budget (duration string with example). Provides usage context beyond schema types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a new project in the workspace', specifying the verb and resource. It distinguishes from sibling tools like create_task and create_client by focusing on project creation, and notes the required fields and default workflow state.
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 explicit guidelines: only name is required, use client_id to associate with existing client, and mentions the limitation of rich-text blocks with an alternative. Lacks explicit comparison to siblings but is sufficiently directive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
create_taskAInspect
Create a new task in the workspace.
Creates an active task. All fields except name and workspace_id are optional.
Args: workspace_id: Workspace slug (required). name: Task name/title (required). client_id: Associate the task with this client. project_id: Associate the task with this project. assigned_to_id: User ID to assign the task to. fuzzy_due_date: Due date string, e.g. 'today', 'tomorrow', '2026-04-01'. is_important: Mark the task as important (default: False). is_private: Make the task private (default: False).
details: HTML task description.
labels: List of label IDs to attach to the task.
followers: List of user IDs to add as followers.
creator_id: Override the creator user ID (defaults to the authenticated user).| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| labels | No | ||
| details | No | ||
| client_id | No | ||
| followers | No | ||
| creator_id | No | ||
| is_private | No | ||
| project_id | No | ||
| is_important | No | ||
| workspace_id | Yes | ||
| assigned_to_id | No | ||
| fuzzy_due_date | No |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It explains that the task is created active, provides default values for is_important, is_private, and creator_id, and clarifies the fuzzy_due_date format. However, it does not mention permissions or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a brief intro, a note about optional fields, then a parameter list. Every sentence adds value with no redundancy or 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?
All 12 parameters are described with semantics. The output schema exists, so the description does not need to cover return values. The description is complete for a creation tool with many optional fields.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It lists all 12 parameters with detailed explanations, including examples for fuzzy_due_date, default values, and the meaning of each field, adding significant value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a new task in the workspace' with a specific verb and resource. It distinguishes from siblings like 'change_tasks' by explicitly focusing on creation, and the parameter list reinforces that it is for new 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 indicates required vs optional fields and notes that the task is created as active. It implies when to use the tool but does not explicitly contrast with alternatives like 'change_tasks' for updates or 'list_tasks' for reading.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_healthAInspect
Get the health status of the todo.vu MCP server.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It only says 'get health status' without mentioning authentication needs, side effects, or performance characteristics. Minimal transparency beyond the name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, perfectly concise. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters, presence of output schema, and low complexity, the description fully covers what the tool does. No gaps for a health status endpoint.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, and schema coverage is 100%. The description adds no extra meaning, but baseline for 0 params is 4. It correctly implies no input needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb 'Get' and resource 'health status of the todo.vu MCP server'. It uniquely identifies the tool's purpose among siblings, as no other tool addresses health.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool vs alternatives. However, its purpose as a health check is implied and typically used for monitoring or before other calls. No exclusions or context provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_clientsAInspect
List clients in the workspace.
Returns a lean JSON object with client summaries (id, name, workflow_state)
by default. Use the fields parameter to request more detail.
Clients are grouped into sections: recent, active, archived.
By default all sections are merged (recent first, then active, then
archived), deduplicated. Use only to restrict to a single section.
When ids is provided, specific clients are fetched directly. ids is
mutually exclusive with search, sort_by, sort_order, and only.
Args: workspace_id: Workspace slug (required). ids: Fetch specific clients by ID. Mutually exclusive with search, sort_by, sort_order, only. fields: List of fields to return. Defaults to [id, name, workflow_state] when omitted. Available fields: id, name, workflow_state, email, phone, mobile, website, city, state, country, postcode, street_address, street_address2, portrait_url, default_assignee_id, follower_ids, contact_ids, active_project_ids, current_user_can_edit, task_counts_by_workflow_state, time_stats, time_spent_per_user, charges_stats, uninvoiced_duration, blocks, num_projects, num_important_tasks, num_overdue_tasks, num_tasks_by_workflow. limit: Maximum number of clients to return (default: 50). search: Free-text search query (filters by client name). sort_by: Sort field — one of: name, projects, todo, important, overdue. sort_order: Sort direction — asc or desc. only: Return only clients from this section: recent, active, or archived.
| Name | Required | Description | Default |
|---|---|---|---|
| ids | No | ||
| only | No | ||
| limit | No | ||
| fields | No | ||
| search | No | ||
| sort_by | No | ||
| sort_order | No | ||
| workspace_id | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It clearly explains the default return format, section merging, deduplication, and parameter interactions. It does not disclose auth requirements or rate limits, but for a read tool this is adequate.
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 quite detailed but well-structured, starting with core behavior and then parameter descriptions. It is front-loaded with key information. The parameter list is lengthy but each entry earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (8 parameters, no annotations, no schema descriptions), the description covers most aspects: purpose, input semantics, grouping behavior, and defaults. Minor omissions include pagination and error handling, but overall very complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must fully explain each parameter. It does so comprehensively: defaults, mutual exclusivity for ids, available fields for fields parameter, sort options, and section restrictions. Adds significant value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'List clients in the workspace,' which is a specific verb+resource combination. It is easily distinguished from sibling tools like create_client and list_projects.
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 extensive usage context, including default behavior, mutual exclusivity of parameters, section grouping, and how to request more detail. However, it does not explicitly mention when not to use this tool or compare to alternative list tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_comments_attachments_time_entriesAInspect
List comments, attachments, and time entries for a specific task.
This tool retrieves the timeline of interactions (comments, attachments, time entries) for a task.
Args: workspace_id: The workspace slug. task_id: The ID of the task.
Returns: A dictionary containing lists of hydrated comments, attachments, time_entries, and a unified timeline preserving the original order.
| Name | Required | Description | Default |
|---|---|---|---|
| task_id | Yes | ||
| workspace_id | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must convey behavioral traits. It describes the return format (hydrated objects + timeline) but does not mention read-only nature, auth needs, or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with only four sentences, well-structured with Args and Returns sections, and contains no redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists, the description adequately covers purpose, parameters, and return structure. It could mention read-only behavior for completeness, but is sufficient for a 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?
With 0% schema description coverage, the description adds meaning by clarifying workspace_id as a 'workspace slug' and task_id as 'ID of the task'. This fills the gap left by the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists comments, attachments, and time entries for a specific task, and highlights the unified timeline. This distinguishes it from sibling tools like list_time_entries which only list one 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 usage for retrieving all interaction types for a task, but lacks explicit guidance on when to choose this over individual list tools or any pre-conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_labelsAInspect
List task labels available in the workspace.
When label_ids is provided, fetches those specific labels via the
LabelFetcher API. When search is provided, queries the task_labels
endpoint with a search filter. The two parameters are mutually exclusive.
Args: workspace_id: Workspace slug (required). search: Optional search string to filter labels by name. label_ids: Optional list of label IDs to fetch directly.
| Name | Required | Description | Default |
|---|---|---|---|
| search | No | ||
| label_ids | No | ||
| workspace_id | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Since no annotations are provided, the description carries full burden. It mentions the underlying API endpoints (LabelFetcher vs task_labels) and implies read-only behavior ('List'), but does not explicitly state it is non-destructive or safe.
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 a brief summary followed by a clear parameter list. Every sentence adds value and is front-loaded with the main purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema, the description adequately covers input parameters and usage modes. It lacks mention of pagination or limits, but these are not critical for a simple list 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?
With 0% schema description coverage, the description fully compensates by explaining each parameter's purpose, including the required workspace_id and the optional search and label_ids, along with their usage context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List task labels available in the workspace' and distinguishes two usage modes (by label_ids or search), making the tool's purpose specific and distinct from sibling tools like list_projects or list_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 explains when to use each mode (label_ids vs search) and notes mutual exclusivity, but does not explicitly contrast with alternative tools or provide when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_projectsAInspect
List projects in the workspace.
Returns project summaries with fields [id, name, workflow_state, client_id]
by default. Use the fields parameter to request more detail.
Projects are grouped into sections: recent, all, active, archived.
By default all sections are merged (recent first, then the rest from all),
deduplicated. Use only to restrict to a single section.
When ids is provided, specific projects are fetched directly. ids is
mutually exclusive with search, sort_by, sort_order, client_id, and only.
A referenced block lists unique client_ids seen across the returned
projects, so callers can fetch client details in one follow-up call.
Args: workspace_id: Workspace slug (required). ids: Fetch specific projects by ID. Mutually exclusive with search, sort_by, sort_order, client_id, only. fields: List of fields to return. Defaults to [id, name, workflow_state, client_id] when omitted. Available fields: id, name, workflow_state, client_id, is_fixed_price, is_private, follower_ids, time_budget, task_counts_by_workflow_state, blocks, time_stats, time_spent_per_user, charges_stats. Note: time_stats, time_spent_per_user, and charges_stats are computed server-side and may be slower to fetch. limit: Maximum number of projects to return (default: 50). search: Free-text search query (filters by project name). sort_by: Sort field — one of: name, client_name, tasks_todo, time_spent, time_remaining. sort_order: Sort direction — asc or desc. client_id: Filter to return only this client's projects. only: Return only projects from this section: recent, all, active, or archived.
| Name | Required | Description | Default |
|---|---|---|---|
| ids | No | ||
| only | No | ||
| limit | No | ||
| fields | No | ||
| search | No | ||
| sort_by | No | ||
| client_id | No | ||
| sort_order | No | ||
| workspace_id | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite no annotations, the description discloses behavioral traits such as section deduplication, a `referenced` block for client IDs, and performance warnings for computed fields. This adds value beyond a simple listing.
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 opening, followed by logical groups explaining sections, parameters, and output. It is comprehensive without redundancy, earning its length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (9 parameters, output schema exists), the description covers all necessary aspects: required workspace_id, optional filters, sorting, field selection, and output behavior (referenced block). 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?
With 0% schema description coverage, the description fully compensates by detailing each parameter: defaults, mutual exclusivity, available fields for `fields`, and sort options. The `fields` parameter lists all options and notes performance implications.
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 begins with 'List projects in the workspace,' specifying the verb and resource. It distinguishes itself from sibling tools like create_project and list_tasks by focusing on listing projects, and it provides context about section grouping and default fields.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use parameters like `only` to restrict sections and `ids` for specific projects, noting mutual exclusivity. It lacks explicit 'when not to use' guidance, but the context is clear enough for an AI agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_tasksAInspect
List and filter tasks from the workspace task dashboard.
Returns a structured JSON object containing tasks and the IDs of referenced objects (users, clients, projects, labels) that can be fetched separately.
Args:
workspace_id: Workspace slug (required).
ids: Fetch specific tasks by ID, bypassing the dashboard query.
Mutually exclusive with all filter parameters.
fields: Fields to request from the fetch API.
If omitted, defaults to id, name, workflow_state,
is_important, due_date, client_id, project_id.
Available fields:
id, name, workflow_state, is_important, is_private,
is_bookmarked, is_viewed, is_fixed_price, created,
due_date, fuzzy_due_date, snoozed_until_date,
assigned_to_id, creator_id, on_behalf_of_id,
client_id, project_id, label_ids, follower_ids,
checklist_item_ids, checklist_items_completed,
checklist_items_total, comment_ids, attachment_ids,
time_entry_ids, dependent_task_ids, depends_on_id,
time_budget, total_duration, has_billed_time_entries,
series_id, rrule, details, blocks.
limit: Maximum number of tasks to return (default: 50).
search: Free-text search query.
user_mode: Scope of tasks to include. One of: assigned, created, following,
interacted, personal (default: assigned). Determines the exact
meaning of the user_id parameter; e.g. created returns tasks
created by the user, assigned returns tasks assigned to the user.
user_id: Filter tasks by a specific user ID.
client_id: Filter tasks by a specific client ID.
project_id: Filter tasks by a specific project ID.
label_id: Filter tasks by a specific label ID.
by_time: Filter by time bucket, e.g. 'today' or 'week'.
only: Return tasks from a single dashboard section only. One of:
active, completed, overdue, important, unread, snoozed.
When omitted, tasks from all sections are merged in priority order.
bookmarked: Return only bookmarked tasks (default: False).
todo_sort: Sort order for active tasks. One of: manual, last_modified
(default: manual).
recent: If True, fetch recently interacted tasks,
ordered by most-recent interaction first.
Supports search, client_id, project_id, and limit;
other filter params (mode, user_id, label_id, by_time,
only, bookmarked) are not applicable and ignored.
An action field is added to every returned task
regardless of the fields requested (e.g. 'logged time',
'VIEWED', or None for catch-all entries).
Mutually exclusive with ids.
| Name | Required | Description | Default |
|---|---|---|---|
| ids | No | ||
| only | No | ||
| limit | No | ||
| fields | No | ||
| recent | No | ||
| search | No | ||
| by_time | No | ||
| user_id | No | ||
| label_id | No | ||
| client_id | No | ||
| todo_sort | No | manual | |
| user_mode | No | assigned | |
| bookmarked | No | ||
| project_id | No | ||
| workspace_id | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully covers behavioral traits: return format (JSON with tasks and referenced IDs), parameter constraints (mutually exclusive, ignored under conditions), and special behavior like the 'recent' parameter adding an 'action' field. 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 (purpose, return description, parameter list). Each sentence adds value; no redundant or vague statements.
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 (15 parameters, 1 required) and absence of annotations, the description is complete. Covers return format, parameter interactions, defaults, edge cases, and even mentions fields and 'recent' behavior. Output schema exists, but description still adds context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description provides exhaustive details for all 15 parameters, including defaults, allowed values, constraints, and interactions. Adds significant meaning beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the verb (list/filter) and resource (tasks from workspace dashboard). Distinguishes from sibling tools like create_task and change_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?
Provides detailed guidance on parameter usage, including mutual exclusivity (ids vs filters), defaults, and behaviors like 'recent' ignoring certain filters. Lacks explicit mention of when to use alternative tools, but the context of sibling names implies it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_time_entriesAInspect
List time entries, either by direct IDs or by filter criteria.
Args: workspace_id: Workspace slug (required). ids: List of time entry IDs to fetch directly. Mutually exclusive with all filter parameters. start: Filter entries starting on or after this datetime (ISO 8601) in the user's local timezone. Must be provided together with end. end: Filter entries starting before this datetime (ISO 8601) in the user's local timezone. Must be provided together with start. task_id: Restrict to a specific task. When specified, client_id, project_id and label_id must not be provided. client_id: Restrict to tasks belonging to this client. Cannot be used together with task_id. project_id: Restrict to tasks belonging to this project. Cannot be used together with task_id. label_id: Restrict to tasks tagged with this label. Cannot be used together with task_id. user_id: Restrict to entries logged by this user. uninvoiced: Include uninvoiced billable entries (default True). invoiced_draft: Include entries in draft invoice reports (default True). invoiced_sent: Include entries in sent invoice reports (default True). nonbillable: Include non-billable entries (default True).
Returns: A dict with: - time_entries: List of time entry objects with fields: id, task_id, user_id, start, end, duration, description, is_billable, rate, amount, invoice_workflow_state, invoice_report_id, invoice_external_id. start and end are ISO 8601 strings in the user's local timezone. - totals: Summary dict with: - number_of_time_entries: Count of entries returned. - duration: Total duration in seconds. - amount: Total billable amount (sum of non-null amounts), rounded to 2 decimal places. - tasks: Per-task aggregation, sorted by task_id. Each entry has: - task_id: The task ID. - number_of_time_entries: Count of time entries for this task. - duration: Total duration in seconds for this task. - amount: Total amount for this task (sum of non-null values), rounded to 2 decimal places. - timezone: The user's local timezone name (e.g. 'Australia/Brisbane').
| Name | Required | Description | Default |
|---|---|---|---|
| end | No | ||
| ids | No | ||
| start | No | ||
| task_id | No | ||
| user_id | No | ||
| label_id | No | ||
| client_id | No | ||
| project_id | No | ||
| uninvoiced | No | ||
| nonbillable | No | ||
| workspace_id | Yes | ||
| invoiced_sent | No | ||
| invoiced_draft | No |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses behavior: filtering logic, defaults (e.g., uninvoiced defaults to True), timezone handling, and returns a detailed dict. However, it does not mention pagination, error handling, or rate limits, which are relevant for a listing tool. Still, it provides substantial transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is fairly long but well-structured with clear sections (Args, Returns) and bullet points. Every sentence provides unique value, though it could be slightly trimmed without loss of clarity. The structure aids readability and earns a 4.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 13 parameters, no annotations, and no output schema (but context says 'Has output schema: true'; the description includes a detailed return format). The description covers all parameters with dependencies and return fields, making it fully complete for its complexity. No gaps are apparent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains every parameter in detail, including constraints, mutual exclusivity, and defaults. For example, 'start: Filter entries starting on or after this datetime... Must be provided together with end.' This fully compensates for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with 'List time entries, either by direct IDs or by filter criteria,' which clearly states the verb and resource. It distinguishes two modes, making it specific and differentiating it from analogous list tools like list_projects or list_tasks, though not explicitly. This level of specificity earns a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides detailed guidance on parameter combinations and mutual exclusivity, e.g., 'ids... Mutually exclusive with all filter parameters' and 'Must be provided together with end.' It also explains when parameters cannot be used together. However, it lacks explicit guidance on when to prefer this tool over siblings (e.g., list_projects) or general usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_usersAInspect
List users from the workspace.
Args: workspace_id: Workspace slug (required). ids: Explicit list of user IDs to fetch. Mutually exclusive with all other filter parameters (kind, search, sort_order, only, client_id). kind: Which users to return. One of: - 'team' (default): admins and staff via @rTeamDashboard. - 'contacts': client contacts via @rContactDashboard. - 'both': team members and contacts combined. limit: Maximum number of users to return (default: 50). search: Free-text search query. sort_order: Sort direction — asc or desc. only: Return users from a single section only: active or inactive. When omitted, active users are listed first, then inactive. client_id: Filter contacts by a specific client ID. Only valid when kind='contacts'.
| Name | Required | Description | Default |
|---|---|---|---|
| ids | No | ||
| kind | No | team | |
| only | No | ||
| limit | No | ||
| search | No | ||
| client_id | No | ||
| sort_order | No | ||
| workspace_id | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not explicitly state that the tool is read-only or safe. It implies listing behavior but omits details like side effects, permissions, or rate limits. Given the absence of annotations, this is a 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 front-loaded with the one-liner and uses a clear docstring format. While lengthy due to 8 parameters, every sentence adds value. Minor redundancy with schema defaults is acceptable given schema descriptions are missing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (8 parameters, no annotations, output schema exists), the description is thorough. It covers all parameters but omits behavioral details like error handling or pagination behavior, though limit implies pagination.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description fully compensates by explaining every parameter, including enum values for kind, mutual exclusivity, and conditional validity. This adds critical meaning beyond the raw 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 starts with 'List users from the workspace,' a specific verb and resource. While it doesn't explicitly differentiate from siblings like list_clients, the resource 'users' is distinct enough for an agent to infer 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?
The description provides clear internal usage guidance for parameters, e.g., mutual exclusivity of ids, and constraints like client_id only valid with kind='contacts'. However, it lacks cross-sibling guidance, such as when to use list_users over list_clients.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_workspacesAInspect
List all workspaces the current user has access to.
Args: ids: Only return workspaces whose ID matches one of these values. search: Case-insensitive substring filter applied to workspace id and company_name.
Returns: A dictionary with: - workspaces: list of workspace objects, each with id, company_name, logged_in_user_id, num_unread_notifications, portrait_url, and url. - total: total number of workspaces after filtering.
| Name | Required | Description | Default |
|---|---|---|---|
| ids | No | ||
| search | No |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description provides useful behavioral context: it lists workspaces accessible to the current user, explains filtering via ids and search (including case-insensitivity and fields searched), and details the return structure. However, it does not mention potential pagination or limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear purpose sentence, followed by Args and Returns sections. Every sentence adds value, with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with two optional filters, the description fully covers purpose, parameter behavior, and return structure. The presence of an output schema does not detract; the description's return details align well.
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% (no parameter descriptions in schema). The description compensates by explaining each parameter: 'ids: Only return workspaces whose ID matches one of these values.' and 'search: Case-insensitive substring filter applied to workspace id and company_name.' This adds meaningful guidance beyond type/default.
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: 'List all workspaces the current user has access to.' It uses a specific verb (list) and resource (workspaces), and implicitly distinguishes from siblings like list_projects or list_clients.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives. It does not mention when not to use it or compare to related list tools. The description only states what it does, not the decision criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
repeat_taskAInspect
Set, update, or remove the recurrence rule for a task.
Args: workspace_id: Workspace slug (required). task_id: ID of the task to set the recurrence rule on (required). period: Recurrence frequency — one of: daily, weekly, monthly, yearly, never (required). Use 'never' to remove the recurrence rule. interval: Repeat every N periods (default: 1). until: ISO 8601 datetime string; recurrence ends on or before this date. byhour: Hour of the desired local due time (0–23). byminute must also be provided when this is set. byminute: Minute of the desired local due time (0–59). Only used when byhour is set. timezone: Timezone name, e.g. 'Australia/Brisbane'. Defaults to the user's timezone when omitted.
Weekly-only parameters:
byweekday: Day-of-week index (Monday=0, Sunday=6) or list of indices.
byweek: Controls exact frequency/position within the month. One of:
'every_week', 'every_2_weeks', 'every_4_weeks',
'first_week', 'second_week', 'third_week', 'last_week'.
Monthly-only parameters:
bymonthday: Day(s) of the month on which the task recurs (default: 1).
Shared weekly/monthly/yearly parameter:
bymonth: Calendar month (0-based, 0=January) or list of months.
For yearly it is a single int and is required.
Yearly-only parameters:
bymonth: (int, required for yearly) Calendar month (0-based).
bymonthday: (int, required for yearly) Day of the month.| Name | Required | Description | Default |
|---|---|---|---|
| until | No | ||
| byhour | No | ||
| byweek | No | ||
| period | Yes | ||
| bymonth | No | ||
| task_id | Yes | ||
| byminute | No | ||
| interval | No | ||
| timezone | No | ||
| byweekday | No | ||
| bymonthday | No | ||
| workspace_id | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full burden. It discloses that the tool can set, update, or remove recurrence rules and includes parameter behaviors like defaults and dependencies. However, it lacks discussion of side effects, idempotency, auth needs, or rate limits. Adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but well-structured, with clear sections for weekly-only, monthly-only, and yearly-only parameters. It is front-loaded with the purpose. Could be slightly more concise, but the length is justified given the parameter complexity and lack of schema descriptions.
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 (12 parameters, no schema descriptions, no annotations), the description is remarkably complete. It covers all parameters, usage conditions, defaults, and dependencies. An output schema exists but is not needed for completeness per guidelines.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description fully compensates by providing extensive details for each parameter including allowed values, defaults, conditional requirements (e.g., byminute must be set with byhour), and grouping by period. Adds significant meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Set, update, or remove' and the resource 'recurrence rule for a task', distinguishing it from sibling tools like change_tasks by focusing specifically on recurrence. The purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives such as change_tasks. While it explains how to remove recurrence via period='never', it does not provide context for choosing between tools or when not to use this one.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
task_add_commentAInspect
Add a comment to a task.
Either comment (HTML string) or blocks (rich-text block list) must be
provided. When both are supplied, blocks takes precedence.
Args:
workspace_id: Workspace slug (required).
task_id: ID of the task to comment on (required).
comment: HTML content of the comment.
blocks: Rich-text block list (takes precedence over comment).
is_staff_only: Whether the comment is visible to staff only (default: False).
| Name | Required | Description | Default |
|---|---|---|---|
| blocks | No | ||
| comment | No | ||
| task_id | Yes | ||
| workspace_id | Yes | ||
| is_staff_only | No |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full transparency burden. It explains the precedence between comment and blocks, but does not disclose side effects, permissions required, error behavior (e.g., invalid task_id), or whether the comment is appended or replaces existing comments.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is reasonably concise, using a paragraph with a bullet-like list for args. It could be slightly more concise but is well-structured with key information front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the existence of an output schema, the description does not need to explain return values. It covers the core functionality and parameters. However, it lacks error context, permissions, and does not mention if the comment is added immediately or asynchronously. The tool has moderate complexity (5 params) and seems adequately described but not exhaustive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explains all 5 parameters: workspace_id, task_id, comment, blocks, is_staff_only. It clarifies that either comment or blocks must be provided and that blocks takes precedence. Since schema coverage is 0%, the description adds significant meaning beyond types.
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 with the verb 'Add' and the resource 'comment to a task'. It is specific, but it does not distinguish from sibling list_tools like list_comments_attachments_time_entries, though the verb 'add' implies creation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the two ways to provide content (comment vs blocks) and their precedence, which is helpful. However, it does not explicitly state when to use this tool versus alternatives like list_comments_attachments_time_entries or other mutation tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
task_statsAInspect
Return task counts and time/money statistics for tasks in the workspace.
Aggregates task data matching the given filters without fetching individual task records.
Args:
workspace_id: Workspace slug (required).
user_mode: Scope of tasks to aggregate. One of: assigned, created,
following, interacted, personal (default: assigned). user_mode parameter determines
the exact meaning of the user_id parameter, for example
created mode aggregates tasks created by the user,
while assigned mode aggregates tasks assigned to the user.
user_id: Restrict aggregation to tasks related to this user ID.
search: Free-text search query.
client_id: Restrict aggregation to tasks belonging to this client.
project_id: Restrict aggregation to tasks belonging to this project.
label_id: Restrict aggregation to tasks with this label.
by_time: Filter by time bucket, e.g. 'today' or 'week'.
wf: Workflow state filter, e.g. 'active' or 'completed'.
'todo' is an alias for 'active'; 'done' is an alias for 'completed'.
Returns a dictionary with the following keys:
Counts (list of {id, count} objects): counts_by_user: Task counts grouped by user (based on user_mode). counts_by_client: Task counts grouped by client. counts_by_project: Task counts grouped by project. counts_by_label: Task counts grouped by label.
Workflow counts (dict {state_id: count}): counts_by_workflow: Task counts grouped by workflow state.
Time/money stats (dict {status: value}): time_by_billing_state: Total duration grouped by billing status (e.g. 'billed', 'unbilled', 'nonbillable'). money_by_billing_state: Total amount grouped by billing status.
| Name | Required | Description | Default |
|---|---|---|---|
| wf | No | ||
| search | No | ||
| by_time | No | ||
| user_id | No | ||
| label_id | No | ||
| client_id | No | ||
| user_mode | No | assigned | |
| project_id | No | ||
| workspace_id | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It clearly explains the tool is read-only (aggregates without fetching individual records) and details the return structure including counts and stats. However, it does not mention potential side effects, rate limits, or data freshness, which would elevate it to a 5.
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 statement, parameter list, and return value breakdown. It is front-loaded. While it is relatively long, most information is relevant. Minor redundancy (e.g., repeating 'user_mode' explanation) prevents a perfect score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 9 parameters, no annotations, and a detailed output, the description covers all aspects: all parameters are explained, return values are documented with structure examples, and behavior (aggregation only) is clear. The output schema is described in detail, making the tool fully understandable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description fully compensates by explaining each parameter in detail, including valid values for 'user_mode' and how it interacts with 'user_id', aliases for 'wf' filter, and meanings of all filter parameters. This adds significant meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns aggregated task counts and time/money statistics without fetching individual records. It uses specific verbs ('Return', 'Aggregates') and identifies the resource ('task data'). Distinguishes from sibling tools like 'list_tasks' by emphasizing aggregation.
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 or provide 'when not to use' guidance. It implies usage for aggregated statistics, but lacks direct comparison to siblings. The hint about not fetching individual records is useful but not sufficient for full usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
timerAInspect
Manage the running timer for the current user in a workspace.
A user can have one timer running per workspace. All operations return the list of active timers in the workspace.
Args: workspace_id: Workspace slug (required). operation: One of: - 'start': Start the timer. Optionally set task_id, timer_started, and description. - 'stop': Stop the running timer and emit a time entry. Optionally pass task_id to override the task, or pause=True to pause without clearing the task. - 'change': Update the running timer. Supply any of task_id, description, timer_started — only the provided fields are updated. - 'discard': Discard the running timer without saving a time entry. - 'list': Return current active timers (no changes made). task_id: Task ID to associate with the timer. Used by start, stop, and change. description: Timer description. Used by start and change. timer_started: ISO 8601 datetime string for when the timer started, e.g. '2026-03-12T09:00:00' (in the user's local timezone). Used by start and change. pause: If True, pause the timer (keeps task ID but clears start time). Only valid for stop.
| Name | Required | Description | Default |
|---|---|---|---|
| pause | No | ||
| task_id | No | ||
| operation | Yes | ||
| description | No | ||
| workspace_id | Yes | ||
| timer_started | No |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It fully discloses behavior: one timer per workspace, effects of each operation, and pause behavior. This is comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with bullet points for operations, but it is somewhat lengthy. However, every sentence adds value, and the key information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (6 parameters, 5 operations), the description is complete. It explains return behavior (list of active timers) and covers all edge cases like pause and discard.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% coverage for parameter descriptions. The description compensates by explaining each parameter's purpose, valid operations, and format (e.g., timer_started ISO 8601). This adds significant meaning beyond the schema types.
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 manages the running timer for the current user in a workspace, with a specific verb and resource. It distinguishes itself from sibling tools like add_time_entry and list_time_entries by focusing on timer operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides detailed guidance on each operation (start, stop, change, discard, list) and when to use optional parameters. It lacks explicit exclusions or alternatives, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Claim this connector by publishing a /.well-known/glama.json file on your server's domain with the following structure:
{
"$schema": "https://glama.ai/mcp/schemas/connector.json",
"maintainers": [{ "email": "your-email@example.com" }]
}The email address must match the email associated with your Glama account. Once published, Glama will automatically detect and verify the file within a few minutes.
Control your server's listing on Glama, including description and metadata
Access analytics and receive server usage reports
Get monitoring and health status updates for your server
Feature your server to boost visibility and reach more users
For users:
Full audit trail – every tool call is logged with inputs and outputs for compliance and debugging
Granular tool control – enable or disable individual tools per connector to limit what your AI agents can do
Centralized credential management – store and rotate API keys and OAuth tokens in one place
Change alerts – get notified when a connector changes its schema, adds or removes tools, or updates tool definitions, so nothing breaks silently
For server owners:
Proven adoption – public usage metrics on your listing show real-world traction and build trust with prospective users
Tool-level analytics – see which tools are being used most, helping you prioritize development and documentation
Direct user feedback – users can report issues and suggest improvements through the listing, giving you a channel you would not have otherwise
The connector status is unhealthy when Glama is unable to successfully connect to the server. This can happen for several reasons:
The server is experiencing an outage
The URL of the server is wrong
Credentials required to access the server are missing or invalid
If you are the owner of this MCP connector and would like to make modifications to the listing, including providing test credentials for accessing the server, please contact support@glama.ai.
Discussions
No comments yet. Be the first to start the discussion!