How do I use clockodo-mcp-server?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@clockodo-mcp-server list my time entries for 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.

clockodo-mcp-server

by pfaeffli

Overview Schema Source Related Servers Discussions Admin

Python

Hybrid

Clockodo MCP Server

MCP server wrapper for the Clockodo time tracking API with configurable feature sets.

MCP Badge Security Scans

🐳 Docker Image: ghcr.io/pfaeffli/clockodo-mcp-server:latest

Related MCP server: Clockify MCP Server

Features

This MCP server provides comprehensive time tracking capabilities through:

Tools: 25+ tools for time tracking, HR analytics, and team management
Prompts: Interactive prompt templates for common workflows
Resources: Real-time access to time entries, customers, and services
Role-Based Access: Configurable permission levels (employee, team_leader, hr_analytics, admin)

Architecture & Patterns

This project follows specific architectural patterns to maintain clean, testable, and maintainable code.

1. Layered Architecture

┌─────────────────────────────────────┐
│   MCP Server Layer (server.py)     │  ← Tool registration, MCP protocol
├─────────────────────────────────────┤
│   Service Layer (services/)         │  ← Business logic, orchestration
├─────────────────────────────────────┤
│   Client Layer (client.py)          │  ← HTTP API communication
├─────────────────────────────────────┤
│   External API (Clockodo REST API)  │  ← Third-party service
└─────────────────────────────────────┘

Rules:

Server Layer: Only handles MCP tool registration and protocol. No business logic.
Service Layer: Contains all business logic. Services use clients but never handle MCP directly.
Client Layer: Pure HTTP/API client. No business logic, only request/response handling.
Dependencies flow downward only: Server → Service → Client (never upward)

2. Configuration Management

Pattern: Feature Flags with Environment Variables

# config.py - Central configuration
class ServerConfig:
    hr_readonly: bool = True      # Default safe
    user_read: bool = False        # Opt-in
    admin_edit: bool = False       # Explicit opt-in

    @classmethod
    def from_env(cls) -> "ServerConfig":
        """Load from environment with safe defaults"""

Rules:

All configuration comes from environment variables
Safe defaults (read-only, minimal permissions)
Preset configurations available (readonly, user, admin)
No hardcoded credentials or API keys

3. Dependency Injection

Pattern: Constructor Injection

class HRService:
    def __init__(self, client: ClockodoClient):
        """Inject dependencies explicitly"""
        self.client = client

    def check_overtime_compliance(self, year: int) -> dict:
        # Use injected client
        reports = self.client.get_user_reports(year=year)

Rules:

Services receive their dependencies through constructors
Makes testing easy (mock the dependencies)
Clear dependency graph
No global state or singletons (except config)

4. Separation of Concerns

Pattern: Single Responsibility Principle

client.py          → HTTP communication only
hr_analyzer.py     → Pure data analysis (no I/O)
hr_service.py      → Orchestration (client + analyzer)
hr_tools.py        → MCP tool wrappers (service → MCP)
server.py          → Tool registration

Rules:

Each module has ONE clear purpose
Analyzers are pure functions (input → output, no side effects)
Services handle orchestration
Tools are thin wrappers

5. API Version Handling

Pattern: Resource-Specific Versioning

Clockodo uses a resource-specific versioning scheme. This server always targets the most recent stable version for each resource:

v4: Projects, Services, Absences
v3: Users, Customers
v2: Clock, Entries
v1: User Reports (Legacy reports with no newer version available)

Rules:

Base URL is normalized to end with /api/
All client methods explicitly use the required version prefix (e.g., v3/users)
Responses are normalized to maintain internal consistency (e.g., mapping data key to resource-specific keys)
Legacy v1 endpoints are called without a version prefix

6. Error Handling

Pattern: Let Errors Bubble Up with Context

def _request(self, method: str, endpoint: str) -> dict:
    resp = httpx.request(...)
    resp.raise_for_status()  # Let HTTPStatusError bubble up
    return resp.json()

Rules:

Don't catch exceptions unless you can handle them
Use httpx's built-in error handling
Add context when re-raising
Let MCP framework handle final error presentation

7. Type Safety

Pattern: Type Hints Everywhere

def check_overtime_compliance(
    self, year: int, max_overtime_hours: float = 80
) -> dict:
    """
    Clear input/output types

    Args:
        year: Year to check (e.g., 2024)
        max_overtime_hours: Maximum allowed overtime hours

    Returns:
        Dictionary with overtime violations
    """

Rules:

All functions have type hints
Use from __future__ import annotations for forward references
Docstrings explain the structure of complex dicts
mypy validation in CI/CD

8. Testing Strategy

Pattern: Layered Testing

Unit Tests          → Pure functions (analyzers)
Integration Tests   → Services with mocked clients
Manual Tests        → Jupyter notebooks for real API

Rules:

Mock external HTTP calls (use respx)
Test business logic in isolation
Use pytest fixtures for common setup
Manual testing with real credentials in notebooks

9. Documentation as Code

Pattern: Self-Documenting Code

