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

Goes well beyond the annotations by disclosing side-effect scope (client is not invited, no message is sent, safe to run without confirmation) and a non-obvious state behavior: a previously deleted card matching the same email/phone is resurrected with its old visits, note and birthday unless new values are supplied. That resurrection/overwrite rule is exactly the kind of hidden behavior annotations cannot express.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose and the hard requirement (phone or email) are front-loaded, and the closure/confirmation facts come next. There is mild redundancy between 'Add a client card to your client list' and 'Adds one client card with a name', and the final sentence packs two distinct ideas (undo path and resurrection) together.

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 5-param mutation with full schema documentation and no output schema, the description covers side effects, confirmation policy and the interesting resurrection rule. The remaining gap is what the call returns (e.g., a new client id), which matters for follow-up calls like add_client_note or get_client and is unstated.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds a real cross-field constraint absent from the schema: at least one of phone or email is required ('Booksy needs one of them') even though only name is marked required. It also flags that birthday and note are optional/private, reinforcing the schema rather than merely repeating it.

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 ('Add a client card to your client list') and immediately names the counterpart sibling ('delete_client removes the card again'). An agent can distinguish it from find_client/update_client/list_clients without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear usage context — no invite, no message, no confirmation prompt needed before calling — and names delete_client as the inverse operation. It stops short of explicitly contrasting add_client with update_client for an already-existing client, which is the one genuinely ambiguous routing decision among the siblings.

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 a non-destructive, non-idempotent write; the description adds real context beyond that: the write is append-only ('keeping what is there'), the text is auto-prefixed with today's date, the note is business-private, and the client receives no notification. The notification-free and append semantics are exactly the side effects an agent cannot infer from the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sentences, front-loaded with the action and its preservation guarantee, followed by model context and the non-notification fact. No filler or restatement of the tool name.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a two-parameter append mutation with annotations and no output schema, the description covers the essentials: what is added, what is kept, who can see it, and that the client isn't notified. It doesn't say what the call returns or what happens at the 1000-character limit, but neither is critical to correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so both parameters are already documented in the schema, establishing the baseline of 3. The description adds only the implication that the caller supplies the line text while the date prefix is generated, which is marginal beyond what the schema states.

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 ('Add a dated line to a client's private note') plus the key invariant that existing text is preserved. The second sentence explains the underlying model (one private note per client card), which separates it from update_client and other client mutators.

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 when this tool applies: you want to append a timestamped observation to the single private note rather than overwrite client fields. It doesn't explicitly name an alternative (e.g. update_client) or state exclusions, so it stops short of full routing 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?

Beyond annotations, the description discloses that the operation reaches no client, that Booksy rejects blocks over existing appointments, and that remove_time_off reverses it. It does not describe permission requirements or the response shape, but it adds meaningful behavioral context consistent with non-read-only, non-idempotent 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?

The description is four tight sentences, front-loads the core action, and each sentence contributes distinct information about modes, errors, and reversal.

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?

It covers the mutation's purpose, dual modes, error condition, and inverse operation, which is sufficient for correct invocation. With no output schema, it could say more about the return value, but the essential behavioral context is present.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds interpretive value by mapping the start/end formats to whole-day versus partial-hour blocking semantics. That clarification complements rather than repeats the schema's per-field descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: blocking a staff member's calendar for whole days or hours. It distinguishes the two operating modes and names the inverse sibling, remove_time_off, so the agent can tell it apart from appointment creation and time-off listing.

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 explains the two usage modes based on parameter formatting (two dates vs. two date-times on the same day) and notes that Booksy refuses blocks over existing appointments. It also points to remove_time_off for reversal, but does not explicitly exclude using create_appointment for bookable slots.

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: client notification depends solely on notify_client, deposit handling follows business settings, non-cancellable appointments are refused, and there is no undo. These details are exactly what an agent needs for a destructive, non-idempotent mutation.

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, then efficiently covers side effects, failure conditions, irreversibility, and the rebooking alternative. Every sentence carries operational value with no wasted phrasing.

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 destructive cancellation tool with no output schema, the description covers the critical gaps: side effects, deposit implications, refusal conditions, irreversibility, and the follow-up path. An agent has enough context to invoke it correctly and understand the consequences.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so all three parameters are already documented in the input schema. The description adds useful context for notify_client and appointment_id behavior, but it does not add meaning for reason beyond what the schema already states.

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 and resource: 'Cancel an appointment and free its time in the calendar.' It also distinguishes the operation from rebooking by naming create_appointment and from cancellability checks by naming get_appointment.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly states when to use this tool and what alternatives exist, including checking get_appointment for cancellability and using create_appointment to book again after cancellation. It also clarifies that the client is notified only when notify_client is used.

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?

Substantially beyond the annotations: it discloses that the end time is derived from the service duration, that Booksy pre-checks staff availability, and that a busy slot is refused rather than double-booked. It also confirms dry_run saves nothing and returns saved=false. It omits any undo path, though a created appointment is reversible via cancel_appointment, and the destructiveHint=true annotation is not directly explained.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action, then behaviour, then the dry-run caveat — good ordering with no filler. The opening two sentences overlap ('Book a client for one service at a start time' / 'Books one client card for one service'), which costs a little.

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 seven-parameter mutation with no output schema, the description covers what gets created, how availability is enforced, notification behaviour, and the dry-run contract. What is missing is failure/edge handling (invalid client or service, permission requirements) and what the saved result looks like.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so all seven parameters are already documented. The description adds only marginal semantic value, mainly the coupling between start and service duration and the cardinality of one client/one service. Baseline 3 is appropriate when the schema carries the parameter burden.

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 names a specific verb and resource with tight scope: book one client, for one service, at one start time. An agent can distinguish it from cancel_appointment or reschedule_appointment by name, but the description never explicitly routes against those siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives real conditional guidance: use dry_run to check slot and price without saving, and add notify_client only when the client should get a confirmation. It never states exclusions (e.g. that existing bookings should go through reschedule_appointment instead) or prerequisites beyond pointing at list_staff/list_clients via the schema.

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 destructiveHint=true and readOnlyHint=false, so the safety profile is covered; the description goes further by disclosing blast radius (past appointments preserved) and a real side effect (the client is not notified). It stops short of stating reversibility or what happens on a repeat delete, despite 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?

Three short sentences, each earning its place: action, fidelity to the UI behavior, and consequence. The core action is front-loaded and nothing is padded.

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 destructive tool with rich annotations and no output schema, the description covers consequences and non-effects well. A minor gap remains around what happens when the card is already gone (annotations say non-idempotent) and whether the removal is recoverable.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the sole parameter client_id already documents its source (list_clients or find_client). The description adds no further meaning about the identifier, so 3 is the correct 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 (remove) and resource (client card from client list) plus an explicit scope boundary: past appointments stay in the calendar. This separates it from related siblings like cancel_appointment or update_client without requiring the schema to be opened.

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 clear 'remove a client card' framing, and the note that appointments are untouched implicitly rules out using this to cancel bookings. However, it never states when to prefer this over update_client or what prerequisites (e.g., existing client, permissions) apply.

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 and destructiveHint=false, so the safety profile is covered. The description adds genuine context beyond them: consent semantics in EU jurisdictions ('consented counts only the clients who agreed'), SMS cost beyond the plan's free allowance, and the guarantee that nothing is sent. It could go further on return shape or error behavior, but it meaningfully supplements 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?

The purpose is front-loaded in the first sentence, followed by a focused second paragraph on consent and cost. Slight redundancy between 'without sending it' and the closing 'Nothing is sent' keeps it from a 5, but every sentence largely 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 read-only estimate tool with no output schema, the description explains what the caller receives (reach counts, per-channel send counts, SMS cost) and the consent nuance that changes the count. Minor gaps remain around invalid client IDs or partial failures, but the core call context is 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 coverage is 100%, so all three parameters are already documented, including that message length sets SMS parts and client_ids come from list_clients. The description echoes the same facts ('same clients, channel and text') but adds little new parameter-level meaning. Baseline 3 is appropriate when the schema does the heavy lifting.

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 (count/estimate) and resource (who a Message Blast reaches and its SMS cost), and immediately distinguishes itself from send_message_blast ('without sending it'). An agent can tell exactly what this tool produces versus its sibling without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly frames itself as the dry-run counterpart to send_message_blast: 'Asks Booksy what send_message_blast would do with the same clients, channel and text.' The alternative is named and the condition that selects it (wanting to preview rather than send) is clear, reinforced by 'Nothing is sent.'

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 and non-destructive, so safety is covered. The description adds behavior beyond them: the result set includes contact details plus note and visit counts, and the search index is eventually consistent ("a few seconds" lag), which is exactly the kind of trait an agent needs to avoid wrong conclusions from an empty result.

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 what it matches and what it returns. The match fields are repeated from the schema's query description, a minor redundancy, but nothing is padding.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a two-parameter read tool with full schema coverage and no output schema, it covers matching semantics, returned fields, and the indexing-lag caveat with a fallback tool. Only result ordering is unaddressed, which is a small gap for a search 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 coverage is 100%, so both parameters are already documented, including that query takes a partial name/email/phone and that limit defaults to 10 with a max of 50. The description adds little parameter-level detail beyond restating the match fields, so baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The definition states the resource (client cards), the match fields (name, email, phone) and the returned payload (contact details, note and visit counts). The second sentence explicitly separates it from get_client, which reads a single card by ID, so an agent can pick between them without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It names the alternative (get_client) and the condition that selects it: a just-created card may not be indexed yet, so fetch by ID instead. It does not say when to prefer list_clients over this search, which leaves one sibling relationship implicit.

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 readOnly/idempotent/non-destructive, yet the description adds real behavioral detail: results are earliest-first, respect the service's slot interval and duration, and exclude past times. 'Booksy's own booking check confirms every slot returned' is a useful guarantee, though it is phrased vaguely enough that its exact meaning is unclear.

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 opening sentence and the first clause of the second ('Free start times for a service on one day' vs 'Returns free start times for one service on one day') are near-duplicates, wasting space. The content is front-loaded and the remainder earns its place, but the redundant lead-in costs it.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description carries the burden of describing returns and does so: free start times, earliest first, per staff member, capped by limit. It does not describe the concrete response shape (e.g. start timestamps with staff associations), leaving a minor gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so all four parameters are already documented in the schema, including the staff_id default and the limit range. The description's 'for each staff member who offers it (or only staff_id)' largely restates the schema's staff_id default rather than adding new semantics, 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 with scope: 'free start times for one service on one day', and enumerates the inputs it considers (working hours, bookings, blocks, time off). An agent can distinguish this from list_appointments or get_business_hours without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The closing line 'Pass start and staff_id to create_appointment' establishes the natural follow-on action, implying this is the availability check that precedes booking. However, it never states when this tool should be avoided or how it compares to alternatives such as list_appointments, so the guidance is contextual but not exhaustive.

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 (readOnly, idempotent, non-destructive), and the description goes well beyond them by defining the returned semantics: 'note' is staff-only while 'client_note' is client-visible, and 'can' enumerates the currently permitted actions (cancel, change, confirm, decline, no_show). Those are non-obvious behaviors an agent cannot get 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?

Field list is front-loaded and the second paragraph adds semantics rather than repeating verbatim, though it does re-list the same return fields (services, staff, times, price, client, notes) at some length. Minor redundancy, no wasted filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description has to describe returns, and it does so adequately for a single-record fetch, including the ambiguous note fields and the 'can' capability list. It stops short of stating failure behavior or whether the appointment must exist or be accessible to the caller.

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 parameter with 100% schema description coverage, and the schema already explains that the ID comes from list_appointments. The description adds no format, validation, or lookup guidance beyond that, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The opening line 'One appointment: services, staff, times, price, client and notes' names the resource and its scope (single record) with the fields returned, which implicitly separates it from the sibling list_appointments. It never names that sibling explicitly, so the differentiation is inferable rather than stated.

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 only implied: an agent must infer that this is the drill-down call for an appointment_id obtained elsewhere (the schema notes 'Appointment ID from list_appointments'). There is no explicit when-to-use versus list_appointments or when-not clause.

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 and non-destructive, so the description is free to add semantics: an empty list means closed, and the payload covers address, note, time zone and booking windows. The only omission is any hint of return shape or pagination, which matters little for a single-object read.

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 with the payload front-loaded in the first line and the data-source clarification second. Nothing is padded, though the second sentence runs a bit long by stacking note, time zone, address and booking windows.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, so the description has to carry the return values, and it does: hours per day, closed-day sentinel, note, time zone, address and booking lead times. A 4 rather than 5 because it does not say whether hours are staff-specific or business-wide only.

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 tool takes no parameters, so the baseline is 4. The description correctly explains that the result is implicitly scoped to the caller's business rather than requiring an id, which is the one parameter question an agent could have.

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 the resource and exactly what it returns: weekly opening hours, time zone, booking lead times, the note and address. This clearly separates it from get_business_profile and get_settings, which an agent might otherwise confuse with it.

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 framing 'Reads the opening hours set in Business details' implies this is the canonical source for operating hours, but it never says when to pick this over get_business_profile or get_settings, nor that it takes no arguments because it is tenant-scoped. Usage is inferable but not stated.

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, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds substantive context beyond that: it discloses the scope of data exposed (including visibility in the marketplace, booking lead time limits, and trial end date), which helps the agent understand what it will reveal.

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 summary sentence is front-loaded and the second paragraph enumerates the payload efficiently. There is mild redundancy — name, address and contact details appear in both sentences — but no filler or hedging.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema and no parameters, the description carries the burden of telling the agent what comes back, and it does so field-by-field. It stops short of formats (time zone representation, hours structure, date format for trial end) and of error/no-profile behavior, which would make it 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?

The tool takes zero parameters, so the baseline is 4. The description correctly makes no claims about inputs and instead spends its words on the return payload, which is the right allocation for a parameterless read.

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 ("Reads the business record") with a clearly bounded resource and enumerates the exact fields returned. It implicitly distinguishes itself from narrower siblings like get_business_hours and get_settings by stating the profile record is the superset being 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?

Usage is only implied by the phrase "the business record behind your Booksy profile" — an agent can infer this is the entry point for account-level info rather than hours or settings. There is no explicit when-to-use/when-not-to-use guidance nor any named alternative tool, which is a real gap given 28 siblings.

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/openWorld, so the safety profile is covered; the description adds real value by disclosing the specific data exposed, including a private note and blocked/Booksy-app status. It does not mention error behavior for an unknown ID or any rate/permission constraints, keeping it short of a 5.

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 first sentence is a front-loaded summary and the second supplies the field inventory, which is a sound structure. There is mild redundancy — 'contact details' in the lead is then re-expanded as name, email, phone, birthday — but the length is justified by having to describe return contents with no output schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description carries the burden of explaining returns and does so thoroughly, down to the cross-tool mapping that a visit's appointment_uid equals get_appointment's appointment_id. That mapping is exactly the non-obvious connective detail an agent needs to chain these calls.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and both parameters are already documented there, including the client_id source and the visits_limit default and 0-100 bounds. The description adds no parameter-level detail beyond the schema, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Reads one client card of the business by ID') and enumerates the returned fields, making it clear this is a single-record fetch rather than a list. The distinction from list_clients and find_client is implied by 'one client card ... by ID' rather than named 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 only implied: the reader infers this is the drill-down after list_clients or find_client (that hint lives in the schema's client_id description, not the tool description). There is no explicit when-to-use/when-not or named-alternative routing to find_client for lookup by name or phone.

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, and the description layers on real behavioral context: the period-alignment rule for from/to, currency-formatted amounts, and a plan-tier gate. It stops short of saying what happens when a Lite business requests a Pro-only category (error vs. empty), which is the one behavioral edge an agent could still hit.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core purpose and return shape, then progressively narrower rules (category selection, report key, period alignment, plan availability). Dense but every sentence carries a distinct constraint; the plan-availability clause could be tightened slightly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description carries the burden of describing returns and does so per category (dashboard totals plus delta vs. prior period; other categories expose highlight tables and a report list). Adequate for a 5-parameter read tool, with only the plan-restriction failure mode left 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 100%, so the baseline is 3, but the description adds meaning the schema does not: that `from`/`to` must land on a whole day/week/month/year boundary as Booksy counts it, and how `report` relates to the `reports` list returned by a category. `staff_id` scoping is left to the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Numbers from Stats & Reports ... as JSON') and immediately scopes it to a period and a single category. No sibling tool overlaps this territory, so an agent can route here without ambiguity.

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 explains when to use which category (dashboard for totals, other categories for highlight tables), when to add the `report` key (to get full tables), and when the tool is available at all (dashboard/revenue/appointments/clients on Lite; the rest need Pro). This is genuine routing guidance, not 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 cover readOnly/idempotent safety, and the description adds genuine value on top: the exact scope of what settings are returned (allowance, usage, price per text part, booking-event notification channels) and the fact that the data is read-only with edits made in the Booksy app. Return shape is described more richly than the annotations alone would 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 sentences, both front-loaded with the substantive scope; the first sentence is a compressed noun list that reads slightly like a fragment but still earns its place by enumerating the setting categories. 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?

