Start a Clockify timer

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

The description discloses an important behavioral trait not visible in the annotations: starting a timer automatically stops any currently running timer. This is a meaningful side effect that could surprise an agent. The annotations already indicate a write operation (readOnlyHint=false), and the description adds context beyond that.

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 tight sentences with no filler. The main action is front-loaded, followed by a critical behavioral warning and a practical prerequisite. 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?

For a tool with a simple action, 6 parameters, and a high coverage schema, the description is complete enough. It captures the one non-obvious behavior (stopping an existing timer) and tells the agent where to source IDs. The lack of an output schema is acceptable because return values are not necessary to invoke the tool 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?

The input schema already provides 100% coverage, describing each parameter (including provenance like 'Project id from list_projects'). The description adds a general reminder to fetch IDs first, but this is redundant with the schema's own per-parameter notes. No meaningful new parameter semantics are introduced beyond what the schema already says.

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 names a specific verb and resource: 'Start a running Clockify timer.' It also clarifies the key side effect (stops any timer already running), which distinguishes this tool from siblings like stop_timer and current_timer. This is unambiguous and immediately scopes what the tool does.

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 for use: it starts a running timer and warns that only one timer can run at a time. It also gives a direct prerequisite instruction: use list_projects / list_tasks first if IDs are needed. It stops short of explicitly comparing against log_time or declaring when not to use it, but the context is clear enough for an agent to decide confidently.

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