@mcp.tool()
def check_overtime_compliance(year: int, max_overtime_hours: float = 80) -> dict:
    """
    Check which employees have excessive overtime.

    This docstring becomes the MCP tool description.
    """

Rules:

Docstrings on all public functions
Type hints provide inline documentation
README explains patterns and architecture
Examples in manual-test/ folder

10. Environment-Based Behavior

Pattern: Configuration Over Code

# Don't do this:
if production_mode:
    do_something()

# Do this:
config = ServerConfig.from_env()
if config.is_enabled(FeatureGroup.ADMIN_EDIT):
    register_admin_tools()

Rules:

Feature flags control behavior
No if/else for environments in code
Test different configurations via env vars
Document all environment variables

11. Project Versioning

Pattern: Automated Git Tag Versioning

The project version is automatically managed using setuptools-scm based on Git tags. This ensures that the version in pyproject.toml and at runtime always matches the latest Git tag.

Rules:

Version is NOT hardcoded in pyproject.toml (uses dynamic = ["version"])
src/clockodo_mcp/__init__.py retrieves the version at runtime using importlib.metadata or a generated _version.py file
New releases are created by tagging the repository (e.g., git tag v0.3.0)
The version matches semantic versioning principles

Setup

Option 1: Using Pre-built Docker Image from GitHub Container Registry

For Local MCP Clients (Claude Desktop, IDEs) - stdio transport

Add configuration to your IDE's MCP settings (e.g., Claude Desktop):

{
  "mcpServers": {
    "clockodo": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "CLOCKODO_API_USER=your@email.com",
        "-e",
        "CLOCKODO_API_KEY=your_api_key",
        "-e",
        "CLOCKODO_USER_AGENT=my-company/1.0",
        "-e",
        "CLOCKODO_BASE_URL=https://my.clockodo.com/api/",
        "-e",
        "CLOCKODO_EXTERNAL_APP_CONTACT=dev@company.com",
        "-e",
        "CLOCKODO_MCP_ROLE=employee",
        "ghcr.io/pfaeffli/clockodo-mcp-server:latest"
      ]
    }
  }
}

For Remote Access (Web Apps) - HTTP/SSE transport

⚠️ Note: SSE transport is currently experimental and has known issues. Not recommended for production use.

docker run -d \
  -p 8000:8000 \
  -e CLOCKODO_API_USER=your@email.com \
  -e CLOCKODO_API_KEY=your_api_key \
  -e CLOCKODO_MCP_ROLE=employee \
  -e CLOCKODO_MCP_TRANSPORT=sse \
  -e CLOCKODO_MCP_HOST=0.0.0.0 \
  -e CLOCKODO_MCP_PORT=8000 \
  ghcr.io/pfaeffli/clockodo-mcp-server:latest

Available image tags:

latest - Latest stable release
v1.0.0, v1.0, v1 - Semantic version tags
main-<sha> - Latest main branch build

Option 2: Build Locally

Build the Docker image:
```
make build-mcp
```
Add configuration to your IDE's MCP settings using clockodo-mcp:latest instead of the ghcr.io image.

Environment Variables

API Credentials (Required)

CLOCKODO_API_USER - Your Clockodo email
CLOCKODO_API_KEY - Your Clockodo API key

API Configuration (Optional)

CLOCKODO_USER_AGENT - Custom user agent string (default: "clockodo-mcp/unknown")
CLOCKODO_BASE_URL - API base URL (default: "https://my.clockodo.com/api/")
CLOCKODO_EXTERNAL_APP_CONTACT - Contact info for external app header (default: API user email)

Transport Configuration (Optional)

CLOCKODO_MCP_TRANSPORT - Transport protocol (default: "stdio")
- stdio - Standard input/output for local processes (Claude Desktop, IDEs) [Recommended]
- sse - HTTP/SSE for remote access [Experimental - Known Issues]
CLOCKODO_MCP_HOST - Host address to bind to (default: "0.0.0.0")
CLOCKODO_MCP_PORT - Port for SSE transport (default: 8000)

⚠️ SSE Transport Limitation: The SSE transport is experimental and currently has issues with the MCP library (v1.25.0). The server accepts connections and messages but does not properly send responses back through the event stream, causing client initialization timeouts. Use stdio transport for production. SSE support depends on upstream fixes in the MCP library.

Role Configuration (Recommended)

Use CLOCKODO_MCP_ROLE to set the user's role:

CLOCKODO_MCP_ROLE=employee      # Default - Track your own time
CLOCKODO_MCP_ROLE=team_leader   # Employee + approve vacations & edit team entries
CLOCKODO_MCP_ROLE=hr_analytics  # View HR compliance reports only
CLOCKODO_MCP_ROLE=admin         # Full access to everything

Role	Can Do
employee	Track own time, request vacation
team_leader	Everything employee can + approve team vacations + edit team entries
hr_analytics	View HR compliance reports (overtime, vacation violations) for all employees
admin	Full access to all features

Legacy Configuration (Deprecated)

The following are still supported but deprecated. Use CLOCKODO_MCP_ROLE instead:

Legacy Presets:

