Log a time entry

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

Annotations already indicate readOnlyHint=false and destructiveHint=false, but the description goes further, disclosing side effects: 'When goalId is set this ALSO increases that goal's logged hours... wrong goalId quietly corrupts goal progress.' It also reveals free-plan per-day limits and the dryRun validation behavior. No contradiction with annotations; the description adds substantial behavioral context beyond the structured data.

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 dense but well-structured, front-loading the purpose and then layering warnings and usage notes. It is perhaps longer than strictly necessary but every sentence adds critical operational detail (units, date sourcing, goal confirmation, dryRun). No filler; efficient for the complexity involved.

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 9 parameters and no output schema, the description covers all critical aspects: unit correctness, date handling, side effects, error prevention, and free-plan limits. It explains the dryRun mechanism for previewing batches. For a write tool, it anticipates the likely failure modes and equips the agent to handle them, making it complete for safe 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 coverage is 100%, so the baseline is 3. The description adds value by giving concrete examples ('an hour and a half is 90') and explicit prohibitions ('Never send hours here and never send a decimal'). It also reinforces date sourcing from get_context.today and the goal side-effect warning. These enrich parameter understanding beyond the schema 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 opens with 'WRITES.' and states 'Records time the user already spent,' specifying the exact verb and resource. It positions itself as 'the workhorse tool for catching up on untracked work,' clearly distinguishing it from sibling tools like start_timer or list_time_entries. The purpose is unmistakable and specific.

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 usage guidance: it is for recording already-spent time, warns 'Never invent a duration' and to ask if the user didn't specify length, and instructs to use 'dryRun true to show a batch to the user before committing it.' It also advises confirming goalId before logging to avoid corrupting progress. This goes beyond implied context to actionable do/don't guidance.

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