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 cover read-only, idempotent and non-destructive, so the bar is lower. The description still adds a genuinely useful epistemic contract – unknown is returned explicitly and missing data is never treated as 'no' – which materially changes how an agent should interpret a negative answer.

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 core action and immediately followed by the most decision-relevant caveat. Nothing is padded or repeated from the name/title.

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 formatting need not be described, and the negative-answer semantics are covered. The gap is the total absence of topic/enum semantics and slug-scope explanation for a tool with 0% schema description coverage.

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 0%, so the description must carry parameter meaning, and it largely does not. 'Selected practices' hints at practice_slugs and 'bounded' gestures at the topic enum, but neither parameter, its cardinality (max 10 slugs), nor the meaning of the eleven topic values is explained.

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 gives a specific verb (answer) and a specific resource (bounded factual questions over selected practices' evidence), which an agent can distinguish from the booking/list siblings. It does not, however, name or differentiate itself against the nearest read sibling get_canadian_dental_practice.

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?

There is no when-to-use guidance and no mention of alternatives, even though get_canadian_dental_practice and search_canadian_dentists are plausible competitors for entity lookups. The agent must infer the boundary between 'ask a question' and 'fetch a practice record'.

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 declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds real behavioral value beyond that: it never sends anything, it enumerates the possible statuses, and it clarifies that 'sent' does not mean booked. It omits any note on authorization or error behavior.

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?

It is a single dense sentence that front-loads the purpose before the status enumeration. The colon-plus-quote construction ('It never sends: waiting_for_patient until the patient presses...') is slightly awkward to parse but every clause carries information.

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 no explanation, yet the description usefully explains the status semantics that an agent must interpret. With annotations covering the safety profile, the remaining gap is only the lack of routing versus get_dental_action_status.

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% for the single action_id parameter, so the schema contributes nothing. The description partially compensates by tying the parameter to a 'started request' (i.e., an id from start_dental_request), but it gives no format, length, or source detail.

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: 'Report a started request's status.' The closing caveat 'A sent request is never a confirmed booking' distinguishes it from confirm_xona_booking, so an agent can tell it apart from the confirmation sibling. It stops short of differentiating from get_dental_action_status, which appears to overlap.

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 ('a started request's status') and effectively rules out using it to confirm a booking, but it never states when to call this versus get_dental_action_status or confirm_xona_booking. No explicit when/when-not routing is provided.

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?

With readOnly/idempotent annotations already covering the safety profile, the description still adds substantial behavioral context: answers may be up to 5 minutes stale, read_at/age_seconds expose freshness, fresh triggers a re-read with an explicit rate limit (twice per minute per clinic) and a backoff message when exceeded, and unreadable schedulers return readable=false with a booking_url fallback. The closing line about 'server-owned' provider locators is opaque but harmless.

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, front-loaded with the core purpose before the qualifying conditions and freshness behavior; almost no filler. It is somewhat jargon-heavy ('live_schedule', 'reads_times', 'server-owned'), which slows parsing, but every sentence carries information.

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 present, the description covers the important operational facts: eligibility, caching staleness, rate limits, and the failure path. The remaining gap is how to obtain practice_slug and how this differs from list_xona_booking_services, 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 coverage is 50%: only 'fresh' is documented in the schema, and the description usefully restates its semantics (read now vs. from a read up to 5 minutes old). practice_slug is explained only as the lookup key, with no format, source, or example, so the description only partly compensates for the schema 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 ('read the services a clinic's own online scheduler offers') and scopes it by practice_slug, which is clear. It does not explicitly distinguish itself from the sibling list_xona_booking_services, so the agent must infer the difference between a clinic's 'own' scheduler and the Xona-branded one.

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 an eligibility condition ('a clinic whose search row is live_schedule, or whose action option has reads_times'), which is real when-to-use guidance but is phrased in terms of other tools' output fields rather than plain language. It never names an alternative tool or states when not to use this one, so the routing guidance is implied rather than 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 readOnly/idempotent/non-destructive, but the description adds substantial behavior the agent could not otherwise know: answers may be up to 5 minutes stale, read_at/age_seconds expose staleness, fresh forces a re-read, and there is a rate limit of twice a minute per clinic with a next-allowed hint. That is exactly the kind of operational context 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-loaded with the verb and the three key filters, then structured to explain returned fields and the freshness/rate-limit model. It is dense and semicolon-heavy, but each clause carries distinct information with little redundancy against the 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?

An output schema exists, so return values need not be explained, yet the description still maps the important ones (starts_at, start_local, time_zone, booking_url including which page is used, earliest). Combined with the staleness and rate-limit disclosure, an agent has everything needed to call it and interpret the result 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 already 83%, so baseline is 3, and the description genuinely adds meaning: preferred_time 'puts the closest times first', fresh re-reads rather than using a stale answer, and the date window bounds (both inclusive, at most 14 days) are restated with intent. It does not add syntax detail for practice_slug, which the schema also leaves undocumented.

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 — reading open times from a clinic's own online scheduler — and scopes it by practice_slug, service_id and date range. The phrase 'a clinic's own online scheduler' implicitly separates it from the sibling list_xona_booking_slots (Xona's scheduler) and from list_public_booking_services.

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 context is implied: you need a service_id 'from list_public_booking_services, or from a soonest search row's services', which routes the agent to a predecessor tool. However, it never states when to prefer this over list_xona_booking_slots or when to follow up with choose_public_booking_time, so no explicit when-not 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, 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 non-readonly, non-destructive, non-idempotent behavior. The description adds the meaningful traits: the action is short-lived, unlisted capabilities are refused, and this tool does not hold Xona time. It does not say what 'short-lived' means or whether repeated calls create duplicate actions, which matters given idempotentHint=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?

Two sentences: the first states the action and return value, the second the refusal rule and the sibling exclusion. No filler, and the primary behavior is front-loaded.

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, the description needn't explain the returned URL. It covers refusal and sibling routing, but omits that capabilities should be read from list_dental_practice_actions and what the action's lifetime or status entails (get_dental_action_status exists).

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 enum is self-explanatory. The description supplies the semantic frame: capability must come from the clinic's action options list, and one of the six values ('xona_email_appointment_request') is explained as a Xona request rather than a booking. practice_slug remains unexplained beyond its 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?

States a specific verb and resource: creates a short-lived action for one capability from the clinic's action options and returns its URL. Distinguishes itself from hold_xona_booking_slot by name, though the title says 'Open one of a clinic's booking routes' and the description uses 'capability', which requires the agent to map terms.

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 says a capability the clinic does not list is refused, and directs connected-practice time holding to hold_xona_booking_slot instead. It does not mention list_dental_practice_actions as the prerequisite source of valid capabilities, leaving that 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?

Annotations already declare readOnly/idempotent/non-destructive/closed-world, and the description adds real context beyond them: freshness of live reads ('read_at says when its times were read, at most 5 minutes before'), that opening booking_url starts a booking with no call, that opening hours are not appointment times, and that no auth is needed. Some of this (live rows, earliest, next_step, booking_url) duplicates the huge schema description of the order parameter, which lowers the added value somewhat.

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 body is a dense ~330-word wall mixing search semantics, ordering internals, service-matching heuristics and edge cases, with cryptic sentences such as 'Each earliest is only a first pick' and 'The tool a row's next_step names reads more times.' Several sentences repeat content already carried by the order parameter's schema description rather than earning their 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 needn't be explained (the description explains them anyway). Given 12 optional parameters and complex ordering, the description covers the hard parts but leaves query, paging, and the locality/province/postal_code relationships largely unexplained outside the order context. Adequate but with visible gaps.

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 58% with 12 parameters, so the description must compensate. It does explain the semantics of order, open, booking, coverage and service matching (e.g. matching service_name against the patient's need), but much of that restates the already-verbose order field description in the schema, and query, page, limit, locality, province and postal_code get no additional meaning in the 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 opening sentence gives a specific verb and resource ('Search evidence-backed public profiles in the Canadian dental directory') plus the filterable axes, which lets an agent separate it from retrieval tools like get_canadian_dental_practice. It also names a sibling (list_public_booking_slots) when the matched service doesn't fit. However, the purpose is buried under a large amount of order=soonest mechanics rather than stated crisply.

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 concrete usage conditions ('A search with order=soonest, the patient's postal code or city and the service returns live rows...') and routes the agent to an alternative when a service_name doesn't match the need. It also states 'no login or clinic membership is required'. It never states when NOT to use this tool (e.g. when the clinic is already known), so it stops short of full when/when-not 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?

Goes well beyond the annotations (readOnlyHint=false, idempotentHint=false): it discloses that nothing reaches the clinic until the patient presses "Send this request" or enters the email code on continue_url, that the response carries consent_text and continue_url, and that confirmation happens later. That two-phase consent flow is exactly the behavioral context an agent needs to avoid telling the patient the request was sent.

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 purpose, then mechanism, then result/routing in four tight sentences. The consent_text/continue_url sentence is partly redundant with the output schema, but it anchors the flow explanation so it still 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?

With an output schema present, return values needn't be detailed, and annotations cover the mutation/safety profile. The description supplies the two-step consent model and the upstream condition, leaving only minor gaps such as what happens on failure or whether repeated calls create duplicate requests (idempotentHint=false).

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 57%; the description only summarises "the patient's details and preferred times", while practice_slug, service_category, and note carry no extra meaning. Schema descriptions already explain patient_name, patient_email, patient_phone, and preferred_window, so the description adds little beyond the schema 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 — starting a dental appointment request that Xona forwards to a chosen clinic by email or web form — which is unambiguous against siblings like confirm_dental_request or start_xona_appointment_access. The channel detail further pins down what the tool actually produces.

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. It also routes status-checking to confirm_dental_request. What's missing is a when-not clause (e.g. what to do when the action is not marked completes_in_conversation).

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.