ClickUp MCP Server

get_time_tracked

Retrieve tracked time data for tasks within a specified date range to analyze team productivity and project progress in ClickUp.

Instructions

Get time tracked for tasks

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "get_time_tracked"
  }
}

Input Schema

Name	Required	Description
`user_id`	No	User ID
`start_date`	No	Start date (ISO 8601)
`end_date`	No	End date (ISO 8601)

Implementation Reference

src/clickup_mcp/tools.py:1072-1116 (handler)

The main handler function for the 'get_time_tracked' tool. It retrieves time entries from the ClickUp API for a given user and date range (defaulting to last 7 days), calculates total time in ms and hours, and returns a summary.

async def get_time_tracked(
    self,
    user_id: Optional[int] = None,
    start_date: Optional[str] = None,
    end_date: Optional[str] = None,
) -> Dict[str, Any]:
    """Get time tracked for tasks."""
    # If no dates provided, default to last 7 days
    if not start_date:
        start_date = (datetime.now() - timedelta(days=7)).isoformat()
    if not end_date:
        end_date = datetime.now().isoformat()

    start_ts = int(datetime.fromisoformat(start_date.replace("Z", "+00:00")).timestamp() * 1000)
    end_ts = int(datetime.fromisoformat(end_date.replace("Z", "+00:00")).timestamp() * 1000)

    # Get time entries
    params = {
        "start_date": str(start_ts),
        "end_date": str(end_ts),
    }
    if user_id:
        params["assignee"] = str(user_id)

    workspace_id = self.client.config.default_workspace_id
    if not workspace_id:
        workspaces = await self.client.get_workspaces()
        workspace_id = workspaces[0].id

    data = await self.client._request(
        "GET", f"/team/{workspace_id}/time_entries", params=params
    )

    total_ms = sum(entry.get("duration", 0) for entry in data.get("data", []))
    total_hours = total_ms / (1000 * 60 * 60)

    return {
        "total_milliseconds": total_ms,
        "total_hours": round(total_hours, 2),
        "entries": len(data.get("data", [])),
        "period": {
            "start": start_date,
            "end": end_date,
        },
    }

src/clickup_mcp/tools.py:368-380 (schema)

The Tool schema definition for 'get_time_tracked', specifying input parameters: optional user_id, start_date, end_date as strings in ISO 8601 format.

Tool(
    name="get_time_tracked",
    description="Get time tracked for tasks",
    inputSchema={
        "type": "object",
        "properties": {
            "user_id": {"type": "integer", "description": "User ID"},
            "start_date": {"type": "string", "description": "Start date (ISO 8601)"},
            "end_date": {"type": "string", "description": "End date (ISO 8601)"},
        },
    },
),
Tool(

src/clickup_mcp/tools.py:45-45 (registration)
Registration of the 'get_time_tracked' tool name mapped to its handler method in the ClickUpTools class _tools dictionary.
```
"get_time_tracked": self.get_time_tracked,
```

Schema Changelog

Changes observed during successful MCP inspections.

First observedAug 15, 2025

TDQS

C2.6/5.0

Behavior2/5

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 time tracked for tasks,' implying a read-only operation, but doesn't specify whether it requires permissions, how data is returned (e.g., format, pagination), or any rate limits. This leaves significant gaps in understanding the tool's behavior beyond the basic action.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence ('Get time tracked for tasks') that directly states the purpose without unnecessary words. It's appropriately sized for a simple tool, though it could be slightly more informative without losing conciseness. There's no wasted text, making it front-loaded and clear.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity (3 parameters, no output schema, and no annotations), the description is incomplete. It lacks details on return values (e.g., format of tracked time data), error handling, or behavioral traits like authentication needs. While the schema covers parameters well, the overall context for effective tool use is insufficient, especially for a read operation with potential data sensitivity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% description coverage, clearly documenting 'user_id,' 'start_date,' and 'end_date' with their types and formats. The description adds no additional meaning beyond the schema, such as explaining parameter interactions or default behaviors. Given the high schema coverage, the baseline score of 3 is appropriate, as the schema handles the parameter documentation adequately.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'Get time tracked for tasks' clearly states the verb ('Get') and resource ('time tracked for tasks'), providing a basic understanding of the tool's function. However, it doesn't differentiate from sibling tools like 'log_time' (which tracks time) or 'get_task_analytics' (which might include time data), making it somewhat vague about its specific scope compared to alternatives.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

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. It doesn't mention prerequisites (e.g., needing user authentication), exclusions, or comparisons to siblings like 'log_time' for logging time or 'get_task' for general task details, leaving the agent with no contextual usage information.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.