CLOCKODO_MCP_PRESET=readonly - Maps to hr_analytics role
CLOCKODO_MCP_PRESET=user - Maps to employee role
CLOCKODO_MCP_PRESET=team_leader - Maps to team_leader role
CLOCKODO_MCP_PRESET=admin - Maps to admin role

Legacy Granular Flags:

CLOCKODO_MCP_ENABLE_HR_READONLY=true
CLOCKODO_MCP_ENABLE_USER_READ=true
CLOCKODO_MCP_ENABLE_USER_EDIT=true
CLOCKODO_MCP_ENABLE_TEAM_LEADER=true
CLOCKODO_MCP_ENABLE_ADMIN_READ=true
CLOCKODO_MCP_ENABLE_ADMIN_EDIT=true

Available Features

Core Tools (Always Available)

health - Health check (shows enabled features)
list_users - List all Clockodo users
list_customers - List all customers
list_services - List all services
list_projects - List all projects
get_raw_user_reports(year) - Get raw API response for debugging

Prompts (Always Available)

start_tracking - Start tracking time for a customer and service
stop_tracking - Stop tracking the current time entry
request_vacation - Request vacation time

Resources (Always Available)

clockodo://current-entry - Get the currently running time entry
clockodo://customers - Get the list of available customers
clockodo://services - Get the list of available services
clockodo://projects - Get the list of available projects
clockodo://recent-entries - Get recent time entries (last 7 days)

HR Analytics (when `HR_READONLY` enabled)

check_overtime_compliance(year, max_overtime_hours) - Check employee overtime
check_vacation_compliance(year, min_vacation_days, max_vacation_remaining) - Check vacation usage
get_hr_summary(year, ...) - Complete HR compliance report

User Tools (when `USER_READ` or `USER_EDIT` enabled)

get_my_clock() - Get currently running clock
get_my_time_entries(time_since, time_until) - Get your time entries
start_my_clock(...) - Start tracking time
stop_my_clock() - Stop tracking time
add_my_time_entry(...) - Add a manual time entry
edit_my_time_entry(entry_id, data) - Edit your time entry
delete_my_time_entry(entry_id) - Delete your time entry
add_my_vacation(date_since, date_until) - Request vacation
delete_my_vacation(absence_id) - Delete vacation request

Team Leader Tools (when `TEAM_LEADER` enabled)

list_pending_vacation_requests(year) - List all pending vacation requests
approve_vacation_request(absence_id) - Approve a vacation request
reject_vacation_request(absence_id) - Reject a vacation request
adjust_vacation_dates(absence_id, new_date_since, new_date_until) - Adjust vacation length
create_team_member_vacation(user_id, date_since, date_until, ...) - Create vacation for team member
edit_team_member_entry(entry_id, data) - Edit team member's time entry
delete_team_member_entry(entry_id) - Delete team member's time entry

Development

# Build
make build-mcp

# Run tests
make test

# Type checking
make type

# Linting
make lint

# Style check
make format-check

Security Scanning

Run comprehensive security scans on the Docker image:

# Run all security scans (vulnerability, Docker best practices, licenses, SBOM)
make all-scans

# Individual scans
make vulnerability-scan  # Trivy vulnerability scanning
make docker-scan        # Dockle Docker best practices
make license-check      # Python dependency license check
make sbom              # Generate Software Bill of Materials

All security tools run via Docker containers - no local installation required.

Manual Testing

For manual testing with real Clockodo API credentials, use the Jupyter notebook:

make manual-test

Open http://localhost:8888 and navigate to work/manual-test/test_clockodo.ipynb.

See manual-test/JUPYTER_TESTING.md for detailed instructions.

Project Structure

clockodo-mcp/
├── src/clockodo_mcp/
│   ├── server.py              # MCP tool registration
│   ├── client.py              # Clockodo API client
│   ├── config.py              # Feature flag configuration
│   ├── hr_analyzer.py         # Pure data analysis functions
│   ├── services/
│   │   ├── hr_service.py      # Business logic orchestration
│   │   ├── user_service.py    # User operations
│   │   └── team_leader_service.py  # Team leader operations
│   └── tools/
│       ├── hr_tools.py        # MCP tool wrappers
│       ├── user_tools.py      # User tool wrappers
│       ├── team_leader_tools.py    # Team leader tool wrappers
│       └── debug_tools.py     # Debugging utilities
├── tests/                      # Unit and integration tests
├── manual-test/               # Jupyter notebooks for manual testing
├── docker-compose.yml         # Dev and server services
├── docker-compose.test.yml    # Test and Jupyter services
└── makefile                   # Build and test targets

Contributing

When adding new features, follow these patterns:

New API Endpoint: Add method to client.py
Business Logic: Create/update service in services/
MCP Tool: Add tool registration in server.py
Tests: Add unit tests in tests/
Documentation: Update README and docstrings

Always maintain the layered architecture: Server → Service → Client

Available Tools

15 tools

add_my_time_entryA

Add a manual time entry for the authenticated user.

Args: customers_id: ID of the customer services_id: ID of the service time_since: Start time (e.g., 2025-01-01T09:00:00Z) time_until: End time (e.g., 2025-01-01T10:00:00Z) billable: Whether the entry is billable (1) or not (0) projects_id: Optional project ID text: Optional description

