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

The description adds significant behavioral context beyond the annotations. It discloses that this is a partial-update operation, that absent fields are treated as omitted per batch, that optional/conditionally required omissions don't block progress, and that the latest expected_state_version must always be passed (implying optimistic concurrency control). Annotations already indicate idempotency and non-destructiveness, and the description complements these without contradiction. It provides actionable behavior that isn't evident from schema or annotations alone.

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 three concise sentences with no fluff. The purpose is front-loaded, followed by essential usage constraints (what to pass, how omissions are handled, and the version requirement). Every sentence adds value, and the structure is clean and easily digestible for an agent scanning tool descriptions.

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 description covers the core behavioral nuances: partial response handling, omission semantics, and version requirement. It also implicitly guides which fields to populate. Since an output schema exists, return values don't need explanation. The only minor gap is not explicitly stating when to use this vs. sibling tools, but that's addressed in usage guidelines. Overall, the description is complete for the complexity of the tool, which involves a nested answers object and concurrency controls.

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 itself provides per-property descriptions (e.g., 'Brand. Use the exact key brand.'), but the tool description adds critical parameter semantics: instructing to pass only user-supplied fields plus selected_time_key, and emphasizing the need for the latest expected_state_version. This compensates for the 0% schema description coverage by guiding how to construct the answers object and which required parameters are mandatory. It doesn't explain idempotency_key or request_id, but those are already required in 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?

The description clearly states the tool's purpose: updating a service request with a user's partial response to the current intake or matching batch. It names the resource (service request) and the action (update via partial response). While it doesn't explicitly differentiate from siblings like reschedule_service_booking or prepare_service_booking_change, the 'current intake or matching batch' context implies it's for in-progress requests, which distinguishes it from booking lifecycle tools. The description is not a tautology and adds specific context about partial responses.

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 opens with 'Use this for the user's partial response to the current intake or matching batch,' which is an explicit when-to-use instruction. It clarifies that only user-supplied values plus selected_time_key should be passed, and explains how omitted fields are treated (they don't block progress). However, it doesn't explicitly mention when NOT to use this tool or name alternatives, such as using create_service_booking for new bookings or reschedule_service_booking for changes. The guidance is clear but lacks explicit exclusions.

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