With no output schema, the description carries the burden of explaining what comes back, and it does so by enumerating the returned settings categories. An agent knows what it will get and that the state is read-only; only the exact response shape (field names, units) is unspecified, which is acceptable for a settings read.

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 tool takes zero parameters, so the baseline is 4; there is nothing for the description to disambiguate and it correctly makes no parameter claims.

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 names the resource precisely: message allowance/usage, client messaging channels, and notification settings, with a clear read verb ("Reads the settings an agent needs before messaging clients"). It is specific and concrete, but it does not explicitly distinguish itself from the closest sibling, list_notifications, which covers the notification feed rather than the notification preferences.

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?

"Reads the settings an agent needs before messaging clients" gives a real usage condition, and "Changes stay in the Booksy app" tells the agent this is not the path for editing. It stops short of naming any alternative or prerequisite for other settings lookups, so it's strong but not exhaustive.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior, and the description adds substantial context: start order, maximum 31-day span, inclusion of unconfirmed requests, business time zone, empty client for walk-ins, and one row per multi-service appointment. These details help the agent interpret results correctly without contradicting 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?

The description is front-loaded with the tool's purpose and then adds only useful behavioral details in a compact sequence. Each sentence contributes either scope, ordering, time zone, edge-case handling, or a sibling-tool distinction.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description still explains the returned row shape, ordering, time zone behavior, walk-in edge case, and multi-service representation. Combined with fully documented parameters and safety annotations, it is complete enough for an agent to call 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?