ParametersJSON Schema

Name	Required	Description	Default
`text`	No
`billable`	No
`time_since`	Yes
`time_until`	Yes
`projects_id`	No
`services_id`	Yes
`customers_id`	Yes

TDQS

A4/5.0

Behavior3/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 transparency. It states the action ('Add') and the target ('a manual time entry'), but does not disclose any potential side effects, error conditions, or details about the created record's association. The behavior is minimally transparent but lacks deeper disclosure.

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

Conciseness5/5

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

The description is extremely concise, with no redundant information. Each parameter is listed briefly and clearly. The entire description is compact and efficiently communicates the necessary details.

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

Completeness4/5

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

The description covers the core purpose and all parameters. It does not explicitly mention return values or possible errors, but given the simplicity of a create operation and the lack of an output schema, this is a minor gap. Overall, it provides enough context for an agent to invoke the tool correctly.

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

Parameters4/5

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

The parameter descriptions in the tool description add meaningful context beyond the raw schema types. It clarifies the roles of customers_id, services_id, time_since, time_until, billable, and marks projects_id and text as optional. It also provides examples for time format. This exceeds the schema's bare type information.

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

Purpose5/5

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

The description clearly states the tool's function: 'Add a manual time entry for the authenticated user.' It uses a specific verb (add) and resource (time entry), and it is distinct from sibling tools like start_my_clock or add_my_vacation which perform different actions.

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

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description does not explicitly mention when to use this tool versus alternatives. It implies usage for manual time entry logging, but does not state conditions or contrast with other tools like start_my_clock or add_my_vacation. Thus the usage 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.

add_my_vacationA

Add a vacation for the authenticated user.

Args: date_since: Start date (YYYY-MM-DD) date_until: End date (YYYY-MM-DD)

ParametersJSON Schema

Name	Required	Description	Default
`date_since`	Yes
`date_until`	Yes

TDQS

A3.7/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must carry the full burden of disclosing side effects. It only states 'Add a vacation' without mentioning that it creates a record, whether it is idempotent, any conflict handling, or potential impact on other data. This lacks sufficient 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.

Conciseness5/5

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

The description is concise and well-structured, with a clear purpose statement followed by an Args section listing parameters. No redundant or irrelevant information is present, making it easy to parse quickly.

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

Completeness3/5

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

For a simple add operation, the description provides the essential action and arguments. However, given the absence of an output schema and annotations, it leaves out details such as what the tool returns (e.g., success status, created vacation object) and how errors are communicated. It is minimally adequate but not fully self-contained.

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 description includes basic meaning for both parameters ('Start date' and 'End date') and specifies the YYYY-MM-DD format, which is helpful. However, it omits constraints such as whether the end date must be after the start date, timezone handling, or if dates are inclusive/exclusive. Schema coverage is 0%, so the description partially compensates but not fully.

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

Purpose5/5

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

The description clearly states the action ('Add a vacation') and the target ('for the authenticated user'). It unambiguously distinguishes this tool from siblings like get_my_time_entries or start_my_clock, making the intent immediately obvious.

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

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives a clear directive for when to use the tool (to add a vacation), but does not explicitly mention any alternative to avoid. Given there is no direct alternative among siblings (e.g., no 'add_my_time_entry' is a different resource), the guidance is adequate though not deeply explicit.

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

delete_my_time_entryB

Delete a time entry for the authenticated user.

Args: entry_id: ID of the entry to delete

ParametersJSON Schema

Name	Required	Description	Default
`entry_id`	Yes

TDQS

B3.3/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, and the description does not mention irreversibility, side effects, permission requirements, or any potential consequences of deletion. The behavioral impact is largely opaque.

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

Conciseness5/5

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

The description is a single, concise sentence that directly conveys the tool's purpose without unnecessary detail. It is well-structured and easy to parse.

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

Completeness3/5

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

The description covers the basic purpose but omits contextual cues such as typical usage flow, preconditions (e.g., must already have a time entry), or relationship to sibling tools like get_my_time_entries. For a simple delete operation, this is acceptable but not comprehensive.

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 parameter entry_id is described as 'ID of the entry to delete', which is clear but somewhat tautological. It does not explain how to obtain the ID, any format constraints, or whether it must belong to the authenticated user beyond the implicit scope.

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

Purpose4/5

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

The description clearly states the action ('Delete') and the resource ('a time entry'), and scopes it to the authenticated user. It distinguishes from sibling tools like delete_my_vacation, though it does not name alternatives explicitly.

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

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage when a time entry needs to be removed for the current user, but it does not explicitly contrast with alternatives or provide conditions for when to choose this tool over others such as edit_my_time_entry or add_my_time_entry.

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

delete_my_vacationB

Delete a vacation/absence for the authenticated user.

Args: absence_id: ID of the absence to delete

ParametersJSON Schema

Name	Required	Description	Default
`absence_id`	Yes

TDQS

