reschedule_plan

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

Annotations already indicate readOnlyHint=false and destructiveHint=true, so the mutating nature is known. The description adds meaningful behavioral context beyond this: the operation is fail-closed, and changes require re-validation and re-approval before admission. This helps an agent understand that the tool may not immediately commit the change and that additional workflow steps are required.

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 short and front-loaded, with the core purpose in the first sentence and an important behavioral caveat in the second. It is not overly verbose, though terms like 'legacy generic mutation,' 'fail-closed,' and 'admission' are somewhat jargon-heavy and could be clearer.

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 four parameters, zero schema description coverage, and a destructiveHint annotation, the description is not complete enough for reliable invocation. It explains the purpose and approval workflow but leaves optional parameters such as schedule_revision and validation_digest undocumented, which may be required in certain approval contexts. The presence of an output schema helps, but the input-side gap remains material.

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 0%, so the description must compensate for the four parameters. The only hint is 'changed time,' which loosely maps to execute_at, but plan_id, schedule_revision, and validation_digest are left completely unexplained. This is a significant gap for an agent trying to construct a valid call.

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 clearly states the tool's core action: 'Request a temporal revision for a pending plan.' It identifies a specific resource ('pending plan') and a distinct operation ('temporal revision'), which helps separate it from scheduling, cancellation, and execution siblings. However, it does not explicitly name a sibling alternative, so it falls just short of the strongest differentiation.

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 implies when to use this tool: when a pending plan needs a time change. It also provides important workflow context by noting the legacy generic mutation is fail-closed and that a changed time must be validated and approved again, guiding the agent toward validation/approval follow-up steps. Explicit 'do not use when...' exclusions are absent, but the context is reasonably clear.

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