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

Annotations already cover idempotency, but the description adds meaningful behavioral nuance: it books nothing and reports which link is untapped, and it returns the practice's booking page when patient identity is ambiguous rather than guessing. This goes beyond the structured hints and helps the agent anticipate failure modes.

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 compact and front-loaded with the step context. Each sentence adds operational value: the precondition, the partial-failure behavior, the ambiguity fallback, and the idempotent outcome. No filler or repetition beyond what is useful.

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 action with an output schema, the description covers the workflow, failure cases, and retry behavior. The main gap is parameter mapping, which affects the parameter_semantics dimension; otherwise the behavioral picture is sufficiently complete.

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% and the description never mentions action_id or consent_version. It loosely refers to 'details from step 1' and 'consent_text', but an agent cannot map these to the required parameters with any confidence. The description fails to compensate for the schema's lack of descriptive text.

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 states a specific verb and resource: 'Book the held time' and explicitly frames this as 'Step 2 of 2', distinguishing it from hold_xona_booking_slot and abandon_xona_booking. This makes the tool's role in the workflow immediately clear.

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?

It gives clear when-to-use context: only after the patient has tapped both links and agreed to consent_text. It also explains the no-op condition when links are untapped. It doesn't explicitly name alternative tools, but the 'Step 2 of 2' framing and sibling set make the intended sequencing clear.

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