B3.3/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description does not disclose any side effects or prerequisites. It is a destructive operation (delete) but does not warn about irreversibility or potential cascading effects (e.g., impacting leave balances). Without annotations, the description carries the full burden, and it is insufficiently transparent about the operation's consequences.

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 very brief and to the point, containing no unnecessary fluff. However, it could have included a few more useful details (e.g., outcome feedback) without becoming verbose, so it is efficient but not perfectly balanced.

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?

The description lacks information about return values, error cases, or required permissions. Since there is no output schema, the description should at least mention what the tool returns or how errors are signaled. It also does not state whether the absence must belong to the authenticated user, despite implying it. This leaves gaps for the agent.

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

Parameters4/5

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

The single parameter, absence_id, is described as 'ID of the absence to delete,' which clearly identifies its role. While it lacks additional detail like whether it must be an existing ID or format examples, the basic semantic is clear and sufficient for most uses.

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

Purpose5/5

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

The description clearly states the tool's function: 'Delete a vacation/absence for the authenticated user.' It uses the specific verb 'delete' and names the resource ('vacation/absence'), which distinguishes it from sibling tools like delete_my_time_entry. The scope is also clarified with 'for the authenticated user.'

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?

No explicit guidance is provided on when to use this tool versus alternatives. While the purpose is clear, the description does not mention conditions like 'use this when the vacation is no longer needed' or contrast with deleting time entries. The agent must infer usage from the tool name and sibling context.

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

edit_my_time_entryC

Edit a time entry for the authenticated user.

Args: entry_id: ID of the entry to edit data: Dictionary of fields to update (e.g., {"text": "new description"})

ParametersJSON Schema

Name	Required	Description	Default
`data`	Yes
`entry_id`	Yes

TDQS

C2.6/5.0

Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

There are no annotations and no description of side effects, persistence, irreversibility, or permissions. The description only says 'edit', which implies mutation, but provides no details about consequences or behavior.

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

Conciseness5/5

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

The description is very concise, consisting of a single sentence plus two parameter explanations. There is no fluff or redundant information, making it efficient and easy to parse.

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?

The description is minimal and lacks important context such as expected output, potential errors, or how it fits with sibling tools. For a simple edit operation it may be sufficient, but it does not fully cover what an agent needs to know in context.

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 schema itself has no descriptions, but the tool description explains entry_id as 'ID of the entry to edit' and data as 'Dictionary of fields to update' with an example. This provides basic meaning for both parameters, though the data parameter remains underspecified because additionalProperties is true and allowed fields are not enumerated.

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

Purpose4/5

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

The description clearly states the tool edits a time entry for the authenticated user, using the verb 'edit' and the resource 'time entry'. It does not explicitly differentiate from sibling tools like add/delete/get, but the action is specific enough to be understood.

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

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided about when to use this tool versus alternatives such as adding, deleting, or getting time entries. The description only states what the tool does, not the conditions under which it should be selected.

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

get_my_clockB

Get the currently running clock for the authenticated user.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

B3.4/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description does not disclose any behavioral aspects such as side effects (read-only vs. mutating), authentication requirements, rate limits, or error conditions. Since no annotations are provided, the description carries the full burden, and 'Get' alone does not explicitly confirm safety.

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

Conciseness5/5

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

The description is a single, concise sentence with no unnecessary words. It is front-loaded with the action and resource, making it immediately understandable.

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

Completeness4/5

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

The description provides sufficient context for a simple getter: it identifies the resource (currently running clock) and the scope (authenticated user). It does not specify the return format, but given the lack of an output schema, this is acceptable for a basic retrieval.

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 tool has no parameters, and the description adds no additional meaning beyond the empty schema. Since schema coverage is effectively 100% (nothing to cover), the baseline of 3 applies, and the description offers no extra semantic detail.

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

Purpose5/5

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

The description clearly states a specific action ('Get') and resource ('currently running clock') for the authenticated user. It effectively distinguishes itself from sibling tools like start_my_clock and get_my_time_entries by focusing on retrieving the active clock.

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?

There is no explicit guidance on when to use this tool versus alternatives. While the name and description imply it is for retrieving the running clock, it does not state conditions like 'use this when you need the current active clock' or contrast with get_my_time_entries.

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

get_my_time_entriesA

Get time entries for the authenticated user in a given time range.

Args: time_since: Start time (e.g., 2025-01-01T00:00:00Z) time_until: End time (e.g., 2025-01-01T23:59:59Z)

ParametersJSON Schema

Name	Required	Description	Default
`time_since`	Yes
`time_until`	Yes

TDQS

A3.6/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of disclosing behavioral traits. It does not explicitly state that the operation is read-only, mention potential side effects, permissions, rate limits, or error conditions. The verb 'Get' implies read-only behavior, but this is not explicitly disclosed.

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

Conciseness5/5

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

The description is concise and well-structured. It uses one clear sentence for the main purpose and a compact list for parameter details. No redundant or verbose content is present.

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

Completeness4/5

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

For a simple retrieval tool, the description covers the essential context: what it retrieves, for whom, and the parameter format. It does not mention return format, pagination, or timezone handling, but these are not critical for basic use and no output schema is provided. Overall, the description is sufficiently complete for its simplicity.

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

Parameters4/5

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

