start_timer

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 doesn't state whether starting a timer affects an existing running timer (does it stop/overwrite?), whether it requires active workspace context, or what happens on success. The term 'running timer' suggests there may be an existing timer involved, but the exact behavior (start one vs. resume one) is ambiguous.

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 brief at a single clause, which is concise in length, but it's under-specification rather than efficient communication. The phrase 'a running timer' is awkward and could have been used better to convey behavior. There is no room for waste, but also no content that adds depth.

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 5 parameters, no output schema, no annotations, and a low schema description coverage (20%), the description should provide substantive context. It provides almost none - no mention of return values (none specified), no parameter semantics, no behavior details. For a state-changing timer tool among many related time tools (create_time_entry, update_time_entry, stop_timer, get_running_timer), this is under-specified.

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 only 20% (only team_id is described as 'The workspace/team ID'). The description adds nothing about the four undocumented parameters: task_id, description, billable, and tags. Given the low coverage, the description should compensate by explaining key parameter relationships (e.g., how task_id ties to the target task, or what billable affects), but it remains silent.

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 'Start a running timer on a task' uses a clear verb+resource structure and identifies the target (a task). However, the phrasing is odd ('Start a running timer' is slightly tautological/confusing - a timer that is already running?). It distinguishes the core action from sibling get_running_timer and stop_timer, but doesn't specify what 'running' means in the context.

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 usage guidance is provided. The description doesn't say when to use this tool versus create_time_entry, update_time_entry, or stop_timer - sibling tools that could be confused for timer management. There's no mention of prerequisites (e.g., whether a timer must already exist or the task must be valid) or whether this starts a new timer when none exists.

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