Update schedule task

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

Annotations only mark it as a non-readonly, non-idempotent, non-destructive write; the description adds what actually happens: dependents are not shifted, the project start/end dates follow the schedule, and the call is easily undone with one more call. That is exactly the beyond-annotations context an agent needs before mutating a schedule.

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, then a tight sequence of behavioral facts, each sentence carrying distinct information with no filler. It runs to five sentences, and the dependency and no-confirmation points could be tightened, but nothing is wasted.

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 a 7-parameter mutation with no output schema, it covers the outcome ('returns it as the schedule shows it afterwards'), the side effects on dependents and project dates, and the safety/undo story. Nothing an agent needs in order to invoke it correctly is missing.

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 71%, so the schema documents most fields, but the description adds cross-parameter semantics the schema cannot express: start_date alone moves the task while preserving length, whereas end_date or duration_days redefine the length. name and percent_complete get no extra semantics, which keeps it from a 5.

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?

A concrete verb plus resource ('Change the name, dates, length or percent complete of a task on the project schedule') and it immediately pins the object as a single schedule task, which separates it from the many update_* siblings. The second sentence reinforces that exactly one task is modified and returned.

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 real usage guidance: it points to list_schedule_tasks for checking depends_on and tells the agent to move dependents too, and it clarifies that no confirmation prompt is needed because the edit is internal and reversible. It stops short of naming an alternative tool or stating when not to use it, so it is clear context without explicit exclusions.

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