The description adds meaningful information beyond the schema by explaining the parameters: 'time_since' as start time and 'time_until' as end time, with concrete example formats (2025-01-01T00:00:00Z). This compensates for the lack of schema descriptions and helps an agent correctly format the input.

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

Purpose5/5

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

The description clearly states the tool's purpose: retrieving time entries for the authenticated user within a given time range. The verb 'Get' is specific, and the resource and scope (authenticated user, time range) are explicit, which distinguishes it from sibling tools like add_my_time_entry or list_projects.

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 explains what the tool does but provides no guidance on when to choose it over alternatives such as get_raw_user_reports or get_my_clock. It does not mention filtering, sorting, or other usage conditions that would help an agent decide between similar tools.

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

get_raw_user_reportsA

Get raw user reports from Clockodo API (for debugging).

Shows the actual data returned by Clockodo's /api/userreports endpoint.

Args: year: Year to fetch (e.g., 2024, 2025)

Returns: Raw API response with all user report data

ParametersJSON Schema

Name	Required	Description	Default
`year`	Yes

TDQS

A3.9/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description bears the full burden. It mentions the tool returns the raw API response and includes 'all user report data', implying it fetches data for all users rather than just the current user. However, it does not state whether the operation is read-only, what errors might occur, or any rate-limit or data-size implications. Transparency is partial.

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

Conciseness5/5

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

The description is concise and well-organized, with distinct sections for the summary, arguments, and return value. It avoids unnecessary wording and directly conveys the tool's purpose and usage.

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

Completeness3/5

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

The description explains that the return is a raw API response with all user report data, but it lacks details about the response format (e.g., JSON structure), error handling, or any side effects. Given the tool is for debugging, some vagueness is acceptable, but it is not fully complete in context.

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

Parameters4/5

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

The only parameter, 'year', is explained with a clear description and examples (2024, 2025), which adds meaning beyond the schema's bare integer type. It does not specify a range or format constraints, but the explanation is sufficient for a simple parameter.

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

Purpose5/5

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

The description clearly states the tool's function: retrieving raw user reports from the Clockodo API, explicitly for debugging purposes. It also specifies the resource (user reports) and the endpoint, distinguishing it from sibling tools that handle individual time entries or vacations.

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

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description notes the tool is 'for debugging' and returns 'raw' data, implying it is for low-level inspection. However, it does not explicitly state when to prefer this over other tools (e.g., when a processed summary is needed) or provide concrete use cases. It gives some context but lacks direct comparison with alternatives.

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

healthA

Health check for the Clockodo MCP server.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A4.3/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description does not disclose side effects or return format. It merely says 'health check' without specifying whether it is read-only or what output to expect. Given no annotations, the description carries the full burden for behavioral transparency, and it falls short of explicit detail.

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

Conciseness5/5

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

The description is a single, concise sentence that conveys the essential purpose without any extraneous detail. It is optimally sized for its simplicity.

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

Completeness4/5

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

The tool is minimal, and the description covers its basic function completely. However, it does not mention what the health check returns (e.g., status, error codes), which could be relevant for an agent deciding whether to invoke it. Still, for a health check, the purpose is clear enough.

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

Parameters5/5

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

The tool has zero parameters, so there is nothing to describe. The absence of parameters is accurately reflected in the input schema, and no additional explanation is necessary.

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

Purpose5/5

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

The description is unambiguous: it states that the tool performs a health check for the Clockodo MCP server. There is no ambiguity about the tool's primary function.

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

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

While no explicit when-to-use guidance is given, the purpose is self-evident. A health check is typically invoked to verify server status, and the description implies this usage without needing further clarification.

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

list_customersB

List all customers from Clockodo API.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

B3.4/5.0

Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description does not explicitly state that listing is read-only or safe, and there are no annotations to fill this gap. It only says 'List', which implies but does not disclose 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.

Conciseness5/5

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

The description is a single, concise sentence with no unnecessary words.

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

Completeness5/5

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

Given the simplicity of the operation, the description provides enough context for a user to understand what the tool does.

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

Parameters5/5

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

The tool takes no parameters, so there is no additional parameter information needed; the description is sufficient.

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

Purpose5/5

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 (customers) with the context of the Clock API. It is unambiguous.

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

Usage Guidelines1/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 over alternatives such as list_users or list_projects, nor any conditions for its use.

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

list_projectsA

List all projects from Clockodo API.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

A4.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description implies a read-only operation ('List all projects') and the lack of annotations means the description carries the full burden. It accurately describes the behavior without misleading side effects. No hidden behavior is suggested.

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

Conciseness5/5

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

The description is a single, concise sentence with clear structure. It contains no redundant words and precisely communicates the tool's action.

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

Completeness5/5

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

Given the tool has no parameters and no output schema, the description fully covers what the agent needs to know to invoke it correctly. It states the action and the data source sufficiently.

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

Parameters4/5

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

There are no parameters, so the description doesn't need to add meaning to them. The baseline score of 4 applies as the description provides no extra context for parameters, which is acceptable for a parameterless tool.

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

Purpose5/5

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

