Skip to main content
Glama
cruzleedan

personal-timesheet-mcp

by cruzleedan

Timesheet MCP Server

A Model Context Protocol (MCP) server that provides CRUD operations for timesheet management via REST API endpoints.

πŸ‘€ For End Users: See README-USER.md for simple installation instructions
πŸ‘¨β€πŸ’» For Developers: Continue reading below
πŸ“¦ Publishing: See Publishing Guide to distribute your connector

Features

  • Create timesheet entries

  • Read timesheet entries (list and get single)

  • Update existing entries

  • Delete timesheet entries

  • List Projects for reference

  • Configurable API base URL

  • Support for both Go and Node.js backend APIs

Related MCP server: TimePRO MCP Server

Prerequisites

  • Node.js 18 or higher

  • A running instance of the Timesheet Logger backend API

  • Claude Desktop (for integration)

Installation

  1. Navigate to the mcp directory:

cd mcp
  1. Install dependencies:

npm install
  1. Configure environment variables:

cp .env.example .env
# Edit .env and set TIMESHEET_API_BASE_URL
  1. Build the project:

npm run build

Configuration

Environment Variables

Create a .env file or set environment variables:

TIMESHEET_API_BASE_URL=http://localhost:3000/api

Claude Desktop Integration

Add to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

For end users (after publishing to npm):

{
  "mcpServers": {
    "timesheet": {
      "command": "timesheet-mcp",
      "env": {
        "TIMESHEET_API_BASE_URL": "http://localhost:3000/api"
      }
    }
  }
}

For local development:

{
  "mcpServers": {
    "timesheet": {
      "command": "node",
      "args": ["/absolute/path/to/timesheet_logger/mcp/build/index.js"],
      "env": {
        "TIMESHEET_API_BASE_URL": "http://localhost:3000/api"
      }
    }
  }
}

Usage

Development Mode

Run in development mode with auto-reload:

npm run dev

Production Mode

Build and run:

npm run build
npm start

Available Tools

1. create_timesheet_entry

Create a new timesheet entry.

Parameters:

  • project_id (string, required): Project ID

  • date (string, required): Entry date (YYYY-MM-DD)

  • hours (number, required): Hours worked

  • description (string, optional): Entry description

  • billable (boolean, optional): Whether entry is billable (default: true)

2. list_timesheet_entries

List timesheet entries with optional filters.

Parameters:

  • start_date (string, optional): Filter by start date (YYYY-MM-DD)

  • end_date (string, optional): Filter by end date (YYYY-MM-DD)

  • project_id (string, optional): Filter by project ID

  • limit (number, optional): Maximum results (default: 50)

  • offset (number, optional): Offset for pagination (default: 0)

3. get_timesheet_entry

Get a single timesheet entry by ID.

Parameters:

  • entry_id (string, required): Entry ID

4. update_timesheet_entry

Update an existing timesheet entry.

Parameters:

  • entry_id (string, required): Entry ID

  • project_id (string, optional): New project ID

  • date (string, optional): New date (YYYY-MM-DD)

  • hours (number, optional): New hours

  • description (string, optional): New description

  • billable (boolean, optional): New billable status

5. delete_timesheet_entry

Delete a timesheet entry.

Parameters:

  • entry_id (string, required): Entry ID

6. list_projects

List available projects.

Parameters: None

7. create_project

Create a new project. Requires admin or manager role.

Parameters:

  • name (string, required): Project name

  • description (string, optional): Project description

  • is_active (boolean, optional): Whether project is active (default: true)

8. login

Manually trigger browser-based login. Opens a browser window for authentication.

Parameters: None

Note: Useful after logout or for manual authentication. If already logged in, will show current user.

9. logout

Logout from the current session and clear stored authentication tokens.

Parameters: None

Note: After logout, you will need to re-authenticate (via browser login) on the next request.

Testing

Test with Local Backend

  1. Start your backend API:

# From backend/api-nodejs or backend/api-go
docker-compose up
  1. Run the MCP server:

npm run dev
  1. Test through Claude Desktop or use the MCP Inspector

Troubleshooting

Connection Refused

  • Ensure the backend API is running

  • Verify the TIMESHEET_API_BASE_URL is correct

  • Check that the port matches your backend configuration

Authentication Errors

  • Verify API key if required by your backend

  • Check that the API endpoint supports the operations

Tool Not Found

  • Rebuild the project: npm run build

  • Restart Claude Desktop

  • Verify the path in Claude Desktop config is absolute

Development

Project Structure

