Gaplessly Booking

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

Annotations declare readOnlyHint, idempotentHint, destructiveHint=false, but the description adds substantial behavioral context beyond them: the URL is short-lived, nothing is reserved, a popular slot can still be lost, and the page itself collects contact details. This is exactly the kind of non-inferable behavior an agent needs.

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?

Front-loaded with the core 'this does not book' clarification, then the mechanics and the guest-handling caveat. Every sentence earns its place, though it runs slightly long for a three-parameter tool.

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 no output schema, the description correctly explains the return value (the url) and the tool's non-mutating nature. Combined with annotations covering safety, an agent has everything needed to call it and instruct the guest correctly.

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 100%, so the baseline is 3. The description reinforces the slotToken's signed/expiring nature and the venue slug's origin, but these are already documented in the schema; it adds little parameter-specific meaning beyond what structured fields provide.

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?

States a specific verb and resource: it converts a time from find_appointment_times into a guest-tappable booking link. It explicitly negates the sibling action with 'This does NOT book anything', so an agent can distinguish it from book_table without opening either schema.

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?

Names the prerequisite tool (find_appointment_times) as the source of the time, states the negative case (it does not book), and gives operational guidance ('Give the guest the url', 'Never ask the guest for their contact details'). Clearly tells the agent when and how to use it.

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

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

Annotations declare readOnlyHint=true and destructiveHint=false, and the description reinforces this by stating it books nothing, then adds genuinely new behavioral context: a short-lived URL, a ~ten-minute hold that begins only when the guest opens the link, and nothing held beforehand. This is exactly the operational detail annotations cannot carry.

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?

Front-loads the most important clarification (this does not book) before detailing the URL mechanism and the hold. Two tight paragraphs, though the second paragraph's 'tenant' guidance repeats the do-not-hold point slightly.

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 no output schema, the description correctly explains the return value (a short-lived url) and the agent's obligation to hand it over promptly. For a three-required-param, non-destructive tool this is complete enough to invoke correctly.

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 100%, so venue, partySize, and slotToken are already fully documented including the signing/expiry semantics of slotToken. The description only loosely ties the URL to 'that party size and that exact sitting', adding no meaning beyond the schema, so baseline 3 applies.

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?

States a specific verb+resource outcome (turn a find_table_times slot into a tappable booking link) and immediately distinguishes it from what an agent might assume by clarifying it does NOT book anything. This makes it easily separable from its sibling book_appointment.

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?

Explicitly names the upstream source (a time from find_table_times) and the downstream consumer (the guest, who completes booking themselves), giving clear context for when to call it. It does not explicitly contrast with the sibling book_appointment, which would be the natural alternative an agent might consider.

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

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

Annotations already establish readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description then adds real context beyond that: slotToken is signed, expires in ~30 minutes, must be passed back verbatim, must not be reused across venues, and an empty times array means genuine unavailability rather than failure. However, it doesn't cover return ordering, pagination, or rate limits. With annotations carrying the safety profile, a 3 is fair – meaningful additions, but the token lifecycle is the only substantial behavioral disclosure.

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?

Three tight paragraphs, front-loaded with scope, then routing, then the token contract. Every sentence carries information; there is no filler or repetition of the tool name.

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 no output schema, the description compensates by describing the returned payload (`at` label and `slotToken`) and the empty-array edge case. Combined with full schema coverage and annotations, an agent has everything needed to call this correctly.

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 100%, so the baseline is 3 and the schema already documents all four parameters with constraints (days 1-14, the rejected 'next Tuesday' phrasing, the slug format). The description adds some framing (serviceId comes from get_venue, tokens are per-venue), but not enough beyond the schema to lift this above the baseline.

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?

States a specific verb and resource (free appointment times), pins the scope to one venue, one service, up to two weeks, and names the audience (salons, clinics, studios). It explicitly distinguishes itself from the sibling find_table_times, so an agent can route without opening a schema.

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?

Gives the alternative by name and the condition that selects it ("Use find_table_times for a restaurant instead") and states the prerequisite ("Needs a service id from get_venue"). Both the when and the when-not are explicit.

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

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

Annotations only cover the read-only safety profile, but the description adds substantial non-annotated behavior: the slotToken is signed, expires in ~30 minutes, is the sole booking handle, must be passed unedited, and must not be reused across venues. It also interprets the empty-`times` case and notes the phone-booking fallback for large parties.

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?

Front-loaded purpose in sentence one, sibling routing in sentence two, then the token lifecycle and empty-result meaning. Every sentence carries information an agent needs; nothing is repeated from the schema or annotations.

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?

There is no output schema, so the description correctly compensates by explaining the returned `at` label, the `slotToken`, and the empty-array case. Combined with the 100%-covered input schema and read-only annotations, an agent has everything needed to call and consume this tool.

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 100%, so days/from/venue/partySize are already fully documented with formats and constraints. The description reinforces the venue-identity constraint ('never reuse one from a different venue') but adds no syntax or semantics beyond the schema, so the baseline 3 applies.

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?

States a specific verb and resource ('Free table times'), plus the scoping units (one venue, one party size, up to two weeks) that distinguish it from find_appointment_times. An agent can route between the two booking-search siblings purely from this sentence.

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?

Explicitly names the alternative for the wrong vertical ('Use find_appointment_times for a salon or clinic instead') and clarifies that an empty result means closed/fully booked. It stops short of stating prerequisites (e.g. that a venue slug must come from get_venue's ecosystem) and when to prefer book_table over searching.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description goes further by disclosing the `venueClock` return semantics and the non-obvious rule that all later dates resolve against `venueClock.today` rather than the caller's today, plus the deliberate absence of a timezone identifier. It stops short of describing the full shape of the profile payload, but the critical misuse hazard (date/time interpretation) is well covered.

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?

Front-loaded with purpose and the call-ordering rule in the first sentence, then the time-semantics caveat. Slightly longer than strictly necessary, but the second paragraph is not padding: it preempts a real failure mode (off-by-hours bookings) that no structured field communicates.

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?

There is no output schema, so the description carries the burden of explaining returns, and it does: it names `venueClock`, states the result is venue-local time as text with no timezone identifier, and explains how downstream calls should interpret dates. With one fully documented required parameter and clean annotations, nothing an agent needs to call this correctly is missing.

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 100% and the property description already explains the slug format exhaustively, including the 'not the business name' warning and the booking-link derivation. The description reinforces this by tying the slug back to get_venue's own output, which helps close the loop across calls, but it adds no new format detail 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 a concrete verb and resource: reading a venue's public booking profile, and enumerates what that profile contains (identity, location, bookable services, current local time). It also positions itself against siblings by declaring it must be called first, so an agent can place it in the workflow without opening any schema.

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?

Explicitly states 'Call this first' and gives the reason: other tools need the venue slug, and appointment searches need a service id from here. That is a when-to-use rule plus the dependency ordering, with no inference required.

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