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

Annotations only supply destructiveHint=true, so the description carries most of the burden and it delivers: it discloses that the timer mode only works on a timestamp-tracking account, that ended_time is optional alongside started_time, and that the call is a write ('WRITE — creates data'), consistent with the write hint. It does not state what the response contains or whether the action is reversible, which is the remaining gap.

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?

Front-loaded with the action and the three modes before the routing hint and REST metadata. Dense but every sentence adds usable information; the trailing 'Harvest REST: POST /time_entries. WRITE — creates data.' is mildly redundant with the tool name, keeping it out of 5 territory.

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 an 8-parameter create tool with full schema coverage and no output schema, the description covers the required IDs, the three invocation patterns, the account-type caveat, and a helper sibling. The one thing an agent must infer is what the created entry returns (e.g., the new entry id needed to later stop or update it), which is not stated.

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 100%, so baseline is 3, but the description adds semantics the schema cannot express: the mutual exclusivity of hours / started_time / (neither) and the account-type precondition on the timer mode. This is real meaning beyond the field-level descriptions.

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?

States a specific verb+resource ('Create a time entry') and then enumerates the three distinct operating modes, which lets an agent immediately distinguish this from harvest_update_time_entry, harvest_stop_time_entry and harvest_restart_time_entry. No sibling does what this does, and the description makes that unambiguous.

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?

Gives explicit mode-selection guidance (hours vs. started_time vs. neither for a running timer) and routes the agent to harvest_list_project_assignments to resolve valid project_id/task_id, which is genuinely actionable. It stops short of naming when NOT to use it (e.g., 'use harvest_update_time_entry to modify an existing entry'), so it is clear context without full exclusions.

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