mcp/
β”œβ”€β”€ src/
β”‚   β”œβ”€β”€ index.ts              # Main MCP server entry point
β”‚   β”œβ”€β”€ config.ts             # Configuration management
β”‚   β”œβ”€β”€ types.ts              # TypeScript types
β”‚   β”œβ”€β”€ api/
β”‚   β”‚   β”œβ”€β”€ client.ts         # HTTP client wrapper
β”‚   β”‚   └── timesheet.ts      # Timesheet API operations
β”‚   └── tools/
β”‚       β”œβ”€β”€ create-entry.ts   # Create tool
β”‚       β”œβ”€β”€ list-entries.ts   # List tool
β”‚       β”œβ”€β”€ get-entry.ts      # Get tool
β”‚       β”œβ”€β”€ update-entry.ts   # Update tool
β”‚       └── delete-entry.ts   # Delete tool
β”œβ”€β”€ build/                    # Compiled output
β”œβ”€β”€ package.json
β”œβ”€β”€ tsconfig.json
└── README.md

Adding New Tools

  1. Create a new file in src/tools/

  2. Define the tool schema using Zod

  3. Implement the handler function

  4. Register the tool in src/index.ts

License

MIT

Available Tools

9 tools
create_projectB

Create a new project. Requires admin or manager role.

ParametersJSON Schema
NameRequiredDescriptionDefault
nameYesThe name of the project (required)
is_activeNoWhether the project is active (default: true)
descriptionNoOptional description of the project

TDQS

B3.4/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. It discloses the required role but omits other behavioral details such as idempotency, side effects, or return value, making it insufficient for a mutation tool.

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?

Two concise sentences, front-loaded with the purpose. No wasted words.

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?

For a creation tool with no output schema, the description should indicate return behavior or error conditions. It only covers prerequisites, leaving the agent uninformed about expected outcomes.

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?

Schema coverage is 100%, so the schema already documents all parameters. The description adds no parameter-specific information beyond what is in the schema, meeting the baseline.

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 'Create a new project' with a specific verb and resource. It distinguishes from siblings like create_timesheet_entry and list_projects, which operate on different resources.

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 mentions a prerequisite ('Requires admin or manager role') but does not provide guidance on when to use this tool versus alternatives, nor when not to use it.

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

create_timesheet_entryB

Create a new timesheet entry with project, date, hours, and optional description

ParametersJSON Schema
NameRequiredDescriptionDefault
dateYesThe date of the entry in YYYY-MM-DD format
hoursYesNumber of hours worked (must be positive)
billableNoWhether this entry is billable (default: true)
project_idYesThe ID of the project for this entry
descriptionNoOptional description of the work performed

TDQS

B3.1/5.0
Behavior2/5

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

With no annotations provided, the description does not disclose behavioral traits like persistence, validation, permissions, or side effects. It only states the action 'Create', which implies mutation, but offers no further transparency.

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 one concise sentence with no waste. It is appropriately short for a simple tool, though it could benefit from slightly more structure or elaboration.

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 absence of an output schema, the description does not specify return values or validation behavior. It is incomplete for a creation tool, missing context on success/error outcomes.

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?

Schema description coverage is 100%, so baseline is 3. The description lists the parameters (project, date, hours, optional description) but adds no additional meaning or context beyond the schema.

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 (Create), the resource (timesheet entry), and key fields (project, date, hours, optional description). It effectively distinguishes from sibling tools like delete, get, list, update.

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. No prerequisites, context, or exclusions are mentioned. While sibling names imply creation, the description itself lacks explicit usage instructions.

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

delete_timesheet_entryB

Delete a timesheet entry by ID

ParametersJSON Schema
NameRequiredDescriptionDefault
entry_idYesThe ID of the entry to delete

TDQS

B3.2/5.0
Behavior2/5

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

No annotations are provided, so the description bears full burden. It does not disclose traits like irreversibility, required permissions, or side effects (e.g., cascading deletions).

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, clear sentence with no wasted words. Slightly more structure (e.g., noting irreversibility) could improve it.

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 delete tool with one parameter and no output schema, the description is minimally adequate but lacks behavioral context (e.g., what happens on success/failure, idempotency).

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?

Schema coverage is 100%, and the description adds no additional meaning beyond the schema's parameter description. Baseline score of 3 is appropriate.

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 'Delete a timesheet entry by ID' uses a specific verb ('Delete') and resource ('timesheet entry'), clearly distinguishing it from sibling tools like create, get, list, and update.

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 guidance on when to use this tool versus alternatives, nor any prerequisites, caveats, or exclusions (e.g., cannot delete if timesheet is approved).

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

get_timesheet_entryB

Get a single timesheet entry by ID