The description clearly states the tool's function: 'List all projects from Clockodo API.' It uses a specific verb and resource, and the phrase 'all projects' distinguishes it from sibling list tools like list_users or list_customers.

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

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The purpose is self-evident and the context is clear for a simple list operation. While it doesn't explicitly mention when to use it over alternatives, the resource name and lack of parameters make the usage obvious. No explicit exclusions are needed.

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

list_servicesA

List all services from Clockodo API.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

A4.6/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description indicates a non-destructive read operation ('list'). Although annotations are missing, the wording itself implies safety, and there is no contradiction with the absence of destructive hints.

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

Conciseness5/5

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

The description is a single, concise sentence with no unnecessary words. It directly states the operation and resource, making it highly efficient.

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

Completeness5/5

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

For a parameterless read-only listing tool, the description provides all necessary context. The user knows exactly what the tool does and what to expect: a list of all services.

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

Parameters5/5

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

The tool has no parameters in its schema. The description does not need to explain any parameters, as there are none, and the schema coverage is complete by default.

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

Purpose5/5

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

The description clearly states the action (list) and the resource (all services) from the Clockodo API. It is unambiguous and leaves no doubt about the tool's purpose.

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

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description is self-explanatory for a simple read-only listing operation. It does not explicitly mention when to use it over sibling tools, but the absence of parameters and the generic 'list all' phrasing makes the use case obvious in context.

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

list_usersA

List all users from Clockodo API.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

A4.5/5.0

Behavior4/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. The verb 'List' suggests a read-only, non-destructive operation, and the lack of parameters implies no side effects beyond fetching data. However, it does not explicitly confirm read-only status or mention potential pagination or rate limits, leaving minor ambiguity.

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

Conciseness5/5

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

The description is a single, concise sentence that conveys all necessary information without extraneous detail. It is front-loaded with the action and resource, making it easy to parse quickly.

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

Completeness4/5

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

For a simple list operation with no parameters, the description is sufficient for an agent to invoke it correctly. However, it does not specify the structure or content of the returned user list (e.g., fields, ordering), which could be relevant for downstream processing. Given the simplicity, this is a minor gap.

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

Parameters5/5

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

The tool has zero parameters, and the description correctly indicates no inputs are required. There is no schema to document, and the description adequately conveys that no additional arguments are needed to invoke the listing.

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

Purpose5/5

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

The description clearly states the action ('List') and the target resource ('all users') from the Clockodo API. It is specific and distinguishable from sibling tools like 'get_my_clock' or 'list_customers', making its purpose unambiguous.

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

Usage Guidelines4/5

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 over alternatives, but its name and phrase 'all users' imply it is for broad user enumeration, contrasting with the 'my' prefixed tools that focus on the authenticated user. The context from sibling tools provides implicit guidance, though explicit usage conditions would be clearer.

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

start_my_clockC

Start the clock for the authenticated user.

Args: customers_id: ID of the customer services_id: ID of the service billable: Whether the entry is billable (1) or not (0) projects_id: Optional project ID text: Optional description

ParametersJSON Schema

Name	Required	Description	Default
`text`	No
`billable`	No
`projects_id`	No
`services_id`	Yes
`customers_id`	Yes

TDQS

C2.7/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations and no description of side effects, failure conditions, or return behavior, the description leaves the tool's full behavior unclear. It does not state whether starting the clock is idempotent, whether it fails if a clock is already running, or what the response will contain.

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

Conciseness5/5

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

The description is very concise and free of redundant or irrelevant information. The one-sentence purpose followed by a simple parameter list is efficient and easy to parse.

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?

Overall, the description is too sparse to be fully self-contained. It omits important behavioral details, parameter semantics, and any mention of what the caller should expect after invoking the tool, making it incomplete for an agent relying solely on this text.

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

Parameters1/5

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

Schema description coverage is 0%, and the parameter descriptions are largely tautological (e.g., 'customers_id: ID of the customer', 'services_id: ID of the service'). The description adds no meaningful guidance about where IDs come from, constraints, or relationships between parameters, so an agent cannot reliably determine correct values.

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

Purpose4/5

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

The description clearly states the action ('Start the clock') and the target ('the authenticated user'), which distinguishes it from sibling tools like stop_my_clock and get_my_clock. However, it does not explicitly clarify whether this creates a time entry or merely begins tracking, leaving slight ambiguity.

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 gives no explicit guidance on when to use this tool versus alternatives such as add_my_time_entry or stop_my_clock. Usage is only implied by the tool's name and minimal description, so an agent receives little direction on choosing this tool.

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

stop_my_clockA

Stop the currently running clock for the authenticated user.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

A4/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description implies a state change (stopping a clock) but does not describe side effects, return values, or error behavior (e.g., what happens if no clock is running). Without annotations, this information is missing.

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

Conciseness5/5

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

The description is a single, clear sentence with no redundant words. It is appropriately concise for a simple action.

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

Completeness3/5

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

The description is minimal and does not address edge cases or expected outcomes. While the action is simple, it lacks context about preconditions or failure modes, making it less complete for an agent.

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

Parameters5/5

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

The tool has no parameters, so the description has nothing to add beyond the schema. The schema coverage is trivially complete.

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

