Update a time entry

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

Annotations already indicate a non-read-only, non-destructive operation. The description adds valuable context by stating partial-update behavior and the intentional absence of a delete tool, which informs the agent of workarounds. It does not contradict annotations, and the added context goes beyond the structured safety hints.

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: purpose, behavior, and contextual note. Every sentence earns its place, with no fluff. The key information is front-loaded, and the structure is tight and clear.

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, the presence of annotations, and absence of an output schema, the description covers the essential usage: what is edited, partial update semantics, and the no-delete policy. It does not mention return values or error handling, but for a straightforward update tool this is acceptable. The description is sufficiently complete for an agent to select and invoke the 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 coverage is only 17% (only spent_date has a description). While the description lists editable fields and explains partial updates, it does not explicitly map 'date' to spent_date, nor does it mention the required time_entry_id or constraints like hours > 0. It partially compensates for low coverage but leaves gaps that the schema alone does not fill.

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 starts with a specific verb and resource: "Edit an existing time entry's hours, notes, date, project, or task." This clearly identifies what the tool does and lists the editable fields. It also distinguishes itself from siblings by noting the absence of a delete tool, reinforcing that this is for editing not deleting.

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 partial-update guidance ("Only provided fields are changed") and explicit alternatives for deletion ("set hours or move entries instead, and delete in Harvest itself"). However, it does not explicitly contrast with log_time or start_timer for creating new entries, so it stops short of a full when/when-not differentiation.

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