Skip to main content
Glama
Sign In
timermcp

timermcp

by julan-gh
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

Start Timer

timer_start

Start millisecond-precision stopwatches or countdowns. Name timers after tasks, launch simultaneous races, and receive live announcements.

Instructions

Start a millisecond-precision stopwatch (or countdown) on the TimerMCP server.

The server stamps the start on a MONOTONIC nanosecond clock the instant this call arrives. Elapsed time is computed server-side as stop-stamp minus start-stamp, so the constant part of the pipeline delay (user → Claude → server) cancels out between start and stop — only the difference in latency between the two calls can leak in.

Args:

  • name (string, default "main"): Timer name. NAME IT AFTER THE TASK — when the user says what they are working on ("start a timer for the auth refactor"), use that as the name ("auth refactor") so their session log reads like a work journal. Pass a comma-separated list (e.g. "alice,bob") to start several timers on the SAME nanosecond — race mode.

  • target_ms (number, optional): Turns the run into a countdown (Pomodoro, rest interval, speedrun target). Stop reports over/under.

  • announcer ('hype'|'zen'|'sergeant'|'sports'|'minimal', optional): Voice for this run's announcements. Defaults to configured style.

  • start_offset_ms (number, optional): Milliseconds subtracted from the final elapsed to bias out start-side latency. Defaults to configured value (0).

Returns: { started: [{name, elapsed_ms, started_wall, target_ms?}], announcement, dashboard_url }

IMPORTANT: Relay the 'announcement' line to the user with matching energy — you are the track announcer. Mention the dashboard_url the first time so they can put the live wall display on a second screen.

Errors: fails if a timer with the same name is already running (stop or cancel it first, or pick another name).

Tool call template

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

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

Input Schema

NameRequiredDescriptionDefault
nameNoTimer name; comma-separate for a simultaneous race start, e.g. "me,rival"main
announcerNoAnnouncement personality for this run
target_msNoOptional countdown target in ms (e.g. 1500000 for a 25-min Pomodoro)
start_offset_msNoLatency handicap subtracted from the final time (start side)

Output Schema

NameRequiredDescriptionDefault
startedYes
announcementYes
dashboard_urlYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv1.2.0

TDQS

A4.7/5.0
Behavior5/5

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

Annotations leave room; description adds monotonic clock, latency cancellation, error handling, return format, and announcement instructions. No contradiction with annotations.

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

Conciseness4/5

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

Well-structured with paragraphs and bullet-like sections, front-loaded with purpose. Slightly long but every sentence adds value; no obvious redundancy.

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

Completeness5/5

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

Given 4 params, annotations, output schema, and sibling tools, description is highly complete: covers return, errors, naming, usage tips, and behavioral details.

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

Parameters5/5

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

Schema coverage is 100%, but description adds naming guidelines, race mode, countdown purpose, voice personality, and latency handicap meaning, far exceeding baseline.

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

Purpose5/5

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

The description clearly states it starts a millisecond-precision stopwatch or countdown on the TimerMCP server, distinguishing it from siblings like timer_cancel, timer_stop, etc. The verb 'start' is specific to the resource 'timer'.

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

Usage Guidelines4/5

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

Provides explicit context on when to use (start a timer) and includes an error condition about duplicate names. No direct when-not or alternatives, but sibling names imply usage boundaries.

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

Deploy Server

Other Tools