The Timebook server lets AI agents manage time tracking across users, projects, clients, timers, and time entries.
Account & Discovery
whoami — Retrieve the authenticated user's id, email, and name
list_projects — List all available projects (id, name, client)
list_clients — List all available clients
Timer Management
get_active_timer — Check if a timer is running (returns project, description, started_at, or null)
start_timer — Start a timer on a project (optional description/rate); automatically stops any existing timer
stop_timer — Stop the currently running timer
Time Entry Logging & Management
log_time — Log a manual past entry using a duration (e.g. 1h30m) or explicit start/end timestamps, with optional rate and description
list_entries — List recent time entries (default 50, max 500), filterable by project and date range
update_entry — Edit any fields on an existing entry (description, duration, start/end time, project, rate); token must own the entry
delete_entry — Delete a time entry; token must own it and it must not be invoiced
Client & Project Creation
create_client — Create a new client with optional email
create_project — Create a new project under a client, with optional description
Command-line client and MCP server for Timebook — track time, manage timers, and expose your Timebook account to AI agents (Claude, Codex, Cursor, …) over the Model Context Protocol.
# one-off
npx @squidcode/timebook login
# globally
npm install -g @squidcode/timebook
timebook --helpRequires Node.js 18.17+.
Related MCP server: mcp-freshbooks
timebook login opens your browser, you log into Timebook (or use an existing session) and pick a scope (which clients/projects this token can touch). The browser delivers the token back to a short-lived loopback HTTP listener, which the CLI then writes to a config file with 0600 permissions.
timebook loginThe token is stored at:
macOS: ~/Library/Preferences/timebook/config.json
Linux: ~/.config/timebook/config.json
Windows: %APPDATA%\timebook\Config\config.json
The token never leaves your machine after login. To revoke it server-side, visit https://usetimebook.com/settings/api-tokens.
timebook whoami
timebook projects # list projects
timebook clients # list clients
timebook start -p "Acme website" -d "Wireframes"
timebook status # show running timer
timebook stop
# manual entries
timebook log -p "Acme website" -t 1h30m -d "Code review"
timebook log -p PROJ_ID --start 2026-05-04T09:00 --end 2026-05-04T10:30
timebook entries --project "Acme website" -n 10
# edit / delete (any combination of fields; unset ones stay as-is)
timebook entries edit ENTRY_ID -t 2h -d "code review + tests"
timebook entries edit ENTRY_ID --start 2026-05-04T09:00 --end 2026-05-04T11:00
timebook entries edit ENTRY_ID -d "" # clear description
timebook entries delete ENTRY_IDDuration formats accepted: 1h, 45m, 1h30m, 1.5h, 1:30, or a bare number (interpreted as minutes — e.g. 90 → 1h 30m).
Edit / delete authorization: an API token can only modify entries it created itself. JWT sessions (the web UI) and admin tokens bypass this rule. Invoiced entries are locked for everyone via the API. A 403 with a friendly message is returned on a denied attempt — fix the entry from the web UI or with the token that created it.
The same binary speaks MCP over stdio when invoked with timebook mcp. Drop it into any MCP-aware host (Claude Code, Claude Desktop, Codex, Cursor, …):
{
"mcpServers": {
"timebook": {
"command": "npx",
"args": ["-y", "@squidcode/timebook", "mcp"]
}
}
}Or, if installed globally:
{
"mcpServers": {
"timebook": {
"command": "timebook",
"args": ["mcp"]
}
}
}The MCP server reuses the token saved by timebook login — run timebook login once in a terminal before starting the agent.
Timebook also runs as a hosted Streamable-HTTP MCP server at https://usetimebook.com/mcp with full OAuth 2.0 (Dynamic Client Registration + PKCE + refresh-token rotation). No CLI install required — Claude.ai discovers it via the standard well-known endpoints:
Auth-server metadata: https://usetimebook.com/.well-known/oauth-authorization-server
Resource metadata: https://usetimebook.com/.well-known/oauth-protected-resource/mcp
Connect from Claude.ai → Settings → Connectors → Add → paste https://usetimebook.com/mcp. You'll be redirected to Timebook's consent page once, then Claude can use all the same tools listed below. Same OAuth-style permissions you'd see for any first-class connector.
The HTTP endpoint also accepts Authorization: Bearer tbk_* (your existing API token) for any client that prefers token-paste over OAuth — including server-to-server use.
Tool | What it does |
| Current authenticated user (read-only) |
| All projects in scope (read-only) |
| All clients in scope (read-only) |
| The running timer, or |
| Start a timer on a project |
| Stop the running timer |
| Log a manual entry ( |
| Recent entries (default 50, max 500), project + date filters |
| Edit one or more fields on an entry (description, duration, startTime, endTime, project, rate). Token must own the entry. |
| Delete an entry. Token must own it. Invoiced entries are locked. |
Once the MCP server is connected, ask the model in plain English:
"Start a timer on my Acme website project for landing-page wireframes."
"How much time did I log on the Recycler project last week?"
"Log 1 hour 30 minutes against ChatNexus from 9am this morning at the Software Development rate, with description 'code review of the auth refactor'."
"What am I currently working on?" — invokes get_active_timer.
"Stop my timer."
"My last entry on Recycler should be 2 hours, not 1h45m. Fix it." — invokes list_entries then update_entry.
"Delete the entry I just made by mistake." — invokes delete_entry. Will 403 if the entry was created by a different token (web UI, another agent) — say so to the model so it doesn't keep retrying.
The model picks the right tool, asks list_projects first if it needs to disambiguate a name, and writes through start_timer / log_time / stop_timer.
Timebook CLI runs on your machine and only talks to your Timebook account.
Authentication: timebook login mints a personal API token via Timebook's OAuth-style consent screen. The token is stored locally with 0600 permissions (~/Library/Preferences/timebook/config.json on macOS, ~/.config/timebook/config.json on Linux, %APPDATA%\timebook\Config\config.json on Windows). It is never transmitted anywhere except https://usetimebook.com (or your override) on outgoing API calls.
Telemetry: none. Neither the CLI nor the MCP server reports usage, errors, or analytics anywhere.
MCP host data: when you use timebook mcp from inside Claude / Cursor / etc., the MCP host (not Timebook) controls what the model sees. Tool inputs and outputs flow through the host's normal model-context pipeline.
Revoking access: visit https://usetimebook.com/settings/api-tokens to revoke the token at any time.
For Timebook's product-level privacy policy, see https://usetimebook.com/privacy.
Override the API/web hosts (useful for self-hosted Timebook or local dev):
TIMEBOOK_API_URL=https://api.example.com \
TIMEBOOK_WEB_URL=https://example.com \
timebook loginYou can also pass --api-url and --web-url to timebook login once; subsequent commands re-use the saved values.
If timebook login errors with State mismatch or you want to see exactly which requests reach the loopback callback, run with --debug:
timebook login --debuggit clone https://github.com/squidcode/timebook-cli
cd timebook-cli
npm install
npm run dev -- --help # tsx-powered hot-loop
npm run build # emits dist/
npm run lint && npm run typecheck && npm run testPre-commit hooks (ESLint + Prettier via lint-staged) are wired up by husky on npm install.
prepublishOnly runs lint + typecheck + tests + build, then:
npm publish --access publicMIT © Squidcode LLC. See LICENSE.
Create a client (the person/company you bill). Needed before any project or time entry can exist. Typical first step on a fresh account.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Client name, e.g. 'Acme Corp'. | |
| No | Optional billing/contact email. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false and destructiveHint=false, so the description adds no new behavioral traits beyond the 'create' action. Description is consistent with annotations, no contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, front-loads core purpose, no extraneous information. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 parameters, no output schema), the description covers purpose, prerequisite relationship, and typical usage comprehensively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers both parameters with descriptions (100% coverage). Description reiterates email as optional but does not add additional meaning beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states verb 'create' and resource 'client', defines it as the person/company billed, and explains it is a prerequisite for projects/time entries. Differentiates from siblings like list_clients and create_project.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says it's the typical first step and needed before other entries, providing good context for when to use. Does not explicitly list when not to use or mention alternatives, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a project under a client. Time entries are always tracked against a project. Typical second step on a fresh account, after create_client.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Project name, e.g. 'Website redesign'. | |
| client | Yes | Client - id or exact name. | |
| description | No | Optional project description. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=true. The description adds value by explaining that time entries are tracked against projects, which is useful behavioral context beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two sentences, front-loading the purpose and providing relevant workflow context without unnecessary verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 3 parameters, no output schema, and no nested objects, the description provides sufficient context: purpose, workflow context, and key association with time entries. It is complete enough for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all three parameters. The tool description does not add additional meaning beyond the schema, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a project under a client and provides the context that time entries are tracked against projects. It also distinguishes itself from siblings by noting it's the typical second step after create_client, which differentiates it from other tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear usage context by stating it's the typical second step after create_client, implying when it should be used. It doesn't explicitly mention when not to use or alternatives, but the context is sufficient for an agent to decide.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a time entry. Server enforces: not invoiced, and either this token created it or the caller is an admin / web session.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Entry id (uuid). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark destructiveHint=true and readOnlyHint=false. The description adds specific enforcement rules (auth, invoice status), providing context beyond annotations. No contradiction found.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences that front-load the main action and immediately add critical constraints. No filler or unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete tool with one parameter, no output schema, and annotations covering destructiveness and idempotency, the description adds the key server-enforced rules. Lacks mention of response or error behavior but is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'id' is fully described in the schema (uuid). The description adds no extra meaning, so baseline 3 is appropriate given 100% schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Delete a time entry' with specific verb and resource. It distinguishes from siblings (e.g., list_entries, update_entry) and adds server-enforced constraints, making the tool's purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides usage guidelines by noting server enforcement conditions (not invoiced, caller must be creator or admin/session). This implies when the tool can be used but does not explicitly state when not to use or suggest alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the currently running timer (project, description, started_at), or null if no timer is running.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only, idempotent, and open-world. The description adds behavioral details about return values (specific fields and null case), providing value beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with no wasted words. Front-loaded with the purpose, includes key details about return value and null case.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no parameters, no output schema, and annotations cover safety, the description is fully adequate for correct usage. It states what is returned and when null.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, and schema coverage is 100%. Baseline is 4, and description correctly implies no parameters are needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns the currently running timer, specifying the fields (project, description, started_at) and the null case. This distinguishes it from sibling tools like list_entries or start_timer.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for checking the active timer, but does not explicitly contrast with sibling tools like list_entries. However, given the name and context, usage is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all clients available to the current token.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint, idempotentHint, openWorldHint. Description adds no extra behavioral context but does not contradict.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, concise, front-loaded, no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with no params and good annotations, description is complete and adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters. Schema coverage is 100% (empty). Description does not need to add param info. Baseline 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists clients available to the current token, using a specific verb and resource. It distinguishes from sibling tool create_client.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use versus alternatives. Implied from sibling context, but no explicit when-not or alternatives mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List recent time entries, optionally filtered by project and/or date range. Returns at most 50 entries by default; pass a higher limit to see more.
| Name | Required | Description | Default |
|---|---|---|---|
| project | No | Optional project id or exact name. Omit to list across all projects. | |
| startDate | No | ISO-8601 — only entries whose start time is on or after this. | |
| endDate | No | ISO-8601 — only entries whose start time is on or before this. | |
| limit | No | Maximum number of entries to return. Defaults to 50. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavioral detail beyond annotations: it explains the default return limit (50) and the ability to increase it up to 500 via limit parameter. Annotations already indicate read-only and idempotent behavior, which is consistent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, front-loaded with purpose, then key behavioral constraint. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers input filtering and limit behavior but omits return format (fields of each entry), ordering, and the exact meaning of 'recent'. Given no output schema, the agent lacks sufficient detail to fully understand the response structure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% of parameters with descriptions. The description effectively summarizes the filtering capability and limit default but does not add new semantic information beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists time entries with optional filtering by project and date range. It distinguishes itself from sibling 'list_clients' and 'list_projects' via the resource type. However, the term 'recent' is ambiguous – it implies a default time window that is not defined.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives like 'get_active_timer' or 'log_time'. The description does not mention related tools or scenarios where this tool is preferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all projects available to the current token. Returns id, name, and client for each project.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint; description adds token scoping and that only available projects are returned, consistent 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two succinct sentences, no wasted words, front-loaded with verb and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Describes return fields (id, name, client) and token scoping; no output schema needed, complete for a simple listing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters; schema coverage 100% and description adds no param info, but baseline for 0 params is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states verb 'List' and resource 'projects', specifies returned fields (id, name, client), and distinguishes from sibling tools like list_clients.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implicitly clear about usage (list all projects for current token), but lacks explicit when-not-to-use or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Log a manual (past) time entry. Provide either duration (relative to now), or both startTime and endTime (absolute ISO-8601 timestamps).
| Name | Required | Description | Default |
|---|---|---|---|
| project | Yes | Project id (UUID) or exact project name. | |
| description | No | What the user worked on. | |
| duration | No | How long the work took. Accepts "1h", "45m", "1h30m", "1.5h", "1:30", or "90" (interpreted as minutes). | |
| startTime | No | ISO-8601 start time (e.g. "2026-05-04T09:00:00Z"). Required if duration is omitted. | |
| endTime | No | ISO-8601 end time. Required if duration is omitted. | |
| rate | No | Optional rate id or exact rate name (e.g. "Software Development"). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a write operation (readOnlyHint=false). Description adds that it logs past entries, but does not further disclose behavioral traits (e.g., whether it overwrites existing entries, permission requirements). Acceptable bar with annotations present.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose, efficient in wording, no extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 6 parameters with conditional rules and no output schema, the description covers the essential usage logic. Lacks mention of return value or error handling, but these are not critical for selection/invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers all 6 parameters with descriptions. Description adds value by explaining the conditional relationship between duration and startTime/endTime, and clarifies that duration is relative to now, which is not in schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Log a manual (past) time entry,' specifying the action (log), resource (time entry), and context (past). Distinguishes from sibling tools like start_timer/stop_timer which handle active timers.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear guidance on the conditional use of duration vs. startTime/endTime. However, does not explicitly contrast with sibling tools (e.g., start_timer) to advise when not to use log_time.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Start a timer on a project. Stops any other running timer first — Timebook allows only one active timer at a time.
| Name | Required | Description | Default |
|---|---|---|---|
| project | Yes | Project id (UUID) or exact project name. Use list_projects to discover. | |
| description | No | What the user is working on (visible in the time entry). | |
| rate | No | Optional rate id (UUID) or exact rate name (e.g. "Software Development"). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes beyond annotations by clearly stating the non-obvious side effect of stopping any other running timer. This is critical for an agent to understand the tool's behavior, especially since annotations only indicate it's not read-only.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with two sentences that front-load the essential purpose and key behavioral constraint. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (3 parameters, 1 required, no output schema), the description covers the core behavior and side effects. It could mention error handling or prerequisites, but overall it is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already has 100% coverage with detailed descriptions for each parameter. The tool description does not add additional semantic information beyond what is in the schema, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Start a timer on a project' and notes it stops any other running timer, clearly distinguishing it from sibling tools like stop_timer or get_active_timer.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains that it stops any other running timer because only one active timer is allowed, providing clear context for when to use. It does not explicitly list alternatives or when not to use, but the behavior is adequately explained.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Stop the currently running timer. Returns { stopped: false } if no timer was running.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide destructiveHint and idempotentHint. Description adds detail about the return value for the edge case of no running timer, which is useful beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded, no wasted words. Ideal conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no params and no output schema, the description covers the action and a key edge case. Could mention idempotency or side effects, but sufficient for a simple tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters, so baseline 4. Description adds no parameter info, but none needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Stop the currently running timer' with a specific verb and resource. Distinguishes from siblings like start_timer and get_active_timer.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies usage when wanting to stop a timer, but no explicit when-not-to-use or alternatives. The return value hint helps but lacks full guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Edit one or more fields on an existing time entry. Any combination is valid; unset fields are left as-is. Server-enforced authorship rule: this token can only edit entries it created itself (sessions and admins bypass).
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Entry id (uuid). | |
| description | No | New description / note. Pass empty string or null to clear. | |
| duration | No | New duration, e.g. "1h30m" or "45m". | |
| startTime | No | ISO-8601 start time. | |
| endTime | No | ISO-8601 end time. | |
| project | No | Reassign — project id or name. | |
| rate | No | New rate — id or name. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true), the description adds the critical server-enforced authorship rule and the partial update behavior ('unset fields are left as-is'), providing significant behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with zero waste. The first sentence states the purpose, and the second adds two important notes (flexibility of fields, authorship rule) in a compact manner.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description effectively covers the tool's purpose, usage, and behavioral constraints. However, it does not mention the return value (e.g., whether it returns the updated entry or just a success status), which could be inferred but is not explicit. This minor gap prevents a perfect score.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for each parameter, so the baseline is 3. The description adds some value by explaining the flexibility of field combination, but does not add new details about individual parameters beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Edit' and the resource 'time entry', and it distinguishes from sibling tools like delete_entry and log_time by specifying it edits existing entries.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use guidance with 'Any combination is valid; unset fields are left as-is' and crucial context about the authorship rule, telling the agent when the tool can and cannot be used.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the currently authenticated Timebook user (id, email, name).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only and idempotent behavior. The description adds value by specifying the exact fields returned, which is beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with no wasted words. Front-loads the purpose and output structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters and no output schema, the description fully covers what the tool does and returns. No missing information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist (schema coverage 100%). The description correctly implies no input needed, which is the baseline for zero-parameter tools.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns the currently authenticated user with specific fields (id, email, name). It contrasts with sibling tools that handle CRUD operations on other resources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
While no explicit when/why guidance is given, the simplicity and read-only nature make the use case obvious. It is implicitly the tool to use for checking the current user's identity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Each tool targets a distinct action and resource. For example, create_client is clearly different from start_timer, and list_clients is separate from list_projects. There is no ambiguity between tools.
All tool names follow the imperative verb_noun pattern (e.g., create_client, delete_entry, stop_timer). The only exception is whoami, which is a common standalone command but still consistent with the overall style.
12 tools cover the essential operations for a time tracking service: client and project management, time entry CRUD, timer control, and user info. This is a well-scoped set without excess or deficiency.
The tool set covers the core lifecycle: create and list clients/projects, log and update time entries, and timer operations. Minor gaps like missing update/delete for clients and projects suggest room for improvement, but the core workflow is complete.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
MCP server for Codat — companies, connections, invoices, bills and financial statements.
Hosted MCP server with managed OAuth for 15+ toolkits: Google Workspace, Fitbit, Oura, Kalshi, etc.
Hosted MCP server for Mini Accountant: invoices, expenses, customers, analytics, tax estimates.
Read-only MCP server for ClassQuill, a tutoring-business-management platform.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/squidcode/timebook-cli'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
