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

Annotations supply destructiveHint=true and idempotentHint=true, but the description adds real behavioral context: partial-update merge semantics, merchant customer policy enforcement, and the 422-no-retry rule. It does not say what is lost when a time is moved (notifications, existing resource assignment) despite destructiveHint being set, and the no-retry rule sits slightly awkwardly against idempotentHint=true.

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?

A single front-loaded paragraph; every clause earns its place (scope, partial-merge rule, policy refusal, retry prohibition, endpoint). No filler or restatement of the title.

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?

With 11 parameters, no output schema, and annotations that already declare the safety profile, the description covers the operation's semantics and failure mode well. The gaps are the two unmentioned scalar ids (client_id, time_resource_id) and any hint about what the response returns after the PATCH.

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 55%, and the description compensates for the unlabeled fields by grouping them semantically ('move it, switch service/provider/location, change status, price or notes'). However, client_id and time_resource_id get no mention in the description, and no format or constraint detail is added beyond the 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?

Opens with an explicit operation class ('WRITE') and a specific verb+resource ('change an existing booking'), then enumerates the dimensions of change (time, service/provider/location, status, price, notes). This is clearly distinguishable from siblings like agendapro_create_booking and agendapro_cancel_booking.

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?

States the key usage rule explicitly — partial update, only passed fields change — and gives a hard operational directive for the policy refusal (HTTP 422, do not retry). It stops short of naming alternatives for overlapping cases, e.g., that status changes cancelling a booking might belong to agendapro_cancel_booking.

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