Bookafy MCP by usefulapi

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

Annotations only declare destructive/not-read-only/idempotent; the description adds the consequences an agent cannot infer: the customer may be notified, the event is removed from connected calendars, and the appointment cannot be restored through the API. That is exactly the extra context annotations don't carry. The idempotentHint does not conflict with 'irreversible' — cancelling twice is still safe.

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 tightly packed sentences, with the risk classification front-loaded before the operational detail and the call condition. The trailing endpoint line is short and adds traceability rather than noise.

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 destructive mutation with no output schema, this covers the risk profile, the side effects, the irreversibility, and the authorization condition for calling it. Nothing an agent needs in order to act correctly is missing.

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

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

Schema coverage is 100%, so both parameters are already documented, including the provenance hint for appointment_id. The description adds no parameter-level meaning beyond confirming that the id is the DELETE path segment. 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 ('delete (cancel) an appointment') up front, and the WRITE/IRREVERSIBLE prefix distinguishes it immediately from read siblings like bookafy_list_appointments and from bookafy_update_appointment. An agent can select 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?

Gives an explicit gating condition: 'Only call it when the user explicitly asked to cancel this appointment.' That is a real exclusion rule rather than implied usage. It stops short of naming the alternative for the adjacent case (rescheduling via bookafy_update_appointment), so it is not 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 declare non-read-only, non-idempotent, open-world behavior, but the description adds materially: a customer record is created as a side effect, a confirmation email may be sent, connected calendars may be updated, and times are converted to UTC. These external side effects are exactly what an agent needs before committing to a booking.

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 sentences, front-loaded with the WRITE classification, the effect statement, and the guardrail, ending with the endpoint. No filler, and the riskiest information (outbound email, calendar writes) is surfaced before the alternative routing.

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 an 11-parameter mutating tool with no output schema, the description covers prerequisites, side effects, and time semantics well. The remaining gap is the return value: with no output schema, the agent has no idea whether an appointment id comes back for later update/cancel 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 coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema: ids must be sourced from bookafy_list_staff and bookafy_list_services, the customer is derived from the provided name/email/phone, and start/end are normalized to UTC. Only the optional price/title/description/custom_fields semantics are 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?

Opens with an explicit verb, 'WRITE: book an appointment', then names the resource and the three entities involved (customer, staff member, service). It distinguishes itself from sibling list/update/cancel tools by naming where the ids come from (bookafy_list_staff, bookafy_list_services), so the agent can identify the tool without opening the schema.

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

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

Gives a clear exclusionary rule: 'only call it when the user clearly asked to book', which is a real when-not condition for a tool with external side effects. It also points to sibling tools for prerequisite ids. It does not explicitly contrast with bookafy_update_appointment for modifying an existing booking, so it stops short of a full when/when-not/alternatives treatment.

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, non-destructive, non-idempotent and open-world behavior, so the description only needs to add context. It does contribute the underlying endpoint (POST /api/v3/customers) and reinforces the write nature, but says nothing about duplicate handling when a customer with the same email already exists, which is the key behavioral risk for a non-idempotent create.

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 clauses plus an endpoint reference; the write marker and required-field note are front-loaded and every fragment carries information.

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

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

With no output schema, the agent does not learn what the call returns (e.g., a new customer ID usable in bookafy_create_appointment), nor how to recover from a duplicate-email failure. For a create tool that is typically chained into a booking flow, that is a meaningful 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%, including the nested custom_fields example with underscore naming, so the schema carries the parameter burden. The description's restatement that name is required and email/phone/custom_fields optional adds no meaning beyond what the schema already 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?

States a specific verb and resource ('add a customer record') and immediately delimits scope against the sibling it is most likely confused with: 'It does not book anything.' An agent can distinguish it from bookafy_create_appointment and bookafy_update_customer without opening the schema.

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

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