Schema description coverage is 100%, so from, to, and staff_id are already documented in the schema. The description restates the 31-day range limit but does not add filtering semantics or usage details for staff_id beyond what the schema provides, making the baseline 3 appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific resource (appointments) and scope (date range with client, service, staff, time, and status). It clearly distinguishes itself from get_appointment by explaining that get_appointment returns prices and notes, which are not returned here.

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 context for use: listing the calendar between two days, including unconfirmed requests, and points to get_appointment when price and note details are needed. However, it does not explicitly say when not to use this tool or name alternatives such as find_open_slots for availability checks.

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 readOnly, idempotent, and non-destructive, so the description's job is to add context. It does add one important nuance ('filtered on each page'), which implies filters apply to page results rather than narrowing the client set globally. It says nothing about pagination termination or whether revenue and visit data can lag, so the added context is limited.

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 stays short: two sentences cover what the tool returns and how to filter, and the field list is front-loaded. The dense field enumeration reads as a list rather than prose, so it is a little harder to scan, but it wastes nothing.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, so the description should explain the return shape, and it does: fields, visit metrics, and the groups facet with counts. The gaps (how pagination ends, whether groups can be requested per call) are minor.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description goes beyond the schema by hinting how query and not_visited_days interact with pagination, and it names the groups facet, which no parameter or output schema documents.

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 and resource ('Reads the Clients list of the business, A to Z') and enumerates returned fields, so an agent knows exactly what it returns. It doesn't explicitly contrast with the sibling find_client or get_client, so the boundary between list/search/single-lookup is only implied.

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 real usage cues ('Search by name, email or phone, or keep only clients who have not visited...'), which implies when to use the filters. But it never says when to prefer get_client or find_client instead, even though sibling tools cover the same searchable fields.

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 openWorldHint, so safety is covered; the description adds real content-level context about what the read returns (automated vs one-time templates, trigger state, scheduled blasts) and the navigation path 'Promotion > Message Blasts'. It does not describe ordering, field shape, or whether disabled templates are included, so it stops short of full disclosure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short paragraphs, front-loaded with the resource definition and followed by scope and sibling routing. There is mild redundancy between 'Message Blast templates (automated and one-time)' and the later enumeration of the same two categories, but no filler sentences.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no input parameters and no output schema, the description must convey what comes back, and it does so at the category level. It is nearly complete for a simple list tool; only the returned field detail and pagination behavior are left unstated, which is a minor gap here.

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 tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a 0-param tool applies. The description correctly implies no filtering arguments are needed.

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 names a specific verb (list/read) and resource (Message Blast templates and scheduled blasts), then enumerates the three data classes covered: automated templates with trigger and on/off state, one-time templates, and scheduled blasts. It is clearly distinguishable from send_message_blast and estimate_message_blast, which are named as the write/count siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly routes the agent to the right alternatives: send_message_blast for sending a one-time message and estimate_message_blast for counting recipients and SMS cost first. That effectively implies this tool is the read/browse step before sending, though it never states an explicit 'do not use this to send' exclusion or any preconditions.

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, so the bar is lower. The description still adds genuinely useful non-obvious behavior: 'Reading does not mark them seen' and 'newest first' ordering. It says nothing about result limits beyond schema/defaults, but that is covered in the 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?

