Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@ATimeLogger MCP Server show me today's time report"
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.
A standalone MCP (Model Context Protocol) server that exposes the ATimeLogger REST API to AI assistants — locally over stdio (Claude Desktop / Claude Code / OpenAI Codex) or remotely as a connector (claude.ai in the browser, Claude mobile apps, ChatGPT). Scope: activities (start/stop/pause/log), reports/history, and activity types.
The same package also installs atimelogger-cli — a read-only JSON CLI that needs no AI assistant at all. Use it from cron jobs, status bars, and shell pipelines; it shares the server's internals (fuzzy type names, period words, DST-correct timezones) but runs entirely on its own. A library entry point covers the third case, calling ATimeLogger in-process from your own code.
Requires Node 20+.
Generate a Personal Access Token in the ATimeLogger web app: Settings → API Tokens → Generate token. The value (starting with atl_pat_) is shown only once — copy it right away. You can revoke the token from the same page at any time.
Register the server. No install or build step needed — npx fetches the published package on first run:
Claude Code — a one-liner:
claude mcp add atimelogger \
-e ATL_TOKEN=atl_pat_... \
-- npx -y atimelogger-mcpClaude Desktop — a JSON block to merge into ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows), then restart Claude Desktop:
{
"mcpServers": {
"atimelogger": {
"command": "npx",
"args": ["-y", "atimelogger-mcp"],
"env": {
"ATL_TOKEN": "atl_pat_..."
}
}
}
}OpenAI Codex (CLI, IDE extension, or the ChatGPT desktop app's Codex mode) — also a one-liner; the configuration is shared by all three Codex surfaces:
codex mcp add atimelogger --env ATL_TOKEN=atl_pat_... -- npx -y atimelogger-mcpEquivalent ~/.codex/config.toml block:
[mcp_servers.atimelogger]
command = "npx"
args = ["-y", "atimelogger-mcp"]
env = { "ATL_TOKEN" = "atl_pat_..." }MCP support in Codex is not gated by plan — it works with any ChatGPT subscription that includes Codex, or with a plain API key. (Using the tools from the ChatGPT web/mobile app is a different path — see Connect from ChatGPT below.)
Instead of the published package, you can clone and build:
git clone https://github.com/zaplitny/atimelogger-mcp && cd atimelogger-mcp
npm install
npm run build
npm run setup # paste the token, verifies it, prints registration snippets pointing at the local buildTroubleshooting: a 401 from any tool means the token is invalid, expired, or was revoked — generate a new one in Settings → API Tokens and update ATL_TOKEN in the MCP config.
No token yet? The server also starts without ATL_TOKEN in docs-only mode: the app_help tool (official app documentation) works, so you can ask your assistant how ATimeLogger features work before setting up API access; the time-tracking tools return setup instructions until a token is configured.
Related MCP server: Toggl MCP Server
Tool | Purpose |
| Running/paused activities with elapsed time |
| Activity type names as a group tree (source of names for other tools) |
| Start by type name; optional backdating ( |
| Stop the active activity (name optional if only one is active); same backdating options |
| Pause or resume |
| Retroactively log a completed entry (wall-clock times, optional comment/tags) |
| Change the comment/tags of an existing entry (running or past) without touching its times |
| Aggregated per-type statistics for a period ( |
| Raw history grouped by day, paged, max 100-day range |
| Official app documentation (atimelogger.pro/docs) — the assistant looks up how app features work (goals, widgets, sync, export, …) instead of guessing |
Tools accept human-readable type names (fuzzy matched); internal ids also flow through tool outputs and parameters for exact targeting, but are never shown to the user. Durations are returned as "2h 15m" strings; times are shown in the user's ATimeLogger timezone unless a timezone parameter is given.
Things you can say to your assistant once the server is registered:
Timers
"Start tracking work" · "Stop the timer" · "Pause reading, I'll be back in 10" · "What am I tracking right now?"
Backdating — forgot to press start or stop:
"Start Development — I actually began at 11:30" · "Stop work, I finished 20 minutes ago" · "I've been in a meeting since 14:00, track it"
Logging past activities
"Log 2 hours of Reading yesterday from 9 to 11pm" · "Add a gym session for last Saturday morning, 90 minutes, tag it 'legs'" · "I slept from 23:30 to 7:15, log it"
Annotating existing entries
"Add a note to the current timer: reviewing the Q3 report" · "Tag this morning's Work session with 'client-x'" · "Update yesterday's meeting entry — it was the architecture sync"
Reports & history
"Where did my week go?" · "How much did I work in June, broken down by week?" · "Compare my sleep this month vs last month" · "Show everything I tracked today" · "Which day last week had the most Development time?"
Learning the app — answered from the official documentation rather than guesswork:
"How do goals work?" · "Why isn't my sync picking up yesterday's entries?" · "What's the difference between a group and a type?" · "Can I export to CSV?" · "How do I edit an entry's times?"
Combinations — the assistant chains tools on its own:
"Stop whatever is running and start Work" · "Continue from where the last entry ended — start Development from that time" · "Fill yesterday's gap between lunch and the meeting with Reading"
Activity names are fuzzy-matched against your own type list, so "start dev" finds "Development"; the assistant asks when a name is ambiguous.
atimelogger-cli is installed by the same package and stands on its own — no MCP client, no assistant, no API key beyond the same ATL_TOKEN. It is a read-only JSON CLI for scripts and automation (cron jobs, status bars, shell pipelines) where speaking MCP is impractical, and it reuses the internals the MCP tools are built on: fuzzy type names, period words, DST-correct timezones, humanized durations.
export ATL_TOKEN=atl_pat_...
npx -y -p atimelogger-mcp atimelogger-cli status
atimelogger-cli report --period this_week --type work
atimelogger-cli intervals --period yesterday --tag gym --compact | jq .Commands: status, types, report, intervals, plus doctor — run atimelogger-cli --help for all options. doctor is the first thing to run when something is off: it checks the token's presence and shape, whether the host is reachable, whether the token still authenticates, and whether the account has trackable types, telling you which layer broke instead of leaving you to guess. It exits 1 when unhealthy and never echoes the token. Output is always JSON (pretty by default, --compact for one line) with stable keys: durations carry both a humanized string and raw seconds, paging is a has_more boolean, and empty results give [] rather than dropping the key — so jq pipelines don't break on a quiet day. Errors go to stderr as {"error": "..."} with exit code 1 (2 for usage mistakes, including an unresolvable --type). The CLI never starts, stops, or edits anything — write operations stay in the MCP server, where a human is in the loop; scripted writes from cron are retry-prone and can corrupt your timeline.
The package also exports its task-shaped core, so a long-running process can call ATimeLogger in-process instead of spawning a binary per request — useful for daemons, bots, editor plugins, or anything that wants the conveniences (fuzzy type names, period words, DST-correct timezones, humanized durations) without the MCP transport.
import { createClient, clientFromEnv } from "atimelogger-mcp";
const atl = createClient({ token }); // credentials passed explicitly
// …or, for the single-account case, read ATL_TOKEN + ATL_BASE_URL:
// const atl = clientFromEnv();
// reads
const { active } = await atl.status();
const { duration, seconds, by_type } = await atl.report({ period: "this_week", type_names: ["work"] });
const { days, has_more } = await atl.intervals({ period: "yesterday" });
// writes
await atl.start({ type_name: "development", started_minutes_ago: 10 });
await atl.stop(); // name optional if one is active
await atl.pauseResume({ action: "pause" });
await atl.log({ type_name: "reading", from: "2026-08-05 21:00", to: "2026-08-05 22:30" });
await atl.update({ activity_id, comment: "architecture sync" });
await atl.api.get("/api/…"); // escape hatch for anything unwrappedPrefer clientFromEnv() over hand-rolling createClient({ token: process.env.ATL_TOKEN }) — the latter ignores ATL_BASE_URL and would silently target production. Unlike the MCP server and the CLI, it throws rather than exiting the host process when no token is configured.
Writes are part of the client rather than something you assemble against api, because the sequencing matters: update does a read-modify-write, since a raw PUT soft-deletes every interval missing from the payload and would silently destroy the entry's tracked time. (The CLI stays read-only for a different reason — unattended shell retries, not programs.)
Results are fully typed (CurrentStatus, TimeReport, IntervalsPage, StartedActivity, …), and every field is present unless its type marks it optional — days, active and by_type are empty arrays rather than missing keys, so destructuring is safe on empty results. Durations come as both a humanized string and raw seconds. Errors are typed too: UsageError (bad arguments or an unresolvable type name), ApiError (the server answered with a failure, carries .status), NetworkError (the request never arrived, keeps the original as .cause).
Each client owns its own HTTP client and caches, so several accounts can coexist in one process. A fetch override makes fixture-backed testing straightforward, with no network access:
const atl = createClient({ token: "test", baseUrl: "https://example.test", fetch: fakeFetch });app_help is not part of this surface — it answers from the public documentation site rather than the account, so it stays an MCP tool.
These clients are purely in-process — no daemon, no persisted state, nothing shared between invocations; keep the process alive to keep the caches warm. Importing the library never reads the environment. Experimental while the package is 0.x: signatures may change in a minor release, so pin an exact version if you depend on them.
Besides the local stdio setup above, the server can run as a remote MCP server and connect to Claude as a Custom Connector — or to ChatGPT via Developer Mode (section C). This is the path to use if you want to reach your ATimeLogger data from claude.ai in the browser, the Claude mobile apps, or the ChatGPT web/mobile apps, where local stdio servers aren't available.
There are two audiences here: people who just want to connect to a running endpoint, and people who want to self-host their own.
If you have the HTTPS URL of a running instance (for example one you host yourself, per section B):
Open claude.ai in a browser (desktop or mobile). The one-time "add" step is done in the web UI; once added it also shows up in the mobile apps.
Go to Settings → Connectors → Add custom connector.
Enter a name (e.g. ATimeLogger) and the server URL, ending in /mcp:
https://your-host.example.com/mcpClick Add.
In any chat, open the + menu → Connectors and toggle the connector on.
Then talk to Claude as usual — "what am I tracking right now?", "where did my week go?", etc. (see Usage examples). On mobile it works the same way once the connector is enabled for the conversation.
Note on how Claude reaches your server. Custom connectors connect from Anthropic's cloud infrastructure, not from your own device — this is true even in the mobile apps and Claude Desktop. Your endpoint must be reachable over the public internet. A server on
localhost, behind a VPN, or blocked by a firewall won't connect even though you can reach it from your own machine.
The server speaks stdio, so to expose it over HTTPS you put a small proxy in front that serves it over Streamable HTTP, then terminate TLS with a reverse proxy. One working setup:
1. Run the server behind an HTTP proxy, in Docker. The host only needs Docker — no source checkout, no Node install. The image pulls the published npm package plus mcp-proxy, which serves the stdio server over Streamable HTTP:
FROM node:22-slim
RUN npm i -g atimelogger-mcp mcp-proxy
EXPOSE 8080
CMD ["mcp-proxy", "--port", "8080", "--", "atimelogger-mcp"]Pin a version (npm i -g atimelogger-mcp@0.1.0) if you want reproducible rebuilds; to upgrade later, rebuild with --no-cache (or bump the pin) and recreate the container.
Build and run it, bound to localhost only, with your token passed as an env var:
docker build -t atimelogger-mcp .
docker run -d --name atimelogger-mcp \
-p 127.0.0.1:9095:8080 \
--restart unless-stopped \
-e ATL_TOKEN=atl_pat_your_token_here \
atimelogger-mcpVerify it's up locally (a bare GET returns 400 Bad Request — that's expected, it means the endpoint is listening and refusing an incomplete handshake):
curl -i http://127.0.0.1:9095/mcp2. Put a TLS reverse proxy in front. Example nginx location block inside your HTTPS server block. The streaming directives (proxy_buffering off, long proxy_read_timeout) matter — without them the connection stalls:
location /mcp {
proxy_pass http://127.0.0.1:9095/mcp;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
# streaming essentials
proxy_set_header Connection '';
proxy_buffering off;
proxy_cache off;
proxy_read_timeout 3600s;
chunked_transfer_encoding on;
}sudo nginx -t && sudo systemctl reload nginxYour public endpoint is now https://your-host.example.com/mcp — add it as a Custom Connector per section A.
3. Test before wiring up Claude (optional). The MCP Inspector confirms the endpoint independently:
npx @modelcontextprotocol/inspectorSet transport type to Streamable HTTP, enter the URL, and check that the handshake succeeds and the tool list appears.
Security — read before exposing this. The remote server is authenticated by the single
ATL_TOKENbaked into the container, so anyone who can reach the URL acts as you against your ATimeLogger account. There is no per-user login at the MCP layer. If you self-host:
Keep the endpoint private (don't publish the URL), or put an auth check in front of it (e.g. a required header or basic auth in nginx).
Only bind the container to
127.0.0.1(as above) so the raw HTTP port is never exposed directly — nginx stays the only public door.Treat the token like a password; rotate it from Settings → API Tokens if it's ever exposed.
The same remote endpoint works in the ChatGPT web app as a custom MCP app via Developer Mode (paid plans). The exact settings location and flow change from time to time — follow the official guide: https://developers.openai.com/api/docs/guides/developer-mode. In short:
Enable Developer mode in ChatGPT settings (see the guide for where it currently lives).
Create a new app/connector for the server URL ending in /mcp, with authentication set to None (the ATimeLogger token lives server-side; see the security note above).
Enable it in a chat, then talk as usual — "what am I tracking right now?", "log 2 hours of reading yesterday 9 to 11pm".
Notes:
Set it up once in the web app; after that the connector also works in the ChatGPT mobile apps.
ChatGPT connects from OpenAI's infrastructure, so the endpoint must be publicly reachable — same rule as for Claude custom connectors.
Write actions (starting/stopping timers, logging entries) ask for confirmation in ChatGPT before running by default.
Plan, region, and feature limitations may apply and change over time — check the official documentation for the current state. (Don't confuse Developer Mode with ChatGPT's search/fetch-only connectors for Deep Research — this server exposes action tools, so Developer Mode is the path that works.)
start_activity cannot attach a comment (the underlying start endpoint takes only a type and time); add one afterwards with update_activity, or use log_interval for retroactive entries with comments/tags.
Only comments and tags of existing entries can be edited (update_activity); interval times cannot be changed and entries cannot be deleted — use the ATimeLogger app for that (the assistant can explain how via app_help).
History requests are capped at 100 days by the backend.
Official ATimeLogger app documentation. Use it to answer any question about how the app works, or how to do in the app what these tools cannot (edit entry times, delete records, goals, widgets, CSV export, sync, backups, Pomodoro, Premium features). Call with no arguments for the table of contents (its note covers platform applicability), then again with topics to fetch the relevant pages — answer from the docs, not from memory. Cross-references like sync.md inside a page point to the topic with that slug.
| Name | Required | Description | Default |
|---|---|---|---|
| topics | No | Topic slugs from the table of contents (fuzzy matched against slug and title). Omit to get the table of contents. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Although there are no annotations, the description conveys the tool's behavior: it's a documentation retrieval tool that returns the TOC or specific pages. It explains the two-step invocation, fuzzy matching, and cross-reference handling. It doesn't explicitly state it makes no modifications, but the documentation nature implies a non-destructive read operation. This is adequate transparency, though it could be more explicit about return format or side-effect absence.
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 information-dense but every sentence adds value. It starts with a clear identification, then usage examples, followed by practical instruction. There is no fluff or repetition; the structure is logical and easy to parse, making it appropriately sized for a documentation/help tool.
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 (one optional parameter, no output schema), the description is remarkably complete. It covers purpose, use cases, invocation pattern, parameter semantics, and behavior. It also lists specific topics it can answer about (edit times, delete records, etc.), which helps the agent know when to delegate to this tool. The lack of an output schema is mitigated by the clear explanation of what the tool returns (TOC or pages).
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 schema already describes `topics` as slug strings with fuzzy matching and omission for TOC. The description adds significant extra semantics: the recommended two-step workflow (first no args for TOC, then with topics), how cross-references map to slugs, and the note about platform applicability in the TOC. This goes beyond the schema, enhancing the agent's understanding of how to use the parameter effectively.
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 provides official ATimeLogger documentation and is used to answer questions about how the app works or how to do things the other tools cannot. This distinguishes it from sibling action tools like start_activity or time_report, making its purpose specific and 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?
It explicitly tells when to use the tool (for app questions or tasks other tools can't do, with examples), and gives a clear calling pattern: call with no arguments for the table of contents, then with `topics` to fetch pages. It also instructs to answer from the docs, not memory, and explains cross-references, providing comprehensive usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Show currently running or paused activities with elapsed time.
| Name | Required | Description | Default |
|---|---|---|---|
| timezone | No | IANA timezone for displayed times (default: user's timezone) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It does add useful scoping (only running or paused activities) and the notion of elapsed time, but it does not mention whether the operation is read-only, what happens if no activities are active, or how elapsed time is calculated. This is adequate for a simple getter but lacks deeper 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the key action and scope. Every word contributes meaning; there is no fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (one optional parameter, no output schema), so the description doesn't need to be exhaustive. However, since there is no output schema, an agent might benefit from knowing what fields are returned (e.g., activity name, elapsed time). The description gives a high-level idea but leaves these details implicit. Overall, it is minimally sufficient for the tool's simplicity.
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 schema provides 100% description coverage for the single optional 'timezone' parameter, meeting the schema itself. The description does not mention the parameter, but the schema already explains it fully. Baseline of 3 is appropriate since the description adds no extra semantic value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Show'), the resource ('currently running or paused activities'), and the additional detail ('with elapsed time'). This distinguishes it from siblings like list_activity_types (which lists activity types) and list_intervals (which lists historical intervals), so an agent can easily identify when to use this tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: it is for viewing live activity state, not historical reports. It does not explicitly name alternatives or exclusions, but the scope is unambiguous enough for an agent to infer when to use it. The lack of explicit 'when not to use' guidance drops it from 5 to 4.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the user's activity types as a tree (groups contain children): names plus internal ids. Use the names when talking to the user; use the ids for exact targeting in other tools.
| Name | Required | Description | Default |
|---|---|---|---|
| include_archived | No | Include archived types (default false) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses the tree structure and the semantic distinction between names and ids. It implies a read-only operation via 'List' and is transparent about what is returned, though it could mention default filtering behavior or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no fluff. The key action and result shape are front-loaded, and the usage guidance earns its place by explaining the name/id distinction.
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 one optional parameter and no output schema, the description provides sufficient context: what is listed, the tree structure, and how to use the returned data. The missing archived default is documented in the schema.
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 schema covers the only parameter include_archived with a description, so schema coverage is 100%. The description itself adds no parameter-specific meaning, but the baseline is 3 per rubric given high 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 states a specific verb ('List') and resource ('the user's activity types'), and clarifies the output format ('as a tree (groups contain children): names plus internal ids'). This clearly distinguishes it from sibling tools like list_intervals.
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 guidance: 'Use the names when talking to the user; use the ids for exact targeting in other tools.' This helps the agent decide how to apply the output, though it does not explicitly contrast with alternatives since none directly overlap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List raw time entries (intervals) grouped by day for a date range (max 100 days). Paged by day — use page for older days.
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | End date yyyy-MM-dd, inclusive | |
| from | No | Start date yyyy-MM-dd (use with `to`) | |
| page | No | Page number, 0-based (default 0) | |
| size | No | Days per page (default 20, max 50) | |
| tags | No | Filter to these tags | |
| period | No | Named period; alternative to explicit from/to | |
| timezone | No | IANA timezone (default: user's timezone) | |
| type_ids | No | Filter to these exact activity type ids (internal — never show ids to the user) | |
| type_names | No | Filter to these activity type names (groups allowed) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations available, the description carries the full burden. It discloses a 100-day limit, day-grouped output, and day-based pagination ('use page for older days'), which are key operational behaviors. It does not mention rate limits or authentication, but for a read-only list tool these are the most relevant constraints.
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, no filler, and the main purpose is front-loaded. Each sentence contributes useful information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 9 parameters, no annotations, and no output schema. The description covers date range and pagination but does not mention alternative date formats (period) or available filters (tags, type_ids, type_names). While the schema documents these, the description is not fully complete given the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds value by explaining that `page` advances to older days and that results are grouped by day, complementing the schema's parameter descriptions and giving extra meaning beyond the structured definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: listing raw time entries (intervals) grouped by day for a date range, with a 100-day maximum. This distinguishes it from siblings like list_activity_types (which lists type metadata) and time_report (likely aggregated), using a specific verb and resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives context (raw entries, date range, max 100 days) and hints at pagination for older days, but it does not explicitly compare this tool to alternatives like time_report or say when not to use it. Usage is implied rather than explicitly guided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retroactively log a completed time entry for an activity type. Times are wall-clock in the user's timezone, format "yyyy-MM-dd HH:mm".
| Name | Required | Description | Default |
|---|---|---|---|
| to | Yes | End, e.g. "2026-07-09 11:30" | |
| from | Yes | Start, e.g. "2026-07-09 09:00" | |
| tags | No | ||
| comment | No | ||
| type_id | No | Exact activity type id from list_activity_types (internal — never show ids to the user) | |
| timezone | No | IANA timezone the times are given in (default: user's timezone) | |
| type_name | No | Activity type name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must carry the behavioral disclosure burden. It does disclose that times are wall-clock in the user's timezone and the expected format, which is useful. However, it does not mention side effects (e.g., creating a record), prerequisites (which parameter is required: type_id or type_name), or output behavior, leaving significant behavioral context unknown.
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, front-loaded with the primary action, followed by a critical input-format constraint. Every sentence adds value, with no redundancy.
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 adequately conveys the purpose and a key input detail, but given 7 parameters and no annotations or output schema, it does not fully explain how to choose between type_id and type_name, whether either is required, or what the tool returns. The schema covers much, but optional params like tags/comment remain unexplained.
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 schema covers 71% of parameters with descriptions. The tool description adds the wall-clock/timezone context relevant to 'from' and 'to', but tags and comment are left undefined in both schema and description. Since coverage is above 50%, the baseline 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 uses a specific verb 'log' with a clear resource 'completed time entry' and the modifier 'retroactively', which clearly distinguishes it from sibling tools like start_activity/stop_activity that handle live tracking, and update_activity which modifies 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 clear context: this tool is for retroactively logging completed time entries. It implies when to use it (when an entry has already finished) but does not explicitly name alternatives or exclusions, so it falls just short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Pause a running activity or resume a paused one.
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | ||
| type_name | No | Which activity (needed only if several match) | |
| activity_id | No | Exact activity id from get_current_status (internal — never show ids to the user) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It mentions the required activity state but does not disclose side effects, error conditions, or how the pause/resume affects time tracking.
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 a single, clear sentence that is front-loaded with the action and resource. Every word earns its place with no unnecessary filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is adequate for a simple toggle tool, and the schema provides usable parameter details. However, with no output schema or annotations, it omits return values, error behavior, and when to use this over stop_activity, leaving some gaps.
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 67%, with type_name and activity_id already described. The main description adds minimal meaning by mapping 'pause' and 'resume' to activity states, but does not explain selection behavior or the internal id warning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verbs 'Pause' and 'resume' with the resource 'activity', and further clarifies state constraints (running vs paused). This clearly distinguishes it from sibling tools like start_activity and stop_activity.
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 guidance is provided on when to use pause vs stop, when to resume, or any prerequisites. The description states what the tool does but not when to prefer it over alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Start tracking an activity by type name (fuzzy matched, see list_activity_types) or type_id. Optionally backdate the start with at (wall-clock) or started_minutes_ago.
| Name | Required | Description | Default |
|---|---|---|---|
| at | No | Backdate: start time as "HH:mm" (today) or "yyyy-MM-dd HH:mm" in the user's timezone | |
| type_id | No | Exact activity type id from list_activity_types (internal — never show ids to the user) | |
| timezone | No | IANA timezone `at` is given in (default: user's timezone) | |
| type_name | No | Activity type name, e.g. "Work" or "Reading" | |
| started_minutes_ago | No | Backdate the start by N minutes (alternative to `at`) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It does reveal fuzzy matching and backdate semantics, but omits critical side effects for a state-changing tool: what happens if an activity is already being tracked, whether starting overwrites the current status, permissions needed, or any return/error behavior. This is a meaningful transparency gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the primary purpose, and each clause adds necessary information (type identification, backdating options). No wasted words or repetition of schema details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has five parameters, no required parameters, no annotations, and no output schema. The description does not clarify whether at least one of type_id/type_name is required, nor does it explain typical success/failure responses or conflicts with an in-progress activity. This level of ambiguity makes the description incomplete for a state-changing tool, despite good parameter-level coverage.
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 schema already fully documents all five parameters, so the baseline is 3. The description adds value beyond the schema by noting that type_name is fuzzy matched, pointing to list_activity_types for valid names, and clarifying that at and started_minutes_ago are alternative backdating mechanisms. This helps an agent choose between the two backdate options.
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 action ('Start tracking an activity'), the resource (activity), and the key input modes (type name or type_id). It distinguishes itself from sibling tools like stop_activity and pause_resume_activity by explicitly being about starting tracking.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: use this to start tracking an activity, with guidance to consult list_activity_types for fuzzy name matching. It does not explicitly mention exclusions (e.g., when not to use), but the context is unambiguous enough for an agent to select it appropriately over siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Stop a running or paused activity. type_name may be omitted when exactly one activity is active. Optionally backdate the stop with at (wall-clock) or stopped_minutes_ago.
| Name | Required | Description | Default |
|---|---|---|---|
| at | No | Backdate: stop time as "HH:mm" (today) or "yyyy-MM-dd HH:mm" in the user's timezone | |
| timezone | No | IANA timezone `at` is given in (default: user's timezone) | |
| type_name | No | Which activity to stop (needed only if several are active) | |
| activity_id | No | Exact activity id from get_current_status (internal — never show ids to the user) | |
| stopped_minutes_ago | No | Backdate the stop by N minutes (alternative to `at`) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must cover behavioral traits. It discloses the ability to backdate with at or stopped_minutes_ago and the condition for type_name, which is useful. However, it does not mention what happens if no activity is active, whether the interval is definitively closed, or any side effects, leaving the agent without full awareness of edge cases.
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 long, front-loaded with the core purpose, and every sentence adds important operational detail. There is no filler or repetition of schema content, making it appropriately concise and well-structured.
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?
With five parameters and no output schema, the description covers the main purpose and adds key usage semantics. It is fairly complete for a simple stop tool, though it could briefly note error conditions (e.g., no active activity) or what is returned. The schema handles parameter details, so this slight gap does not significantly impair context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds semantic value beyond the schema by explaining that type_name may be omitted when exactly one activity is active and by clarifying that at and stopped_minutes_ago are alternative backdating options. This helps the agent understand parameter relationships and selection.
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 stops a running or paused activity, using a specific verb and resource. It distinguishes from siblings like start_activity and pause_resume_activity by indicating it ends an activity. The nuance about omitting type_name when exactly one activity is active also reinforces the purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when to use the tool (to stop an activity) and includes a specific condition: type_name may be omitted when exactly one activity is active. However, it does not explicitly compare with alternatives like pause_resume_activity or update_activity, so it stops short of full when/when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Aggregated time statistics per activity type for a date range. Returns overall totals plus per-DAY/WEEK/MONTH buckets.
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | End date yyyy-MM-dd, inclusive | |
| from | No | Start date yyyy-MM-dd (use with `to`) | |
| tags | No | Filter to these tags | |
| period | No | Named period; alternative to explicit from/to | |
| group_by | No | Bucket size for the periods breakdown (default DAY) | |
| timezone | No | IANA timezone (default: user's timezone) | |
| type_ids | No | Filter to these exact activity type ids (internal — never show ids to the user) | |
| type_names | No | Filter to these activity type names (groups allowed) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the output format (totals and buckets) but does not explicitly state read-only behavior, data source, or edge cases. It adds some behavioral context but not comprehensive transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences totaling 19 words, front-loaded with the core purpose and output structure. No redundant information, every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 8 parameters and no output schema, the description is somewhat sparse. It does not explain how to use from/to vs period, filtering by tags/type_ids/type_names, or the exact structure of returned data, leaving gaps for a tool of this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description does not add extra meaning to parameters; it only hints at date range and bucket size, which are already documented in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool provides 'Aggregated time statistics per activity type for a date range' and 'Returns overall totals plus per-DAY/WEEK/MONTH buckets'. This specifies a concrete resource and action, distinguishing it from sibling tools like list_intervals which return raw intervals.
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 aggregated time statistics but does not explicitly state when to use this tool over siblings or mention exclusions/alternatives. There is no guidance on 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.
Update the comment and/or tags of an existing entry (running, paused, or stopped) without changing its tracked time. Use this instead of logging a new entry when the user wants to annotate, describe, or re-tag something already tracked. Get activity_id from get_current_status (active timers) or list_intervals (past entries).
| Name | Required | Description | Default |
|---|---|---|---|
| tags | No | Full new tag list — replaces existing tags (include current tags to keep them); [] clears them | |
| comment | No | New comment — replaces the existing one; "" clears it | |
| activity_id | Yes | Activity id from get_current_status or list_intervals (internal — never show ids to the user) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It discloses that the tool does not change tracked time and applies to entries in any state (running, paused, or stopped). However, it does not mention the potentially destructive nature of tag replacement (full list replace) or comment replacement, though that is covered in the schema. It adds valuable context beyond the schema's structured fields.
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 three sentences: the first states the core purpose, the second gives usage guidance, and the third provides a prerequisite. It is front-loaded, concise, and every sentence earns its place with no redundancy.
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 moderate complexity, no annotations, and no output schema, the description adequately covers purpose, when to use, what it changes, and where to get the ID. It does not discuss return values or error conditions, but with no output schema this is less critical. The description is reasonably complete for an update 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?
Schema description coverage is 100% and each parameter has a clear description (e.g., tags 'Full new tag list — replaces existing tags', comment 'New comment — replaces the existing one'). The description adds minor value by specifying where to get activity_id, but this is also in the schema. Baseline 3 is appropriate since the schema already does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Update the comment and/or tags of an existing entry (running, paused, or stopped) without changing its tracked time.' It distinguishes itself from logging a new entry and references sibling tools for obtaining the activity_id, making the 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?
Explicit guidance is provided: 'Use this instead of logging a new entry when the user wants to annotate, describe, or re-tag something already tracked.' It also tells the user where to get the activity_id (get_current_status or list_intervals), which serves as a clear usage prerequisite.
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 or query: listing types, controlling active timers, logging intervals, updating annotations, generating reports, listing raw intervals, and fetching help. There is no overlap or ambiguity between start, stop, pause/resume, and log_interval, as each has a clear, non-overlapping purpose.
Most tools follow a verb_noun pattern (list_activity_types, start_activity, stop_activity, update_activity, list_intervals). However, 'time_report' and 'app_help' break the pattern by not starting with a verb, and 'get_current_status' uses 'get' instead of 'list' or 'show', creating minor inconsistency.
The 10 tools are well-scoped for a time-tracking MCP server, covering the core lifecycle (start, stop, pause/resume, log), data retrieval (status, intervals, report), and configuration (activity types, help). No tool feels redundant or missing at this granularity.
The tool set covers the main workflows: managing active timers, logging entries, updating annotations, and retrieving both raw and aggregated data. Minor gaps exist, such as no direct edit of entry times or deletion of entries, but these are explicitly documented in app_help as intentionally not exposed, making them workarounds rather than dead ends.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Read time entries, projects, clients, tasks and invoices; log and update tracked time.
Track time on usetimebook.com - start/stop timers, log entries, list projects/clients.
Manage projects, tasks, time tracking, and team collaboration through natural language.
Manage Avaza projects, tasks, timesheets, expenses, invoices, and scheduling from AI assistants.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/zaplitny/atimelogger-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
