reschedule_appointment

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

With no annotations, the description fully discloses side effects: 'The old slot is released and the 24-hour reminder is re-queued for the new time.' It also states a behavioral rule: cancelled appointments cannot be rescheduled. This goes beyond basic functionality and helps the agent anticipate consequences.

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 tightly structured: a one-line purpose, then usage guidance, behavioral notes, parameter documentation, and an example. Every sentence earns its place with no redundancy. It is both concise and information-dense.

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 two-parameter tool with an output schema, the description covers all necessary context: preconditions (check availability), side effects, exclusions, and argument formats. It is sufficient for an agent to invoke the tool correctly without ambiguity.

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?

Despite 0% schema description coverage, the description fully explains both parameters: appointment_id is sourced from get_appointments, and new_starts_at requires clinic-local ISO 8601 with a concrete example. This adds meaning beyond the raw schema.

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 begins with 'Move an existing appointment to a new time and update its reminder,' which clearly identifies the action and resource. It distinguishes itself from sibling tools like cancel_appointment and book_appointment by focusing on rescheduling and reminder updates.

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?

Explicit guidance is given: 'Use check_availability first to confirm the new time is free' provides a direct prerequisite and references an alternative tool. 'Cancelled appointments cannot be rescheduled — book a new one instead' gives a clear when-not-to-use condition and suggests an alternative. This is exemplary.

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