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

Beyond the annotations (readOnly=false, idempotent=false, destructive=false), the description discloses concrete side effects: single non-recurring block, one day only, no notification sent to anyone, and client bookability gated by allow_online_booking. It does not cover edge behavior such as overlapping an existing appointment or validation failures, which keeps it off 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?

Two short sentences in the first paragraph carry the core purpose and scope, followed by a compact paragraph of behavioral caveats. No filler, no restatement of the title, and the most important constraint (blocks booking) 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?

For a six-parameter mutation with no output schema, the description covers purpose, scope limits, notification behavior, and the booking flag — enough to invoke it correctly. The remaining gap is what a caller gets back and how conflicts with existing appointments are handled.

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 baseline is 3; the description still adds intent-level meaning by framing the record as 'one block on one day for one team member' (constraining end_at to the same day) and explaining the practical consequence of allow_online_booking rather than just its default. The 'title and a note for the team' phrasing also clarifies the split between title and description.

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

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

Opens with a specific verb and resource plus the user-visible effect: 'Block a time slot in a team member's calendar so nobody books it.' This is clearly distinguishable from booking siblings like create_appointment and from find_available_slots, which read availability rather than create blocks.

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?

Anchors the tool to the product's 'Add > Blocked time' action and states key exclusions ('It does not repeat', 'Nobody is told'), which tell an agent this is not a recurring or notifying operation. It stops short of naming sibling tools or an explicit when-not-to-use condition (e.g. vs. reschedule_appointment).

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 non-readOnly, non-destructive, non-idempotent and open-world. The description adds genuinely useful behavior beyond that: nothing is sent at creation time, while appointment_messages=true triggers booking confirmations and reminders across email/SMS/WhatsApp, and marketing records consent. It does not cover duplicate-client handling or failure modes.

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 second sentence opens with a circular restatement ('Adds a client as Add client in the Client list does'), which wastes space before the genuinely useful message-consent explanation. The final sentence is well placed and front-loads the important 'nothing is sent' fact late.

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 7-parameter mutation with no output schema, the description covers the essential creation semantics and the non-obvious messaging side effects. Gaps are modest: no mention of duplicate-email behavior or what identifying data comes back.

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

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

Schema description coverage is 100%, so the schema already documents all seven parameters including defaults and the phone pattern. The description adds only light reinforcement of the appointment_messages/marketing effect, and even refers to 'mobile' where the schema calls the field 'phone'.

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 to the business's client list.' An agent can distinguish it from list_clients/get_client/add_client_note by the verb, though no sibling is 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 implied by the create verb, but there is no explicit guidance on when to use this versus alternatives (e.g., checking for an existing client first, or using add_client_note for notes). No exclusions or prerequisites are 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 establish that this is a non-read-only, non-idempotent, non-destructive mutation with open-world behavior. The description adds meaningful behavioral context beyond annotations: the note is visible to the team only, the client is not notified, it applies across all locations, and line breaks become paragraphs. It does not cover permissions or response behavior, but the added context is substantial.

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, front-loads the core action, and each sentence contributes useful information: purpose, destination/scope, and visibility/formatting behavior. There is no redundant restatement of the name or schema.

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

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

For a simple two-parameter mutation with full schema coverage and annotations covering safety hints, the description is complete enough. It explains visibility, notification behavior, location scope, and text formatting, leaving little an agent needs to infer before calling 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 description coverage is 100%, so the baseline is 3. The description adds semantics beyond the schema by explaining that line breaks in the text become paragraphs and that the note applies to all locations, which clarifies formatting behavior and implies there is no location-scoping parameter.

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: adding a note to a client's profile. It also specifies the destination (Notes tab), scope (all locations), and visibility (team only), so an agent can understand exactly what the tool does 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 implies this tool is for internal team notes by saying the client is not told and only the team sees it. However, it does not give explicit when-to-use guidance, exclusions, or alternatives for communicating with clients, so usage is only implied.

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

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

The description goes well beyond the annotations: it discloses irreversibility ("cannot be undone here"), side effects (the client may be messaged), refusal conditions, and series-wide blast radius. However, some of this overlaps the destructiveHint=true / openWorldHint=true annotations, and it never describes what the call returns, which matters given there is no output 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?