ParametersJSON Schema
NameRequiredDescriptionDefault
entry_idYesThe ID of the timesheet entry to retrieve

TDQS

B3.4/5.0
Behavior2/5

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

With no annotations, description should disclose behavior. Only states basic purpose; no mention of error handling, permissions, or what happens if entry_id is invalid.

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?

Single sentence is concise and front-loaded, but could include return information without being verbose.

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?

Minimal description for a simple tool; lacks return value description and error context. Adequate but not complete.

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?

Schema coverage is 100% with a clear description for entry_id. Description adds no new meaning beyond repeating 'by ID'.

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?

Description 'Get a single timesheet entry by ID' clearly states the action and resource, and distinguishes from sibling tools like list_timesheet_entries.

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?

Implies usage when you have an entry_id, but no explicit guidance on when to use vs. alternatives like list_timesheet_entries or create_timesheet_entry.

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 available projects that can be used for timesheet entries

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

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 full burden. It states the tool lists available projects, which is a simple read operation. However, it does not disclose any additional behavior such as whether all projects are returned, authentication requirements, or pagination. For a zero-parameter tool, it is adequate but minimal.

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 sentence with no unnecessary words. It is well-structured and front-loaded with the verb and resource.

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?

Given the tool has zero parameters and no output schema, the description is mostly complete. It explains what the tool does and its purpose. It could be improved by noting that it returns all projects, but the simplicity of the tool does not demand more.

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?

There are no parameters, and schema coverage is 100% trivially. The description adds no parameter information, but none is needed. Baseline 3 is appropriate per guidelines.

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 verb 'List' and the resource 'projects', and specifies the context 'available for timesheet entries'. It distinguishes from sibling tools like create_project and list_timesheet_entries by focusing solely on listing projects.

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 implies usage for retrieving projects for timesheet entries, which is clear. However, it does not explicitly state when not to use this tool or mention alternatives like list_timesheet_entries. Nonetheless, the context is unambiguous.

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

list_timesheet_entriesA

List timesheet entries with optional filters for date range, project, and pagination

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoMaximum number of entries to return (default: 50)
offsetNoNumber of entries to skip for pagination (default: 0)
end_dateNoFilter entries until this date (YYYY-MM-DD)
project_idNoFilter entries by project ID
start_dateNoFilter entries from this date (YYYY-MM-DD)

TDQS

A3.9/5.0
Behavior3/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. It states the tool lists entries with optional filters and pagination, which is adequate for a simple read operation. However, it does not disclose any behavioral traits beyond what is inferred, such as default ordering or response format. There is no contradiction with annotations.

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

Conciseness5/5

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

The description is a single sentence of 14 words, concise and front-loaded with the main action. It contains no superfluous information and efficiently communicates the purpose.

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?

Given the tool has no output schema and no annotations, the description is somewhat minimal. It covers the inputs well but does not describe the return format, default behavior, or any edge cases. For a list tool with 5 optional parameters, the description is adequate but could be more complete in explaining what the response looks like.

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?

Schema description coverage is 100% for all 5 parameters, each with clear descriptions. The description adds a summary of parameter categories (date range, project, pagination) but does not provide additional meaning beyond what the schema already offers. Baseline score of 3 is appropriate.

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 specifies the verb 'List', the resource 'timesheet entries', and the scope 'with optional filters for date range, project, and pagination'. It distinguishes from sibling tools like get_timesheet_entry (single entry) and create/update/delete (mutations).

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 implicitly states when to use by listing optional filters, suggesting it is for listing entries with filtering. However, it lacks explicit guidance on when not to use, such as recommending get_timesheet_entry for a single entry or list_projects for projects. Still, the context from sibling tool names helps.

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

loginA

Login to your timesheet account via browser. Opens a browser window where you can enter your credentials. Use this after logout or to manually authenticate.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.4/5.0
Behavior4/5

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

With no annotations, the description reveals key behavioral traits: it opens a browser window for credential entry, indicating user interaction is required. It does not detail session handling or errors, but the interactive nature is transparent.

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 two sentences, front-loaded with the purpose, and every sentence adds value. No redundancy or wasted words.

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 essential aspects: what the tool does, how it works, and when to use it. Given no output schema and no parameters, it is reasonably complete for a simple login tool.

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 input schema has zero parameters, so there is no need for parameter descriptions. According to the guideline, 0 parameters scores a baseline of 4.

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 uses a specific verb 'login' and identifies the resource 'timesheet account' and method 'via browser'. It clearly distinguishes from sibling tools, especially logout, by stating its purpose and usage context.

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 explicitly states when to use the tool: 'after logout or to manually authenticate'. Although it doesn't list alternatives, the simplicity of login and the presence of a sibling logout tool make the guidance clear.

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