Purpose5/5

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

The description clearly states the action (stop), the target (clock), and the scope (authenticated user). It is unambiguous and directly conveys the tool's purpose.

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

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description does not specify when to use this tool versus alternatives like start_my_clock or get_my_clock. It lacks explicit guidance on prerequisites or selection criteria.

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

15 tool updatesv0.1.0Sep 8, 2026
- First observedadd_my_time_entry
- First observedadd_my_vacation
- First observeddelete_my_time_entry
- First observeddelete_my_vacation
- First observededit_my_time_entry
- First observedget_my_clock
- First observedget_my_time_entries
- First observedget_raw_user_reports
- First observedhealth
- First observedlist_customers
- First observedlist_projects
- First observedlist_services
- First observedlist_users
- First observedstart_my_clock
- First observedstop_my_clock

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.7/5.0

Scored 2026-09-08 01:05 across 15 tools

Disambiguation5/5

Each tool has a clear, distinct purpose: time entry operations, clock start/stop, vacation management, list operations, and reports are all separate. No significant overlap or ambiguity.

Naming Consistency5/5

All tools follow a consistent verb_noun pattern in snake_case (get_, start_, stop_, add_, edit_, delete_, list_). The naming is uniform and predictable.

Tool Count4/5

15 tools is at the upper end of the typical range but still appropriate for a comprehensive time-tracking API. Each tool serves a necessary function without excessive redundancy.

Completeness4/5

Covers the core lifecycle for time entries (create, read, update, delete), clock control, vacation add/delete, and listing resources. Minor gap: no edit/update for vacation or users, but not critical for the primary use case.

Maintenance

ActivityMaintained

ResponsivenessResponsive

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

harvest A
io.usefulapi
Read time entries, projects, clients, tasks and invoices; log and update tracked time.
Project Management Payments & Billing Workplace & Productivity
201
Astravue MCPOAuth
com.astravue
Manage projects, tasks, time tracking, and team collaboration through natural language.
Project Management Workplace & Productivity
312
clickup A
io.usefulapi
Read teams, spaces, lists and tasks; create, update and comment on tasks and track time.
Project Management Workplace & Productivity
141
time-tracker-timesheet-billable-hours A
io.github.theluckystrike
Track billable time from your AI chat: timers, entries, reports, CSV export. All data stays local.
Workplace & Productivity Project Management
141

Related MCP Servers

Clockify MCP Server
Project Management App Automation
ratheesh-aot
A
license
B
quality
D
maintenance
Provides comprehensive integration with the Clockify time tracking API, enabling automated time entry management, project organization, task tracking, and reporting through a standardized interface.
Updated a year ago (2025-06-20 23:30 UTC)
29
4 npm
6
MIT
Clockify MCP Server
Project Management Workplace & Productivity
yravinderkumar33
A
license
Not graded
quality
D
maintenance
Integrates with Clockify time tracking API to retrieve user information, manage projects, and log time entries with flexible time specifications across workspaces.
Updated a year ago (2025-07-02 10:05 UTC)
MIT
Clockify MCP Server
Project Management Workplace & Productivity
aslamanver
A
license
Not graded
quality
D
maintenance
Enables AI assistants to interact with Clockify time tracking API to manage time entries, projects, tasks, and workspaces through natural language commands.
Updated 7 months ago (2026-02-11 15:21 UTC)
22 npm
5
ISC
Clockify MCP Server
Project Management App Automation Workplace & Productivity
Yikizi
A
license
B
quality
D
maintenance
Enables time tracking and project management through the Clockify API. Supports starting/stopping timers, logging time entries, managing projects and tasks, and generating reports with natural language commands.
Updated 9 months ago (2025-12-20 20:04 UTC)
21
5 npm
MIT

Clockodo MCP Server

Table of Contents

Features

Architecture & Patterns

1. Layered Architecture

2. Configuration Management

3. Dependency Injection

4. Separation of Concerns

5. API Version Handling

6. Error Handling

7. Type Safety

8. Testing Strategy

9. Documentation as Code

10. Environment-Based Behavior

11. Project Versioning

Setup

Option 1: Using Pre-built Docker Image from GitHub Container Registry

For Local MCP Clients (Claude Desktop, IDEs) - stdio transport

For Remote Access (Web Apps) - HTTP/SSE transport

Option 2: Build Locally

Environment Variables

API Credentials (Required)

API Configuration (Optional)

Transport Configuration (Optional)

Role Configuration (Recommended)

Legacy Configuration (Deprecated)

Available Features

Core Tools (Always Available)

Prompts (Always Available)

Resources (Always Available)

HR Analytics (when HR_READONLY enabled)

User Tools (when USER_READ or USER_EDIT enabled)

Team Leader Tools (when TEAM_LEADER enabled)

Development

Security Scanning

Manual Testing

Project Structure

Contributing

Available Tools

Output Schema

Tool Schema Changelog

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

HR Analytics (when `HR_READONLY` enabled)

User Tools (when `USER_READ` or `USER_EDIT` enabled)

Team Leader Tools (when `TEAM_LEADER` enabled)