Gives clear selection context by excluding the booking behavior, which is the main ambiguity for a customer tool in an appointments API. It stops short of naming the alternative ('use bookafy_create_appointment to book') or stating prerequisites, so an agent must still infer the ordering relative to appointment creation.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered by structured data. The description adds the useful detail that the result is scoped to the calling API key's identity, but says nothing about error behavior when a key is invalid or about the shape/limits of the 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 the meaning of the resource and followed by the use case. The trailing endpoint path is mildly redundant for an agent but aids traceability and costs only a few tokens.

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 carries the burden of describing the result, and it does name the key returned field (the admin user's email). For a no-parameter read tool with full annotation coverage, that is close to sufficient; only error/missing-key behavior is left implicit.

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 of 4 applies. The description correctly adds no parameter prose, and the documented 'GET /api/v3/me' endpoint corroborates that no input is expected.

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 resource (the account tied to the API key) and goes further by naming the concrete return value: the admin user's email. That is far more informative than the bare title 'Get account', and no sibling tool overlaps with this identity lookup.

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?

'Use it to confirm which Bookafy account is connected' gives clear situational context for invoking it, which is more than most read tools offer. It does not name when not to use it or any prerequisite, but for a zero-parameter identity check there is little ambiguity to resolve.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds real behavioral context beyond that: the optional filters narrow sessions rather than the class itself, and the response carries attendee PII (name, email, phone, booking time).

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-load what the tool returns, followed by the filter behavior and the HTTP path. Every element is short and earns its place, with 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 usefully enumerates the returned payload shape (sessions plus attendee name/email/phone/booking time). The filter and required-id semantics are covered, so an agent can call this correctly; only the empty-result or not-found behavior is left implicit.

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 including the from/to/price/duration/attendee_name/provider_name filters is already documented with bounds and formats. The description's only addition is that filters scope sessions, which the schema also states; 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 resource and scope: a single class with its sessions and the attendees booked on each, including the attendee fields returned. That distinguishes it from bookafy_list_classes (plural listing), though it never names the sibling explicitly.

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

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

The singular-resource framing and the required class_id imply this is the detail-fetch for a class already known, versus the list tools. However, there is no explicit when-to-use statement and no guidance on when to prefer it over bookafy_list_session_attendees, which covers overlapping data.

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 annotations already establish that this is a read-only, non-destructive, open-world operation. The description meaningfully adds that results are newest first, that each item includes specific fields, that pagination defaults to 25, that cancel/reschedule tokens are never returned, and that it uses the GET /api/v3/appointments endpoint.

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 compact and front-loaded: it first states what is listed and for whom, then return fields, pagination, token behavior, and endpoint. Every sentence contributes useful information, with only minor overlap with the schema.

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

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

There is no output schema, but the description compensates by listing the returned fields, ordering, pagination behavior, and important security behavior around cancel/reschedule tokens. Combined with the annotations and full schema coverage, an agent has enough context 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 coverage is 100%, so the input schema documents parameter formats in detail. The description still adds useful meaning by identifying staff_email as coming from bookafy_list_staff, clarifying the UTC date range, and describing page/per_page behavior. It does not need to repeat all schema details.

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: list the appointments of one staff member. It adds important scope details such as required staff email, newest-first ordering, optional UTC date range, and pagination. It also indirectly distinguishes this from sibling tools by pointing to bookafy_list_staff and noting that cancel/reschedule tokens are never returned.

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

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

The description gives clear usage context: the tool is for listing appointments of one staff member, and the required email should be taken from bookafy_list_staff. It explains optional date filtering and pagination. It does not explicitly state when not to use it or name a direct alternative, but the context is clear.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds real value beyond them: it discloses that each item carries a public booking-page link and that output is grouped by category, plus the underlying GET endpoint. It does not state whether the list is complete or paginated, which is a minor gap for a no-parameter list.

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?

A single front-loaded sentence describing the resource and return shape, followed by the concrete use case and the endpoint. No filler, and the most decision-relevant information (booking link) appears early.

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

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

There is no output schema, so the description must convey what comes back — and it does, describing grouped appointment types each with a booking link. Missing only pagination/volume expectations for a call with no filtering options.

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 conveys that there is nothing to filter or supply, and the 100% schema coverage means nothing is left undocumented.

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

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

States a specific verb (list) and resource (appointment types) and adds the differentiating detail that results are grouped by category with public booking links. It does not explicitly distinguish itself from the nearby sibling bookafy_list_services, so the boundary between 'appointment types' and 'services' is left to inference.

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 a concrete scenario — 'use it to give a customer the link to book themselves' — which tells the agent when this tool is the right pick. It stops short of naming exclusions or alternatives (e.g., when to use list_services instead), so it is clear context without 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?

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description usefully adds the shape of the returned data, but says nothing about pagination, result limits, or ordering for what could be a large listing.

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?

A single dense sentence front-loads the resource and then the payload fields, followed by the raw endpoint. Nothing is wasted, though the trailing GET path is mildly redundant with the annotations and 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?

With no output schema, the description carries the return-value burden and does so by enumerating the fields and nested session attributes. The remaining gap is operational detail — pagination and result size — which matters for an unfiltered list endpoint.

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 and the schema is empty, so there is nothing to disambiguate; baseline 4 applies. The description correctly avoids inventing filter semantics that the schema does not support.

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 (list) and resource (classes and one-off appointments), and enumerates the returned fields — price, duration, location, seats, booking link, sessions — so an agent knows exactly what it gets. It does not explicitly distinguish itself from the close sibling bookafy_list_appointments, which leaves some ambiguity about which list tool covers what.

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 name and by the field enumeration, but there is no explicit when-to-use guidance and no alternative named (e.g., bookafy_get_class for a single class, or bookafy_list_appointments for appointment records). An agent must infer the routing decision from the sibling names alone.

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 safety is covered. The description adds real context beyond that: Bookafy returns the entire list in one response rather than a truncated page, and next_offset can be fed back to continue reading — response-shape information that annotations do not carry.

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

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

Three short sentences, front-loaded with what is returned before the paging guidance. The trailing 'GET /api/v3/customers' is mildly redundant for an agent but does no harm.

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 usefully discloses the returned field set and the next_offset continuation token, which is exactly what an agent needs to page correctly. Missing only an explicit note on default ordering or volume limits, which are minor for a filtered list.

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%, with limit (1-500, default 100), offset (default 0, use next_offset) and search (case-insensitive name/email/phone) all documented in the schema. The description restates search's matching fields and the paging loop but adds no syntax or semantics the schema lacks.

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 ('List the account's customers') and enumerates the returned fields (id, name, email, phone, custom booking-form answers), which distinguishes it from write siblings like create_customer and update_customer. It does not explicitly name the sibling tools, but the read-only listing intent is unambiguous.

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?

Tells the agent to use `search` for name/email/phone matching and `limit`/`offset` to page, and communicates that the full list is returned at once so paging is a client-side concern. It stops short of stating when to prefer this over a direct customer lookup or which sibling to use for fetching a single customer.

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 read-only, non-destructive, open-world operation, so the safety profile is covered. The description adds the returned field set and endpoint, but does not mention pagination, auth requirements, or result limits.

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 short, front-loaded sentences with no filler. The returned fields, booking-id usage, and endpoint are all packed efficiently.

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 appropriately enumerates the key returned fields and explains the practical use of the ids. The main remaining gap is the unresolved relationship to bookafy_list_appointment_types, which matters for correct tool selection.

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 has zero parameters, so there are no parameter semantics to explain; the baseline for zero-parameter tools is 4. The description correctly focuses on output fields rather than inventing parameter details.

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: list every service, with a concrete set of returned attributes. It does not distinguish this tool from the sibling bookafy_list_appointment_types, and calling services 'appointment types' makes that overlap more ambiguous rather than less.

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 one useful usage cue: use the returned ids when booking. However, it does not say when to choose this over bookafy_list_appointment_types or whether they are aliases, so the agent is left to infer the intended selection.

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 safety is covered. The description adds the return fields and the underlying endpoint (GET /api/v3/sessions), but says nothing about pagination, empty results, or limits.

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 with the returned fields front-loaded and the prerequisite follow-up; nothing wasted. Slightly fragmentary style, but efficient.

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 one-parameter read tool with no output schema, the description covers what's returned and where to get the id, which is sufficient to call it correctly. Pagination behavior is the only notable omission.

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

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

The single session_id parameter is fully documented in the schema, including its link to bookafy_list_classes, so the description adds no new parameter detail. Baseline 3 applies when schema coverage is 100%.

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 precisely (attendees of one class session) and even enumerates the returned fields (name, email, phone). It doesn't contrast with siblings like bookafy_list_customers, but the 'session attendees' framing is specific enough to select 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?

'Get session ids from bookafy_list_classes' gives an explicit prerequisite and routes the agent to the correct sibling for obtaining the required id. No when-not-to-use guidance, 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 declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds the returned fields and the HTTP endpoint, but does not mention authentication needs or pagination behavior for the staff list.

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 clauses and front-loads the core purpose and returned fields. Every phrase adds useful information with no redundant restatement of 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?

With no output schema, the description appropriately lists the returned fields so the agent knows what to expect. It is nearly complete for a no-parameter list tool, though it omits pagination or whether all staff are always returned.

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 are zero input parameters, which sets the baseline at 4. The empty schema is consistent with the description, and there are no parameter semantics that need additional explanation.

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 ('List the staff users') and enumerates the returned fields (id, name, email, booking-page URL). The staff-member resource is distinct from all sibling tools, so an agent can identify its purpose 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 phrase 'Use the id or email for appointments' explains downstream usage of the returned identifiers, but it does not say when to choose this tool over alternatives or state any exclusions. Usage is implied by the tool name rather than explicitly 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so "Read-only" adds no new information. The endpoint (GET /api/v3/api_subscriptions) is mild added context, but nothing is said about pagination, result volume, or auth requirements for a listing that could be long.

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

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

One sentence plus a short endpoint tag, with the resource and its returned fields front-loaded. Nothing is wasted or restated beyond the useful field 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 partially compensates by naming the key return fields, and with zero parameters the call surface is fully covered. The remaining gap is whether the list is paginated or filtered, which an agent would need to know before consuming results.

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 to disambiguate; baseline for a parameterless tool applies. The description correctly does not invent filtering options that the empty schema does not support.

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 the webhook subscriptions") and enumerates the returned fields (id, callback URL, event type with example values). No sibling tool touches webhooks, so it is trivially distinguishable from the appointment/customer/staff 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?

Usage is only implied by the read-only nature and the absence of parameters; the description never says when to call this or what to do with the results. There is no direct alternative among the siblings, so the omission is less costly, but no explicit context is given.

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 idempotentHint=true, but the description adds real behavioral context the annotations cannot: omitted optional fields are not sent (partial-send semantics), times are converted to UTC, and the customer may be notified as a side effect. It does not state permission requirements or what the response contains, keeping it just short of the top mark.

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 the WRITE marker and the core action, then prerequisite, then side effects, then transport detail. Every sentence carries distinct information with no restatement of 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 12-parameter destructive mutation with a nested custom_fields object and no output schema, the description covers action, prerequisites, side effects and timezone handling. Minor gaps remain around authorization requirements and whether notification is unconditional, but nothing essential for correct invocation is missing.

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

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

Schema description coverage is 100%, so the schema baseline is 3; the description earns above that by explaining the semantics of omission for optional fields and calling out that all of staff, service, start, end and customer_name are mandatory regardless. It adds no format detail beyond the schema (ISO 8601, custom_fields naming) because the schema already carries 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?

Opens with an explicit mode marker ('WRITE:') plus a specific verb pair and resource ('reschedule or edit an existing appointment'), which cleanly separates it from bookafy_create_appointment and bookafy_cancel_appointment. It even names the underlying endpoint (PUT /api/v3/appointments/{id}), leaving no ambiguity about what is being changed.

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 a concrete precondition workflow ('read current values with bookafy_list_appointments first') and enumerates the values that must be supplied. It does not explicitly exclude adjacent cases — e.g. that removing an appointment should go to bookafy_cancel_appointment — so it is a strong but not fully disambiguating guideline.

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 destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds genuinely new behavioral context: fields omitted are not sent, so this behaves as a partial update rather than a full replacement despite the PUT endpoint — an important clarification for an agent worried about wiping fields.

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

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

Four short clauses, front-loaded with the WRITE label and the operation, then the non-obvious constraint, then the endpoint. No filler; every sentence carries information.

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

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

For a 5-parameter mutation tool with full annotation coverage and no output schema, this covers operation, partial-update semantics, and the key required-field gotcha. The only real gap is guidance on choosing this tool versus create_customer.

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 schema already states the name is 'required by Bookafy on every update', so the description's name guidance largely repeats it. The 'fields you leave out are not sent' clause does add useful semantics about how the parameters combine, but nothing about custom_fields or the id source beyond what the schema gives.

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 ('change a customer's details') and labels itself WRITE, which distinguishes it from the read siblings like bookafy_list_customers and bookafy_get_account. It does not explicitly contrast with bookafy_create_customer, so the create-vs-update distinction is left implicit.

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 real procedural guidance ('pass the current name when you only change the email or phone') and clarifies partial-update semantics. However, it never says when to choose this over bookafy_create_customer or bookafy_list_customers, nor what preconditions (e.g. the customer must already exist) apply.

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