Xona Dental Gateway

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

The description adds behavioral detail beyond the annotations: it reveals that the tool releases a hold and drops patient details, and that it is safe to call repeatedly ('Calling again returns the same result'), which enriches the idempotentHint annotation. It also clarifies scope with 'never cancels a booked appointment', aligning with destructiveHint false.

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 short sentences with no filler. The primary action and scope are front-loaded, the exclusion is stated clearly, and the idempotency note is concise. Every sentence earns its place.

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 single-parameter tool with an output schema and idempotency annotation, the description covers the main behavior, scope, and repeated-call behavior. However, it leaves out the crucial meaning of action_id and does not say it should be the identifier returned by a prior hold action, which an agent needs to invoke the tool 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?

The schema has a single required parameter, action_id, with 0% schema description coverage. The description never explains what action_id refers to, how to obtain it, or what format is expected beyond the schema constraints. Since the schema coverage is low, the description was responsible for compensating and it does not.

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 uses specific verbs ('Release', 'drop') tied to a clear resource ('the held time', 'the patient's details') and states exactly when it applies ('at any step before it is booked'). It also distinguishes itself from cancellation by explicitly saying 'It never cancels a booked appointment', separating it from any cancellation sibling.

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 clearly states when to use the tool: when the patient no longer wants the held time before it is booked. It also provides a strong exclusion: it is not for booked appointments. It does not name an explicit alternative tool, but the context and exclusion are enough for an agent to select it appropriately.

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 provide readOnlyHint and idempotentHint, covering safety. The description adds valuable behavioral context: 'Unknown is returned explicitly; missing data is never inferred as no.' This clarifies handling of missing data, which is not in annotations, so it adds real value.

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?

Two sentences with zero waste. The main purpose is front-loaded, and the behavioral caveat follows. No redundancy or 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?

Given the output schema exists and the input schema defines the topic enum, the description is fairly complete. It explains the unknown-handling behavior but does not elaborate on practice_slugs or topic categories, though those are largely covered by the schema. Minor gap on usage guidance, but not critical for a read-only QA 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 0% – the description does not mention the two parameters at all. The topic parameter has an enum but no descriptions, and practice_slugs is self-explanatory, yet the description provides no guidance on how to populate them. Since coverage is low, the description should compensate but only weakly implies a bounded question set.

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 clear verb+resource: 'Answer a bounded factual question from the selected practices' evidence.' It differentiates from siblings like search_canadian_dentists and get_canadian_dental_practice by focusing on evidence-based QA. Not a tautology and not vague.

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 implies when to use it (answering factual questions about selected practices) but gives no explicit alternatives or exclusions. Among many booking/action siblings, this tool is clearly distinct, but the description does not name them or state when not 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 state the safety profile (readOnly=false, destructive=false, idempotent=false, openWorld=false), and the description adds real context beyond them: the change is asynchronous and patient-mediated (a texted link/button or code), the practice either updates automatically or receives a request, and re-calling returns a live result. That retry/status behavior also explains the non-idempotent annotation. Only auth/permission and failure behavior are left unstated.

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?

Four sentences, front-loaded with the purpose and then the behavioral details, with essentially no filler. It is slightly dense but every sentence carries information an agent needs about how the change actually happens.

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?

An output schema exists, so return values need not be described, and the description covers the async, patient-driven workflow well for a genuinely complex tool. The gaps are the missing origin/prerequisites for action_id and any failure handling, which keep it from being fully 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 only 40% (date and slot_fingerprint are documented, with helpful cross-references to list_xona_reschedule_times), yet the description itself says nothing about any parameter. With three parameters (kind, action_id, appointment_ref) undocumented in both places, the description fails to compensate for the coverage gap.

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 gives a specific verb pair and resource: 'Move or cancel one of the patient's appointments,' which maps cleanly to the cancel/reschedule enum. It is clear enough to act on, but it does not explicitly distinguish itself from adjacent siblings such as list_xona_reschedule_times or the booking-confirmation tools, so it stops short of a 5.

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?

Usage is implied by the purpose (use it when a patient wants an appointment moved or cancelled) and the description sketches the downstream flow, but it never states prerequisites (e.g., where action_id/appointment_ref come from) or when to prefer a sibling tool. There is no explicit when/when-not guidance, so this is minimum-viable rather than strong.

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 cover the safety profile (readOnlyHint=false, idempotentHint=false), and the description adds genuinely useful behavior beyond that: it re-reads the slot and keeps it only if still open, and it discloses that Xona performs the actual booking while the patient enters details on the returned page. This is the kind of state/flow detail annotations cannot convey.

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?

Two long, clause-heavy sentences that are front-loaded with the flow but include redundancy ('the page collects the patient's details' is stated twice in substance) and a run-on structure that slows parsing.

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 step in a multi-tool booking workflow with an output schema present, the description covers the key context: input source, re-validation behavior, and what continue_url is for. Return-value details are correctly left to the output schema.

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 75%, so most parameters are already documented, but the description adds meaning by grouping service_id/slot_id/starts_at as 'the time' and including action_id in the call shape, plus stressing starts_at must match the returned value exactly. It adds value over the schema without fully substituting for the undocumented action_id semantics.

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 (keeps a chosen time) and resource (a public booking slot), and explicitly frames it as the step following list_public_booking_slots. It distinguishes itself from that sibling by noting it selects rather than lists, though the phrasing is dense enough that the core action takes a second read.

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 clearly scopes usage to a 'public_provider_booking action' and names the upstream source of the time (list_public_booking_slots or a soonest search row's earliest). No explicit when-not or exclusions are given, but the sequencing context is clear.

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 cover safety and idempotency, but the description adds substantive context beyond them: the outcome is delivered/held/failed rather than a confirmed booking, and the consent_version/verification_code inputs encode an authorization step. The idempotency sentence largely restates 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?

Three tight sentences, front-loaded with the core action and the outcome disclaimer before the retry rule. Only the final idempotency sentence is arguably redundant with the annotation.

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 an output schema present, return values need minimal explanation, yet the description still summarizes the possible outcomes usefully. The main gap is not stating where action_id comes from (presumably start_dental_request), which an agent must infer.

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 only 17%, so the description must carry the load. It explains verification_code ('the 6-digit code Xona emailed the patient') and consent_version ('the consent_text the patient agreed to'), but action_id, service_category, and note are left undocumented in both schema and description.

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 (send) and resource (the started dental request to the clinic), and the phrase 'the started request' implies it operates on something created by start_dental_request, distinguishing it from that sibling. It is clear, though it does not name the sibling explicitly.

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?

Usage is implied by 'the started request' (i.e., call this after start_dental_request has produced an action_id), and the retry rule is stated. However, no alternative tool is named and there is no explicit when-not guidance versus confirm_xona_booking or hold_xona_booking_slot.

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?

The description adds substantial behavioral context beyond the annotations: it explains the waiting_for_patient interim state, the fallback to the practice booking page when Xona cannot identify the patient, a one-time retry if the booking stopped before it was written, and idempotent repeated calls. These details are directly relevant to safely interpreting and retrying the tool.

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 four focused sentences, front-loaded with the core action and followed by relevant edge-case behavior. It is informative without padding, though slightly long for a one-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?

An output schema exists, so return values need not be detailed, and the description covers important behavioral edge cases well. However, for a required action_id with no schema description and no mention in the description, the definition is incomplete on how to supply or obtain that parameter.

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?

There is one required action_id parameter with 0% schema description coverage, and the description never mentions it or explains its origin, format, or relationship to the booking. The parameter semantics are left entirely to the caller's inference from the parameter name.

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 gets the booking result and gives the triggering condition: the patient has tapped the text link and pressed Book this appointment. It distinguishes itself from generic status tools by focusing on the final booking outcome, but it does not explicitly name or rule out siblings like get_dental_action_status.

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 a clear condition for calling: after the patient acts, and notes that until then it returns waiting_for_patient. It does not state when not to use it or name alternatives such as get_dental_action_status, so it falls just short of full alternative guidance.

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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds that it returns fact evidence, citations, and current public actions, which is useful behavioral context beyond the annotations. No contradiction found.

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?

One concise sentence that front-loads the core action ('Get one public dental practice profile') and then lists the included components. No unnecessary words; structure is optimal.

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?

Given the single parameter, the presence of an output schema, and annotations that cover safety, the description provides adequate context. It enumerates the return content (profile, evidence, citations, actions) and implies the identifier. It does not explain error handling, but for a simple get operation with schema available, this is sufficient.

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 does not explicitly mention practice_slug. However, the single parameter is clearly the identifier implied by 'Get one public dental practice profile.' The description adds no explicit parameter guidance, but the parameter's purpose is self-evident from its name and the tool's purpose, so it is marginally sufficient.

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 'Get' with a resource 'public dental practice profile' and enumerates the content (fact evidence, citations, current public actions). This clearly distinguishes from sibling tools like search_canadian_dentists (search) and list_dental_practice_actions (list actions), so an agent knows exactly what this tool returns.

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 implies usage for retrieving a single practice by slug, but does not explicitly state when to use it versus alternatives like search or list tools. It lacks exclusions or conditions, so an agent must infer from context. This is adequate but not 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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds useful behavioral nuance ('exact outcome', distinct outcome categories), but does not elaborate on lifecycle behavior or failure cases. It does not contradict 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?

Two short sentences, front-loaded with the primary verb and resource. Every phrase adds value, especially the second sentence clarifying that outcome types remain distinct.

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 simple one-parameter, read-only, idempotent tool with an output schema and strong annotations, the description is mostly complete. It could better define 'expiring dental action' or explicitly state that it applies only to such actions, but an agent can likely proceed with minimal ambiguity.

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%, so the description needed to compensate by explaining action_id and how it relates to the outcome. It does not mention the parameter at all; only the schema's name and length constraints provide any meaning, leaving the parameter semantics mostly implicit.

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 identifies a specific verb ('Read') and resource ('outcome of an expiring dental action'), and adds useful scope by saying handoff, request, and confirmed booking outcomes remain distinct. It does not explicitly name a sibling alternative, but the purpose is unambiguous among the listed 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?

The description implies when to use the tool: when the exact outcome of an expiring dental action is needed. However, it gives no explicit when-not-to-use guidance or alternatives, leaving some inference to the agent.

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?

The description adds substantial behavioral context beyond the annotations: it texts the patient, opens a page with a Book this appointment button, and either books directly or sends a request depending on the practice. It does not mention hold expiry, idempotency, or auth requirements, but the annotations already cover basic read/write and destructive hints.

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 front-loaded with the core action and uses three sentences without obvious repetition. The middle sentence about the link page is somewhat detailed but useful for understanding the downstream flow.

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 10-parameter mutation tool with an output schema and 60% schema coverage, the description covers the patient-facing flow well but omits prerequisites, parameter sourcing, and operational constraints like hold expiry or idempotency. It is minimally adequate rather than 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 60%, with several important parameters such as service_id, practice_slug, slot_fingerprint, and note lacking schema descriptions. The tool description adds no parameter-level meaning at all, so it fails to compensate for the coverage gap.

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: hold one open time and text the patient a link. It clearly implies a pre-booking hold step, but it does not explicitly distinguish itself from siblings such as confirm_xona_booking or abandon_xona_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?

The description explains what happens after the patient receives the link, but gives no explicit guidance on when to call this tool versus list_xona_booking_slots, confirm_xona_booking, or abandon_xona_booking. It also does not state prerequisites such as needing a slot_fingerprint from a prior list operation.

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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds no extra behavioral context such as authentication needs, rate limits, or data freshness guarantees beyond the word 'current'. It does not contradict annotations, but it adds minimal value over the structured hints.

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 a single, efficient sentence that front-loads the action ('List') and then specifies the resource and ordering. Every word contributes to understanding the tool's purpose. No fluff or redundancy.

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?

Given there is an output schema, return values are covered. The description states what is listed and the ordering, which is useful. However, it lacks any usage context, prerequisites (e.g., a valid practice_slug), or alternative guidance. For a simple list operation, the absence of these details is acceptable, but the parameter explanation gap makes it incomplete.

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%, so the description must compensate for the sole parameter, practice_slug. However, the description does not mention or explain this parameter at all. While the parameter name is self-explanatory, there is no guidance on how to obtain or format the slug, nor any indication of required format beyond the schema constraints. The description fails to compensate for the low schema coverage.

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 a specific verb ('List') and resource ('current public booking, request, form, call, and website actions for a dental practice'). It enumerates the action types and specifies the ordering ('preference order'), making it distinct from siblings that focus on services or slots. An agent can easily tell this from list_public_booking_services or list_xona_booking_slots.

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 does not explicitly mention when to use this tool versus alternatives or provide exclusions. The purpose itself implies usage for listing actions, but no alternatives are named or conditions given. An agent must infer from the resource type, which is adequate but not 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 readOnlyHint=true, destructiveHint=false, and idempotentHint=true, covering safety. The description adds valuable behavioral context beyond that: it is live from the schedule, has temporal validity (30 minutes after tap, and for the appointment until its day), and returns a waiting state if called before the tap. These details are not derivable from annotations or schema.

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 sentences with no fluff. It front-loads the core purpose ('Read the named patient's upcoming appointments...') followed by necessary context about the action_id and the waiting behavior. Every sentence earns its place, and the structure is logical.

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 an output schema present, return values are covered externally. The description covers the tool's purpose, input semantics, temporal constraints, and the waiting state, making it complete for an agent to decide when and how to call it. No critical information appears 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 0%, but the description explains that action_id must come from a booking made in this conversation or from start_xona_appointment_access. It also clarifies the context of the patient tapping the text link. This adds meaning beyond the schema's minimal type/length constraints, although it does not describe the exact format or value pattern beyond its origin.

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 action: 'Read the named patient's upcoming appointments at the practice, live from its schedule.' It specifies the resource (appointments), the scope (named patient), and the source (live schedule). It also differentiates from siblings by mentioning the specific trigger condition ('after the patient tapped the text link') and the required action_id types, which are unique to this tool.

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 provides explicit context for when to use the tool: it works with the action_id of a booking made in this conversation (with time constraints) or of start_xona_appointment_access. It also warns that before the tap, the tool reports a waiting state, implying it should not be called prematurely. However, it does not explicitly mention alternative tools or state when not to use this tool, leaving some inference to the agent.

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 readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is established. The description adds useful behavioral context by defining a precondition: the practice must have connected its schedule to Xona, and the tool is tied to a specific route state from list_dental_practice_actions. No contradiction with annotations exists.

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 two sentences with no filler. It fronts the core action and resource, then adds the precise triggering condition, making it immediately scannable.

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 single-parameter, read-only list tool with an output schema and strong annotations, the description provides the essential trigger context and scope. Nothing critical is missing for an agent to invoke it 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 0%, but there is only one parameter, practice_slug, whose meaning is implied by the title and description referencing 'a practice'. The description does not explicitly document the slug format or that it identifies the connected practice, so it provides only minimal compensation for the missing schema description.

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 uses a specific verb ('List') and a specific resource ('the services a practice that connected its schedule to Xona books online'), and it distinguishes this tool from the sibling list_public_booking_services by scoping to connected practices. The title reinforces the same distinction.

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 gives an explicit trigger: use this tool where list_dental_practice_actions marks the Xona booking route as completes_in_conversation. It does not explicitly name alternatives or exclusions, so it stops just short of a full 5.

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 read-only, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds real behavioral detail beyond that: how results are ranked (closest ten to preferred_time, else balanced spread, plus earliest open time) and that an empty result carries a reason.

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?

Two sentences, front-loaded with what the tool returns and immediately followed by the range constraint and the handoff token (slot_fingerprint). Dense but every clause carries information; no 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?

An output schema exists, so return values need not be explained, yet the description usefully signals ranking behavior and the empty-case reason. Combined with annotation coverage of the safety profile, an agent has enough to call this correctly; the only gap is guidance on choosing it over the public slot listing.

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 67%, so the schema already documents date_to, date_from, doctor_id and preferred_time in detail. The description reinforces the date semantics ('inclusive, at most 8 weeks out') but says nothing about practice_slug, service_id or doctor_id, so it only partially compensates for the coverage gap.

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 ('List open times at a connected practice for one service') with an explicit date-range scope, which separates it from the service-listing and public-slot siblings. It stops short of naming an alternative tool the way a 5 would.

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 boundary conditions (inclusive range, at most 8 weeks out, at most 56 days) and forward-routes to hold_xona_booking_slot, so usage is implied and partially guided. There is no explicit 'use this instead of list_public_booking_slots when...' statement, leaving the connected-vs-public choice to inference.

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?

With readOnlyHint/idempotentHint already declaring the safe-read profile, the description adds real behavioral context: results are restricted to the appointment's own service and provider, and the range is bounded by date_from/date_to. It omits pagination/result-size behavior, but the output schema covers return shape.

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?

Two tight sentences, front-loaded with the action and scope, followed by the one piece of provenance an agent needs. No filler or restated schema text.

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 read-only lookup with an output schema, the description supplies the essential scoping rule, the date-range bound, and the source of appointment_ref; return values need not be explained. Only action_id is left implicit, a minor omission.

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 50%: date_from/date_to are already documented in the schema, and the description only re-frames them as a range. It does add provenance for appointment_ref, but the required action_id parameter remains unexplained in both schema and description, which is a meaningful gap.

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 (List) plus precise resource (open times an appointment can move to), with the scoping rule 'for its own service and provider' that separates it from generic slot-listing siblings like list_xona_booking_slots. An agent can tell what it returns without opening the 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 clear context for use (finding reschedule options for an existing appointment) and even states where appointment_ref comes from (list_xona_appointments). It does not, however, name a contrasting sibling such as list_xona_booking_slots for brand-new bookings, nor state prerequisites about appointment status.

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 it is not read-only, not destructive, not idempotent and closed-world, so the safety profile is already covered. The description adds genuinely new behavior: a verification code is emailed to the patient first and the request is only sent after confirmation, and the request may go out by email or the clinic's web form. It stops short of stating failure modes (e.g., invalid code, repeat invocation).

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 with no filler, front-loading what the tool does before the two-step flow and the routing condition. The parenthetical delivery detail is somewhat heavy but earns its place.

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?

An output schema exists, so return values need not be explained. For a non-idempotent mutation that triggers email sends, the description covers the side-effect sequence and the routing rule well; only edge-case behavior and re-invocation semantics are unaddressed.

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 67%, so most parameters are already documented; the description reinforces that patient_email is where the code goes and implies practice_slug is 'the selected clinic'. It adds no format or constraint detail beyond the schema, so the 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?

States a specific verb and resource ('Start an appointment request') and clarifies the delivery mechanism (email or the clinic's own website form). It also distinguishes itself from the sibling confirm_dental_request by describing the two-step flow, so an agent can tell the two apart without opening schemas.

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 an explicit activation condition ('Use it where list_dental_practice_actions marks xona_email_appointment_request as completes_in_conversation') and names the follow-up tool confirm_dental_request. The when-to-use rule and the next step are both stated rather than inferred.

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 readOnlyHint=false, destructiveHint=false and idempotentHint=false, so the description earns credit by adding real behavior: the SMS delivery, the identity-match requirement, and the enumeration-safety disclosure that 'the answer is the same whether or not the details match.' It could go further on error/rate-limit behavior, but the match-invariance note is genuinely useful beyond 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?

The purpose is front-loaded, but the first sentence is tangled ('for a conversation with no booking action_id that still works') and the valuable enumeration-safety point is buried at the end. Roughly the right length, but not optimally structured.

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 an output schema present, return values need no explanation, and annotations cover the safety profile. The description supplies the matching logic, the SMS flow, and the match-invariance behavior, leaving only minor gaps like practice_slug meaning and failure modes.

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 only 20% (only patient_phone is documented), so the description carries more burden. It does map the matching inputs ('the mobile number, name and date of birth') to parameters and implies all must match, but practice_slug is never explained and format expectations aren't clarified. Partial compensation only.

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 uses a specific verb+resource ('Text a patient one link to see, move or cancel the appointments they already have') and names the sibling it hands off to (list_xona_appointments). An agent can identify this as the SMS-link entry point distinct from list/change tools. The phrase 'for a conversation with no booking action_id that still works' is murky, which keeps it short of a 5.

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 a clear triggering condition ('a conversation with no booking action_id') and describes the downstream sequence (patient taps link, presses Show my appointments, then list_xona_appointments reads). It does not state when NOT to use it versus siblings, so it stops short of a 5.

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