Two tight sentences: the source and content are front-loaded, then ordering and two constraints. No filler and nothing redundant with the 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?

For a no-required-param list tool with no output schema, the description covers source, content types, ordering, chat exclusion and unread side-effect. Only the shape of returned notification objects is unspecified, which is a minor gap given no output schema 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 100%, so page, per_page and unread_only are fully documented in the schema. The description adds no extra meaning about parameter interaction (e.g., how unread_only combines with paging), so baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Names a specific verb+resource ('Notifications from the panel's bell') and enumerates the content types (new bookings, changes, cancellations, reviews), plus ordering ('newest first'). This clearly separates it from siblings like list_reviews or list_appointments, which cover single sources.

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 explicit exclusion ('Client chat is not included') and a scoping condition for the source panel. However, it doesn't name an alternative tool for chat messages or reviews, so the agent must infer the routing rather than being told.

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 openWorldHint, so the description's added value is in what the read returns: newest-first default, the fields per review, and the per-star average and count. It doesn't mention pagination limits or that results are scoped to the caller's own Booksy profile, which an agent would benefit from knowing.

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 opening line front-loads the purpose and the routing hint closes the second paragraph, which is good structure. There is some redundancy between the opening summary ('rating, text, services, staff and your reply') and the second sentence's field list, which repeats the same content nearly verbatim.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, so the description correctly carries the return-shape burden by naming the per-review fields and the aggregate rating summary. Combined with annotations covering the safety profile, an agent has everything needed to call and interpret it.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% – page, sort and per_page all carry defaults and bounds in the schema. The description only restates the newest-first default, adding no paging or sort semantics beyond what the schema already provides, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The first line names the specific resource ('Client reviews of your business') and enumerates what each record contains (rating, text, services, staff, reply). This is clearly distinct from reply_to_review and from other list_* siblings, so an agent can pick it 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?

The description says to use reply_to_review for the write path and states the default ordering ('newest first by default'), which covers the main read-vs-write fork. It doesn't say when this is the wrong read (e.g. per-staff or single-review lookups), but the tool has one obvious job and the alternative is named.

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, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral detail beyond the annotations: it explains the return shape, including variants, duration, price representations, currency, price type, online booking status, and staff IDs.

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 service menu concept and then details the returned fields efficiently. There is minor repetition between 'Your service menu with category, variants...' and 'Reads the services...', but every sentence still contributes useful 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?

With no output schema, the description carries the full burden of explaining return values, and it does so thoroughly: name, category, description, online booking, variants, duration, price number/display/currency/type, and staff IDs. It also explains how service_id and variant_id relate to downstream tools, leaving no critical gap for correct invocation.

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 tool takes no parameters, so the baseline is 4. The description correctly does not invent parameter semantics and instead focuses on return data and downstream ID usage.

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 read operation ('Reads the services of the business') and enumerates the returned fields, making it clearly distinguishable from sibling list tools like list_staff or list_clients. It also links the output to create_appointment and find_open_slots via service_id and variant_id, clarifying its role in the workflow.

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 by explaining that create_appointment and find_open_slots require service_id or variant_id from this data. It does not explicitly state when not to use it or name alternative tools for services, but the usage 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 readOnly/idempotent/non-destructive, so the bar is lower, and the description still adds real value: hours are derived from Shifts with time off included, and the window is Monday–Sunday of a single week. It does not, however, say whether inactive/hidden staff are returned or how large the response can get.

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 key content is front-loaded in the first sentence and the field inventory follows efficiently in one sentence. There is mild redundancy between the opening noun-phrase fragment and the 'Reads the staff...' sentence, costing it a point but not readability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description properly carries the return-value burden by enumerating fields and the week shape, and it hints at the staff_id handoff. It stops short of stating filtering of inactive staff or response size, which for a list tool would be the last missing piece.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the single parameter is already well documented, so the baseline is 3. The description adds meaning beyond the schema by clarifying that the returned window is Monday-to-Sunday, complementing the schema's 'any day of the week' input 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?

States a specific verb (reads) and resource (staff of the business) and enumerates exactly what is returned: name, position, email, phone, access level, visibility, services performed, and per-day hours. The inclusion of services-per-staff and weekly shifts distinguishes it from siblings like list_services and list_clients without ambiguity.

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 only implied by 'Reads the staff of the business' — there is no explicit when-to-use or when-not-to-use guidance, and no named alternative. The closing note 'Use staff_id in other tools' is helpful downstream routing but is not selection guidance for this tool itself.

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 this as a safe, idempotent, read-only listing. The description adds meaningful data-shape context: time off carries dates and sometimes hours, blocked hours carry date-times, and the maximum range is 31 days. It stops short of describing pagination or the full 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?

The definition is two tight sentences with the resource and scope front-loaded. Every clause, including the remove_time_off routing hint, 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 read-only, fully described three-parameter listing with no output schema, the description covers the two result kinds and the date-range limit well. It is slightly incomplete only in not giving any sense of the returned item fields or pagination.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so from/to/staff_id are already fully documented, including the 31-day maximum. The description reinforces the date-range semantics but adds little parameter meaning beyond what the schema provides.

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 and resource ('Lists time off ... and blocked hours') and explains the two kinds it returns. It also distinguishes itself from mutation siblings by noting that time_off_id goes to remove_time_off.

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 clear: use it for a date range of at most 31 days, covering both Shifts time off and calendar blocked hours. It points to remove_time_off for deletion, though it does not explicitly state when not to use it versus add_time_off or other list tools.

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 annotations already declaring destructiveHint=true, idempotentHint=false, and openWorldHint=true, the description adds useful context: it deletes exactly one off-… or block-… item and 'reaches no client.' That no-client-reach detail is meaningful behavioral information beyond the annotations. It does not cover permissions or undo behavior, but the annotations carry much of that burden.

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, front-loads the effect ('so the time can be booked again'), then specifies the deleted object types and the no-client-reach behavior. There is no redundant or filler language.

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 destructive mutation with full schema coverage and rich annotations, the description gives enough behavioral context: what is deleted, which ID types are supported, and that no client is reached. It does not explain failure modes or whether the operation returns anything, but no output schema exists and the annotations already flag destructiveness and non-idempotence.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so both staff_id and time_off_id are already documented in the input schema. The description restates the accepted ID forms (off-… or block-…) but does not add syntax, constraints, or meaning beyond the schema. This is the expected baseline when the schema does the heavy lifting.

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: removing one time off or one calendar block. It also clarifies scope with the ID prefixes (off-… / block-…) and distinguishes behavior from client-facing actions via 'It reaches no client.' An agent can tell this is a deletion of a time-off/block object, not an appointment cancellation.

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 phrase 'so the time can be booked again' implies the use case, but the description does not explicitly say when to use this versus list_time_off or add_time_off. The schema mentions that the ID comes from add_time_off or list_time_off, but that guidance is not in the description itself.

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 beyond the annotations by disclosing the real-world consequences: the reply is publicly visible on the profile, the reviewer is notified, and a second call overwrites the prior reply. This adds genuine context to destructiveHint=true and idempotentHint=true, though it says nothing about permissions, moderation, or failure 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?

Front-loaded with the action, then the operational detail and side effects, with no filler. The phrase 'the way the Reviews page does' is the only sentence that contributes little beyond analogy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a two-parameter mutation with no output schema, the description covers what it does, where it lands, its visibility, and its overwrite behavior. Only permissions and error/edge behavior are unaddressed, which is a minor gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and both parameters are documented there, including the pointer to list_reviews for review_id. The description adds only the notion that the reply attaches to a single review, so baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb pair (post/change) and resource (public reply to a client's review), plus the target surface (Booksy profile). It is clearly distinguishable from siblings like list_reviews, which the schema also references for obtaining the review_id.

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 (to publish or edit an existing reply) and that a repeat call replaces the previous reply, but it never explicitly routes the agent away from alternatives or states prerequisites such as obtaining review_id first. Usage is inferable rather than guided.

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?

Beyond the annotations (destructive, non-idempotent, open-world), it discloses several behaviors an agent could not infer: all services shift by the same amount, a dry-run slot check may refuse the move, the client is silent unless notify_client is set, and the server may reject the appointment outright. These are exactly the mutation-side traits annotations can't express.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action, then the mechanics and caveats. Each sentence carries information (service shifting, dry run, notification, refusal), though the parenthetical about get_appointment is slightly compressed at the cost of readability.

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 destructive mutation with no output schema, the description covers the main risks (busy slot refusal, immutability escapes, silent client) well enough to call it safely. It doesn't say what a successful response contains, but that gap is minor given the tool's shape.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the field docs: 'start' governs the first service and all others shift in lockstep, and notify_client's side effect is characterized behaviorally rather than just 'tell the client'. This exceeds what the schema alone conveys.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a concrete verb+resource ('Move an appointment to a new start time') and adds the optional staff reassignment, which clearly separates it from create_appointment and cancel_appointment. No ambiguity about what the tool achieves.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It states real usage conditions: the dry run checks the new slot, a busy slot is refused, the client is only notified via notify_client, and appointments that can no longer be changed are rejected (discoverable via get_appointment). It doesn't explicitly contrast with cancel_appointment or create_appointment as alternatives, keeping it just 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.

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

Annotations already flag destructive/openWorld/non-idempotent, but the description adds real context beyond them: immediate send, EU marketing-consent filtering, failure when no recipient qualifies, SMS from an automated no-reply number, and consumption of the plan's text allowance. It does not describe the response payload or what partial delivery looks like, which keeps it short of a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action, then layering consent, SMS limits, the estimate recommendation, and plan requirements in a compact block. Dense but each sentence carries a distinct operational fact; a slightly tighter phrasing of the Booksy UI reference would earn a 5.

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?

No output schema exists, yet the description still tells the agent what failure looks like (fails when no client can receive) and steers to estimate_message_blast for counts/cost. It stops short of describing success response shape or partial-send outcomes, leaving a small gap for a destructive bulk-send 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 coverage is 100%, including the channel enum, subject default, and client_ids source, so the schema does the heavy lifting. The description adds only the indirect constraint that client_ids must be consent-eligible, which is a behavioral rather than a parameter-format clarification.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource (send one Message Blast to listed clients via email/SMS/push) and ties it to the concrete product path (Promotion > Message Blasts > Create your own message). It is clearly distinguishable from siblings like estimate_message_blast and list_message_blasts, which are named or implied.

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 directs the agent to run estimate_message_blast first for count/cost, states the paid-plan prerequisite (free trial refuses one-time messages), and gives the failure condition (call fails when no listed client can legally receive). That covers when to use, prerequisites, and the adjacent alternative.

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

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

Annotations already declare the write/non-idempotent/non-destructive profile, and the description adds two things they cannot: that unspecified fields are preserved, and that the client is not notified of the change. Missing only edge-case behavior such as what an empty string does, which the schema covers.

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 short sentences, front-loaded with what can be changed, then how partial updates behave, then the sibling comparison. The note sentence lightly duplicates the schema's note description, so it is not perfectly waste-free.

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 6-parameter mutation with full schema coverage and no output schema, the description covers scope, partial-update semantics, sibling routing and the notification side effect. Only the response shape and permission requirements are unstated, which is a minor gap here.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, including removal-via-empty-string and birthday format, so the schema carries parameter meaning. The description restates the editable field list and the note-replacement rule at a high level, adding convenience but no information beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (change) and resource (a client card) plus the exact set of editable fields. It is immediately distinguishable from siblings like add_client, delete_client and add_client_note.

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 covers partial-update semantics ('changes only the fields given') and names the alternative add_client_note with the condition that selects it (append a line instead of replacing). It stops short of stating when not to use this tool at all, e.g. versus delete_client or find_client.

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