Front-loaded with the action and its key caveats, and most sentences carry distinct information. There is mild redundancy between the paragraph text and the schema on whole_series/notify_client defaults.

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, it covers safety, side effects, refusal conditions, and scope. The remaining gap is the return value (e.g., which appointments were cancelled) and how to recover after an unexpected series cancellation.

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 input schema. The description restates the notify_client default and the whole_series meaning without adding format, syntax, or edge-case detail beyond the schema, so the baseline 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?

Specific verb + resource ("Cancel an appointment") plus scope qualifiers (single vs whole series) and an explicit analogy to the in-product Cancel action. It is clearly distinguishable from siblings like reschedule_appointment or 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?

Explicitly states the precondition that selects the alternative: an appointment with a cancellation fee or paid deposit is refused and must be cancelled in Fresha instead. It also names the quiet-vs-notify choice so the agent knows which mode to pick per situation.

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 destructive=true, openWorld=true and idempotent=false, so the safety profile is covered; the description adds real context beyond that: services are booked sequentially from start_at at catalogue price, and the booking can send a real confirmation to the client. The only thing left vague is what the call returns on success or how the over-booking warning surfaces in this tool's own response.

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 compact sentences, front-loaded with what the tool does before the prerequisites and side effects. Every clause earns its place – the calendar analogue, the sequential booking, the client notification and the double-booking warning all change agent behavior.

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 4-parameter destructive mutation with no output schema, the description covers ordering, pricing, external side effects and the slot-checking prerequisite. The remaining gap is the response shape, which is neither documented here nor in an 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 description coverage is 100%, so every parameter is already documented, including the walk-in default and the team-member default. The description reinforces semantics (services run one after another from start_at with a single team member) but adds no format, ordering or constraint detail the schema does not already carry. 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 ('Book an appointment') plus the key inputs (services, team member, start time), and anchors it to a concrete analogue: 'as New appointment in the calendar does'. An agent can distinguish it from list_appointments, reschedule_appointment and find_available_slots 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 an explicit prerequisite ('Find free times with find_available_slots first') and a concrete consequence of skipping it ('Fresha books over other appointments and returns its warnings'). It also routes to get_client for the notification-settings question, so both when-to-use and which sibling to consult are spelled out.

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, openWorld, and non-destructive behavior. The description adds useful behavioral context: 'Times are wall clock in the business's time zone; closed days have no times' and sequential service scheduling. No contradictions with 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 sentences, front-loaded with purpose. The second sentence is slightly redundant with 'Asks the calendar for free start times as New appointment does,' but overall the description is efficient and every sentence contributes.

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, but the description conveys return structure ('day by day') and key behavioral traits (timezone, closed days). For a read-only tool with full annotations and complete parameter schema, this is sufficiently 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 the baseline is 3. The description reiterates 'one or more services' and 'up to 14 days' but adds little meaning beyond what the schema already provides (e.g., service_ids order, days min/max/default are all documented in 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: 'Free start times for one or more services with a team member, day by day.' It also distinguishes from the booking tool by directing the agent to create_appointment. An agent can readily tell what this tool does versus 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?

Provides a clear next step: 'Book a time with create_appointment.' However, it does not explicitly state when NOT to use this tool or contrast it with other listing tools like list_appointments. Implied usage is clear enough for an agent to select it before booking.

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 open-world, so the safety profile is covered. The description adds genuinely useful context beyond that: timestamps are wall clock in the business's time zone, the payload includes balance remaining after the total, and appointment notes are returned.

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 sentence elaborates on the returned fields. There is mild repetition between the two ('client, services, team member' appear in both), but every sentence carries information 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?

With no output schema, the description is the only place return values are described, and it does that adequately: status, times with time zone semantics, client, per-service team member and length, totals and balance, and notes. For a single-parameter read tool with full annotation coverage, this is sufficient to call 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?

There is one parameter and schema description coverage is 100%, with the schema already explaining that the id comes from list_appointments and constraining it to digits. The description adds no further meaning about the identifier, so the baseline of 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 description states a specific verb and resource ('One appointment') and enumerates the fields returned (client, services, team member, times, status, price, notes), which distinguishes it clearly from list-oriented siblings. It stops short of naming list_appointments as the companion tool inside the description itself, though the schema covers that linkage.

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 rather than stated: 'One appointment' suggests this is the single-record read rather than a list, and the schema notes the id comes from list_appointments. There is no explicit when-to-use/when-not or named alternative in the description text.

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=true, idempotent=true, destructive=false and openWorld=true, so safety is covered; the description adds genuinely new behavioral detail by stating the result caps ("next 10 appointments", "latest 10 notes") and that output mirrors the client's page. It stops short of noting what happens for a nonexistent client_id or whether data is truncated/paginated.

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 the one-line summary before the detailed field breakdown. Slight redundancy between the list in sentence one and the restatement in sentence two, but the detail second sentence earns its place by adding caps and field types.

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, so the description must carry the return contract, and it does: exact field families, item limits on appointments and notes, and the "as the client's page shows it" framing. Combined with a fully documented single parameter and read-only annotations, an agent has everything needed to call 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 coverage is 100% and the client_id property already documents the pattern and origin ("Client id from list_clients."), so the description adds nothing about parameters. Baseline 3 is appropriate when the schema carries the field-level meaning.

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+resource ("One client: contact, notification settings, booking stats, upcoming appointments, notes") and enumerates the returned fields, so the agent knows exactly what this fetches. It implies the single-record counterpart to list_clients via "One client" but never names that sibling explicitly.

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

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

Usage is only implied: the pattern that client_id comes "from list_clients" hints at the list-then-fetch flow, but there is no explicit when-to-use, when-not, or named alternative (e.g., list_clients for browsing, get_sales_summary for aggregate numbers).

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 carry readOnly/idempotent/destructive=false, so the safety profile is covered. The description adds genuine context beyond them: rows are grouped per sale type with a totals row, an empty period returns no rows, and amounts are in the business's currency — all useful for interpreting results.

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 purpose then the return shape; every sentence contributes (metrics list, row structure, empty-period behavior, currency). Minor redundancy between the opening list and the parenthetical column list.

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 must describe the return shape, and it does: one row per sale type, Fresha's columns, a totals row, and 'columns names each key.' Only gap is any hint of aggregation granularity limits or currency conversion behavior.

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 (from required, to defaulting to from) are fully documented there. The description only restates 'for the days given' without adding format, timezone, or range-limit semantics, so it meets the baseline but no more.

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

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

Opens with a specific verb+resource ('Sales summary for a period') and immediately enumerates the metrics covered (sales, refunds, discounts, taxes, payments by type). The second paragraph's 'one row per sale type' shape implicitly separates it from the transaction-level list_sales sibling, though it never names an alternative.

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 grounds the tool in a known UI location ('Reads Reports > Sales summary for the days given'), which tells the agent this is an aggregated report pull. But there is no explicit when-to-use/when-not guidance and no mention of list_sales as the per-transaction alternative, leaving the 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?

Beyond the read-only/idempotent annotations, it discloses ordering (latest first), row granularity (one row per booked service), inclusion of cancelled appointments, wall-clock timezone handling, and pagination via next_cursor. The filter limitation on the first 100 rows is an important non-obvious 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?

The description is front-loaded with purpose and ordering, then describes return fields, pagination, and the filter caveat. It is slightly dense and repeats some field-level detail already available in the schema, but every sentence contributes useful behavioral context.

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 list tool with no output schema, it covers return fields, ordering, status inclusion, timezone semantics, pagination, and the important filter-scope limitation. An agent has enough information to call and interpret results correctly.

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

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

Schema coverage is 100%, so the schema already defines each parameter. The description still adds meaningful context by explaining that status/client/team_member filters only cover the first 100 rows and that pagination uses next_cursor, which is not apparent from the schema alone.

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 ('Appointments in a date range') plus the fields returned, and anchors behavior to 'Sales > Appointments' ordering. It is clearly distinguishable from siblings like get_appointment or list_sales.

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 concrete usage caveat: status, team member and client filters only apply to the first 100 rows of the date range, so busy ranges should be narrowed. It does not explicitly name sibling alternatives for single-appointment lookup, but the operational guidance 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 readOnly, idempotent, non-destructive and openWorld, so safety is covered. The description adds genuinely new behavioral context beyond that: default ordering (newest first), the field set returned, a total match count, and cursor-based paging via next_cursor.

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?

Dense and front-loaded, with the resource named first and paging last. Minor waste in repeating the searchable fields twice ('searchable by name, email or phone' then 'search matches name, email or phone'), but overall tight.

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 return-shape burden and does so: it lists the fields returned, the total count, the default sort, and how to page. Four optional parameters are all accounted for, leaving nothing an agent needs missing.

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

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

Schema description coverage is 100%, so every parameter is already documented with defaults and the 50-item cap. The description mostly restates the schema ('search matches name, email or phone', 'newest first by default', 'Page with next_cursor') rather than adding syntax or edge-case meaning, 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?

Opens with a clear verb+resource statement ('Clients of the business, searchable by name, email or phone') and enumerates the returned fields. It is distinguishable from get_client via the word 'Lists' and the paging/search framing, but never explicitly contrasts itself with the single-client 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?

Usage is implied by the tool's shape: an agent can infer this enumerates clients and supports a search filter. However, there is no explicit guidance on when to prefer list_clients over get_client (e.g., 'use get_client when you already know the id') and no stated exclusions.

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 spends its words well: it adds the ordering guarantee ('newest first'), the source domain (Fresha or Google), and the pagination mechanics via next_cursor. It doesn't discuss page-size defaults or rate limits, but those are minor given the annotation coverage.

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 is returned, then the ordering, then filters, then pagination. No filler and nothing buried at the end.

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, and the description compensates by enumerating the fields each review contains plus sort order and cursor paging. Combined with the fully documented schema, an agent has everything needed to call this correctly.

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

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

Schema description coverage is 100%, so every parameter is already documented. The description restates the filter dimensions in prose (rating, source, words, unreplied) and names next_cursor for paging, but adds no syntax, defaults, or edge-case semantics beyond what the schema provides — notably omitting `limit`.

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 ('Client reviews of the business') plus the exact payload each item carries (rating, text, author, client, appointment, source, replies). An agent can immediately distinguish this read-only listing from the mutation sibling reply_to_review 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?

Usage context is concrete: filter by rating, source, words, or reviews still without a reply, and page with next_cursor. The 'still without a reply' filter implicitly routes the agent toward reply_to_review, but no sibling is named and no exclusion (e.g. when to use a different listing tool) is 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 and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful context beyond that: amounts are in the business's currency, linked records carry an `_id`, and results are paginated. It stops short of saying how the date range is interpreted (inclusive boundaries, timezone) or what happens with very large ranges.

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 and reasonably tight: the shape of the rows comes first, then the pagination instruction. The two paragraphs partially restate each other (date range and column list appear twice), which costs a little economy but no clarity.

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 does the work of describing the return shape (columns, currency, `_id` on linked records) and pagination. That is enough to call the tool correctly, though the treatment of inclusive date boundaries and default range behavior is left to the schema alone.

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

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

Schema description coverage is 100%, with defaults for `to` and `limit` documented inline, so the baseline is 3. The description only reinforces 'date range' and 'next_cursor', adding no format details or constraint semantics beyond what the schema already 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 states a specific verb and resource ('Sales (invoices) in a date range') and enumerates the columns returned (sale number, date, client, status, gross total). It does not explicitly distinguish itself from the sibling get_sales_summary, so a reader must infer list-vs-aggregate on their own.

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 date-range framing; there is no statement of when to call this versus get_sales_summary or how to handle open-ended ranges. The pagination hint ('Page with next_cursor') is the only actionable 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, so the safety profile is covered. The description adds meaningful behavior beyond annotations: only active services are listed, results mirror the Catalogue, multi-price services appear as pricing levels, and bookings use the first level.

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 and tightly structured: the opening sentence names the resource and fields, and the second explains catalogue semantics and downstream tool usage. Every sentence carries operational value without 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?

With no output schema, the description compensates by explaining the returned service attributes, active-only scope, multi-price representation, and how service_id is used downstream. No essential calling context is missing for a read-only catalogue list tool.

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

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

Schema description coverage is 100%, so the single 'search' parameter is already fully documented in the schema. The description adds no parameter-specific guidance, 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 states a specific verb and resource ('Lists the active services of the business's location') and enumerates the returned fields: category, duration, price, and online booking availability. It also differentiates itself from adjacent workflows by pointing to find_available_slots and create_appointment for service_id consumption.

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 establishes the context: retrieving the catalogue of active services, including multi-price handling and the rule that bookings use the first pricing level. It does not explicitly name competing sibling tools or exclusion conditions, but the downstream usage guidance for service_id is concrete.

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 the safety profile is covered. The description adds useful context about what is returned (including business locations), but says nothing about ordering, pagination, or authorization needs.

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

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

Content is front-loaded with the resource and its fields. The phrasing 'Lists the team as Team members shows it' is slightly awkward and redundant, but overall there is little waste.

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 it does so by enumerating the member fields and noting locations are included. An agent can call this confidently; only ordering/pagination details are absent.

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 boolean include_former is fully documented in the schema ('Also team members who left. Default: false'). The description does not touch the parameter at all, so baseline 3 applies.

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

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

States a specific verb and resource (list team members) and enumerates the fields returned – name, email, role, bookings, services, location. It is clearly distinguishable from siblings like list_clients or list_services, though no sibling is 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?

The closing line 'Use team_member_id in the calendar tools' implies the primary workflow (discover members, then use their IDs for appointments). However, there is no explicit when/when-not guidance or mention of alternatives such as list_services for the service side.

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 write, destructive, open-world and non-idempotent, and the description adds real consequence: the reply is public on the business's Fresha page and the client is notified, plus who it is signed as. It falls short of explaining the non-idempotent/destructive angle — e.g. whether a second reply replaces the first or stacks — 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?

Short and front-loaded with the action and its audience. The middle sentence ('as Reply in Online reputation does') is slightly redundant framing that could be cut, but nothing else is wasted.

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 3-parameter write tool with no output schema, the description covers the action, the audience, the prerequisite and the identity option. The only real omission is what the call returns and what happens on a repeat reply.

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 (text, reply_id, reply_as enum) are already documented in the schema, including the enum meanings and the list_reviews provenance. The description restates signing-as-both rather than adding syntax, limits, or edge cases 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?

Specific verb+resource ('Post a public reply to a client's review') with the write target and visibility stated up front. It is clearly distinct from list_reviews and the rest of the sibling set, which are read/list or scheduling tools.

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 prerequisite chain: 'It needs a review that exists: take review_id from list_reviews,' which routes the agent to the sibling that produces the required input. It does not state any when-not-to-use conditions, but no competing reply tool exists.

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 destructiveHint/openWorldHint, the description discloses the crucial non-obvious behaviors: all services shift by the same offset with lengths and prices preserved, team_member_id reassigns every service, and notify_client=true (default) sends a client message while false moves it quietly. Refusal on cancelled/completed/no-show is exactly the kind of behavioral constraint 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?

Four sentences, front-loaded with purpose, then mechanics, then the notification default, then the refusal conditions. No filler and no repetition of 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?

With no output schema, the description never indicates what comes back after a reschedule (updated appointment, confirmation, error shape), which is the one remaining gap. Everything an agent needs to decide, prepare inputs, and anticipate side effects is otherwise 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; the description still adds meaning the schema lacks by explaining that start_at is the first service's start and that all remaining services are shifted relative to it, and that team_member_id applies to every service rather than one. It does not clarify timezone conversion, which is left entirely 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 ('Move an appointment to a new start time') plus the optional scope ('optionally to another team member'), which cleanly separates it from create_appointment and cancel_appointment in the sibling list. The added sentence about shifting all services makes the operation concrete.

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 when-not guidance: 'Cancelled, completed and no-show appointments are refused,' and equivalences the agent can reason from ('as Reschedule in the appointment drawer does'). It never names a sibling alternative for the refusal cases (e.g. create_appointment for a new booking), 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.