logoutA

Logout from the current timesheet session. Clears stored authentication tokens. You will need to re-authenticate (via browser login) on the next request.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.3/5.0
Behavior4/5

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

No annotations are provided, so the description must fully disclose behavior. It states that tokens are cleared and re-authentication is required, which covers the key destructive side effects. However, it does not mention if the server-side session is invalidated or other potential impacts.

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: two sentences with no unnecessary words. The first sentence states the primary action, and the second explains the consequence and next steps. It is front-loaded and 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?

Given no parameters, no output schema, and a simple purpose, the description is complete. It covers what the tool does, its effects (clears tokens), and what the user should expect next (re-authentication). No additional information is needed.

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 tool has no parameters, and the schema is fully covered (100%). The description does not need to elaborate on parameters. The baseline score of 4 is appropriate.

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: 'Logout from the current timesheet session'. It specifies the action (logout) and resource (current timesheet session). The mention of clearing authentication tokens and needing re-authentication distinguishes it from the sibling tool 'login'.

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 for ending a session but does not explicitly state when to use this tool versus alternatives. There is no guidance on when not to use it or mention of related tools. The sibling 'login' provides context, but explicit usage conditions are missing.

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

update_timesheet_entryC

Update an existing timesheet entry. Only provided fields will be updated.

ParametersJSON Schema
NameRequiredDescriptionDefault
dateNoNew date in YYYY-MM-DD format
hoursNoNew hours value (must be positive)
billableNoNew billable status
entry_idYesThe ID of the entry to update
project_idNoNew project ID
descriptionNoNew description

TDQS

C2.9/5.0
Behavior2/5

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

With no annotations, the description carries full burden but only states 'Only provided fields will be updated.' No disclosure of success/failure behavior, side effects, permissions, or idempotency. This is insufficient for a mutation tool.

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?

Two concise sentences, front-loaded with the action. Every word earns its place with no redundancy or clutter.

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?

Despite high schema coverage, the description omits critical context for a mutation tool: expected return value, error conditions, required permissions, and effect on related records. The partial update behavior is mentioned but not expanded upon.

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?

Input schema covers all 6 parameters with descriptions (100% coverage). The description adds behavioral context that only provided fields are updated, which slightly enhances parameter meaning beyond the schema. Baseline 3 is appropriate.

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

Purpose4/5

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

Description clearly states the verb ('Update') and resource ('timesheet entry'), distinguishing it from sibling tools like create, delete, and get. However, it could be more specific about the scope of updates (e.g., partial update behavior is mentioned but not emphasized).

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 guidance on when to use this tool vs alternatives like create_timesheet_entry or delete_timesheet_entry. No prerequisites, when-not-to-use, or context are provided.

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

Tool Schema Changelog

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

  1. 9 tool updatesv1.0.0
    • First observedcreate_project
    • First observedcreate_timesheet_entry
    • First observeddelete_timesheet_entry
    • First observedget_timesheet_entry
    • First observedlist_projects
    • First observedlist_timesheet_entries
    • First observedlogin
    • First observedlogout
    • First observedupdate_timesheet_entry

TDQS

A3.7/5.0

Scored across 9 tools

Disambiguation5/5

Each tool targets a distinct action and resource. Login and logout are separate from project and timesheet entry operations, and CRUD tools for timesheet entries are clearly delineated.

Naming Consistency4/5

Most tools follow a verb_noun pattern (e.g., create_project, list_timesheet_entries), but 'login' and 'logout' are single words, breaking the pattern slightly. Overall structure is clear.

Tool Count5/5

With 9 tools spanning authentication, project management, and timesheet entry CRUD, the count is well-scoped for the domain without being excessive or thin.

Completeness4/5

Core workflows are covered: authentication, project listing and creation, and full CRUD on timesheet entries. Missing project update/delete, but these are less critical for typical timesheet use.

Maintenance

ActivityInactive
ResponsivenessNo issues

Related MCP Connectors

Related MCP Servers

  • F
    license
    Not graded
    quality
    D
    maintenance
    A comprehensive MCP server for time tracking, project management, and AI-powered memory storage using semantic search. It enables users to log time, manage client billing, and capture shared or personal ideas through integrated tools and team collaboration features.
    1
    -
  • F
    license
    A
    quality
    D
    maintenance
    An MCP server that wraps the TimePRO API, enabling AI assistants to automatically create, view, and manage timesheets for authenticated users. It provides tools for searching clients and projects, retrieving configuration defaults, and performing full CRUD operations on timesheet entries.
    10
    -