Gaplessly Booking

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

Annotations already establish read-only/idempotent safety, and the description adds substantial context beyond them: the `slotToken` is signed, expires in ~30 minutes, is the only way to book later, must not be edited or reused across venues, and an empty `times` array means genuinely unavailable rather than failed. This is exactly the non-obvious 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?

Three tight paragraphs, front-loaded with what the tool does and the sibling exclusion, then prerequisites, then the critical token contract. No sentence is filler.

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 explaining the returned time shape (`at` label, `slotToken`), the token's lifecycle, and the meaning of an empty result. Nothing needed to call or interpret this tool 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%, so the schema already documents every parameter in detail (including the venue slug formats and the accepted `from` values). The description only reinforces that serviceId must come from get_venue, adding little beyond the schema. Baseline 3 is appropriate.

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 opening sentence states a specific verb and resource with scope ('Free appointment times at one venue for one service, over up to two weeks'), and it explicitly names the sibling it is not (find_table_times) plus the verticals it serves. An agent can distinguish it from find_table_times 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?

It names the alternative 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 when-to-use and what's-needed-before 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 already declare the safe-read profile (readOnlyHint, idempotentHint, non-destructive), and the description goes well beyond them: the slotToken is signed, expires in about 30 minutes, must be passed back unedited, must not be reused across venues. That is exactly the operational behavior an agent needs and cannot get from structured fields.

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 scope, then token semantics, then the empty-result edge case — a logical ordering with no filler. Slightly long and a couple of clauses ('never edited, and never reuse one from a different venue') repeat the same constraint, costing a point.

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 still explains the return shape (an `at` label and a `slotToken`), the meaning of an empty `times` array, and the token's lifetime — enough for an agent to call the tool and correctly hand off to a booking tool. Nothing material 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%, so the schema already documents venue, partySize, days, and from in detail (including rejected formats). The description reinforces 'one party size' and 'up to two weeks' but adds no syntax or format detail 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 at one restaurant or venue'), plus the scope constraints of one party size and up to two weeks. It explicitly names the sibling it is not (find_appointment_times for salons/clinics), so an agent can route correctly 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?

Explicitly gives the alternative tool and the condition that selects it ('Use find_appointment_times for a salon or clinic instead'), and bounds the search domain to one venue, one party size, and up to two weeks. The empty-result guidance ('usually means closed or fully booked', large parties may be taken by phone) tells the agent how to interpret and act on outcomes.

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 read-only, idempotent, non-destructive, non-open-world, so the safety bar is met. The description goes further with genuinely non-obvious behavior: venueClock is returned, later dates resolve against venueClock.today rather than the caller's today, and times are deliberately text with no timezone identifier to prevent hour-offset bookings. It stops short of describing result shape or error cases, but the time-resolution warning is high-value context.

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 dense sentences, correctly ordered: what it returns, why to call it first, then the timezone trap that would otherwise cause real booking errors. No filler and the most consequential warning is kept adjacent to the return-value discussion.

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 must carry the return contract, and it does: venueClock is named and its resolution semantics are explained. Combined with 100% parameter coverage in the schema, an agent has everything needed to call and interpret 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% and the schema already explains the slug format, the /book/<slug> and <slug>.gaplessly.com derivations, and the 'not the business name' warning. The description adds only a light cross-reference (the slug comes from get_venue, a service id feeds appointment searches), so baseline 3 is appropriate.

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?

Specific verb+resource with scope spelled out: reads a venue's public booking profile and enumerates what that contains (identity, location, bookable services, local clock). It also positions itself relative to siblings by declaring itself the entry point that supplies the slug the others need.

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 ordering guidance: 'Call this first: the other tools need this venue's slug, and appointment searches need a service id from here.' It states when to use it and why, tying it directly to find_appointment_times / start_appointment_booking rather than leaving the agent to infer a sequence.

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/idempotentHint and non-destructive, but the description goes well beyond them: the return is a short-lived URL on the venue's own page, nothing is reserved, contact details are collected by the page rather than the tool, and the slot can still be lost. These are exactly the operational facts an agent cannot get from the annotations.

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 short paragraphs, front-loaded with the capability and its negation, then the guest-facing instruction, then the caveat. Every sentence carries a distinct operational fact with no restatement of the title or schema.

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 still tells the agent the shape and lifetime of the return value (a short-lived url) and how to hand it off. Combined with a fully described 3-param schema, nothing needed to invoke and relay the result 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 coverage is 100%, so the schema already documents all three parameters in detail, which sets the baseline at 3. The description adds genuine meaning on top: it explains what the produced link encodes (venue's page pre-opened at that service, that staff member and that exact time) and clarifies that slotToken originates from find_appointment_times or find_table_times.

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 opens with a specific verb and resource (turning a time into a booking link) and immediately negates the likely misread: 'This does NOT book anything.' It explicitly ties itself to the sibling find_appointment_times as its input source, and the schema references find_table_times as well, so an agent can place it precisely among the five siblings.

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 states when to use it (after find_appointment_times), what to do with the result (give the guest the url), a hard constraint ('Never ask the guest for their contact details to pass here'), and a caveat to relay ('a popular time can still go before they tap'). The when/when-not boundary is fully spelled out rather than implied.

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?

Goes well beyond the annotations (readOnly/idempotent/non-destructive) by disclosing the real hold semantics: nothing is reserved until the guest opens the link, the venue holds the table for roughly ten minutes after opening, and the URL is short-lived. That is exactly the operational context an agent needs to sequence the conversation correctly.

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?

Purpose is front-loaded in the first sentence, and the second paragraph is dense with non-redundant hold/expiry detail. It runs slightly long, but no sentence is filler.

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, yet the description covers the return value (a short-lived URL on the venue's booking page), its pre-filled state, and its timing constraints. An agent can call this and hand the result off without further inference.

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%, with venue, partySize and slotToken all documented in detail, so the schema carries the burden. The description only adds the workflow framing that the link opens pre-set to 'that party size and that exact sitting', which is marginal beyond the schema 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?

States a specific verb and resource ('Turn a time from find_table_times into a link') and immediately bounds it with a negation ('This does NOT book anything'). It is trivially distinguishable from find_table_times and start_appointment_booking 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?

Explicitly ties usage to a prior find_table_times result and tells the agent what to do with the output ('give them the url promptly'). It does not name start_appointment_booking as the appointment-side alternative, so the routing across the two booking siblings is left implicit.

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