update_timesheet

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

No annotations are present, so the description must carry behavioral disclosure. It does so by stating that only passed fields are modified and that passing date/start/end/duration recomputes begin and end. It doesn't mention permission requirements or irreversibility, but the partial-update semantics and recomputation are the most salient behaviors.

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 brief sentences plus a tight args list; every sentence adds useful behavior or sourcing information, and the key partial-update rule is front-loaded.

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?

The tool has 10 parameters and no annotations, so the description must carry more weight. It covers the update semantics and timesheet ID sourcing, and an output schema exists for return values, but several optional fields are left semantically unresolved. Adequate but not complete.

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 schema has 0% description coverage, and the description only documents timesheet_id and date/start/end/duration, pointing to log_time for formats. Tags, project, activity, billable, and description receive no semantic guidance, so an agent won't know valid values or ID sources for those fields, particularly project/activity.

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 opening 'Change an existing time entry' clearly identifies the verb and resource, and 'existing' plus 'from list_timesheets' distinguishes updating from logging a new entry. It also immediately communicates the partial-update behavior with 'Only the fields you pass are touched.'

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?

It says to obtain timesheet_id from list_timesheets and implies updating is for entries that already exist, which separates it from log_time and delete_timesheet. It doesn't explicitly state when not to use the tool or name the alternative creation/deletion tools, but the context is clear enough.

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