Waitwhile MCP by usefulapi

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

Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description still adds real value beyond them: 'Adds only; nothing is edited or sent to the customer' discloses append-only semantics and that no customer notification fires — behavior an agent could not infer from the hints.

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

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

Two short clauses plus the endpoint. The WRITE marker and the mutation scope are front-loaded, and every phrase carries information (append-only, optional linkage, target endpoint). Zero 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?

For a 4-parameter mutation with no output schema, the definition covers action, scope, optional linkage, append-only behavior and the REST target; annotations carry the safety profile. The only omission is what comes back on success (e.g., the created note id), which is minor for a write tool.

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

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

Schema coverage is 50%: content and customer_id are documented in the schema, while visit_id and location_id are bare. The description partially compensates by labeling visit and location as optional ('optionally tied to a visit and location'), clarifying the two undocumented fields' role and optionality, but adds no format or constraint details. Baseline 3.

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?

Starts with the explicit verb+resource ('WRITE: add one staff note to a customer's record') and immediately scopes it with 'optionally tied to a visit and location'. It is trivially distinguishable from the sibling waitwhile_list_customer_notes, which reads rather than appends.

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 'WRITE: add one staff note' and the append-only framing, but no sibling is named as an alternative and no precondition (e.g., when to attach a visit_id vs. omit it) is stated. Adequate context, no 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 flag destructiveHint=true and idempotentHint=true, and the description adds substantial context beyond them: the visit's post-state (COMPLETE + CANCELLED tag, record retained), and the non-obvious nuance that suppressing notifications may not stop scheduled reminders/follow-ups. That notification caveat is exactly the kind of behavioral detail annotations cannot convey.

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

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

Front-loaded with the operation type and scope, and the endpoint is placed last. It is efficient overall, though the notification-suppression caveat is stated twice across description and schema, costing some redundancy.

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

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

For a two-parameter cancel operation with no output schema, the description covers scope (one visit), side effects (state/tag, record retention), notification behavior, and the HTTP path. Nothing an agent needs to call it 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 description coverage is 100% and the send_notifications property already documents the suppression caveat in near-identical wording, so the description's restatement adds little. It does not add syntax or format meaning for visit_id beyond what the schema states.

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

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

States a specific verb (cancel) and resource (ONE visit, waitlist entry or booking) plus the resulting state change (COMPLETE + CANCELLED tag, not deleted). An agent can distinguish this from waitwhile_update_visit or a hypothetical delete without opening either schema.

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

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

The 'WRITE:' prefix and 'cancel ONE visit' framing make the write context clear, and the clarification that the visit is kept rather than deleted correctly disambiguates it from a destructive-delete intent. However, it never names an alternative (e.g. update_visit for rescheduling) or states when cancellation is inappropriate.

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 idempotentHint=false and destructiveHint=true, but the description adds real value beyond them: the concrete consequence ('calling it twice creates two visits'), the notification caveat that suppression may only stop the immediate message while scheduled reminders still fire, and the requirement of at least a name/phone/e-mail. It doesn't describe the response shape, but with openWorldHint and destructiveHint already covering safety, this is strong supplemental context.

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 'WRITE:' marker and the core create semantics, and every sentence carries information. It is slightly long, and the notification-suppression caveat is stated twice (description and the send_notifications schema field), which is mild redundancy rather than padding.

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

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

For a 12-parameter mutation with no output schema, the description covers the conditional branches, the required-field reality, the non-idempotency consequence, and notification behavior. It could say more about what the created visit returns or about service_ids/resource_ids interplay, but nothing essential to a correct call 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?

At 75% schema coverage the schema carries most parameter detail, but the description adds one thing the schema omits: although only location_id is required, practically 'at least a name, phone or e-mail' is needed. The date format (YYYY-MM-DDThh:mm) and the send_notifications flag nuance are also reinforced in prose.

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 'WRITE: create ONE visit at a location' — a specific verb and resource — then splits the two behaviors (waitlist vs booking) by presence of a date. This cleanly distinguishes it from siblings like waitwhile_update_visit, waitwhile_cancel_visit, and waitwhile_add_customer_note.

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

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

Explicitly states the two mutually exclusive modes ('Without a date it adds the customer to the waitlist; with a local date-time it creates a booking') and routes the excluded case to the correct alternative ('Visit notes are not supported here... use waitwhile_add_customer_note'). It also warns that repeated calls create duplicates, which is 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, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds only the endpoint path and the fact that the from-date is a local date; it says nothing about the return shape, ordering, or pagination that a first-available-slots query would benefit from.

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 compact sentences with the scoping clause and the intended use front-loaded. The trailing 'GET /visits/first-available-slots' is arguably noise for an agent but costs little and is not padded prose.

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 eight parameters, 63% schema coverage and no output schema, the description is on the thin side. It conveys the essential purpose but does not describe the returned slot structure, ordering, or how from_date/to_date and service_duration interact, which an agent calling this correctly would want to know.

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 63%, leaving party_size, service_ids and resource_ids undocumented in the schema. The description partially compensates by naming these three as optional narrowing filters ('party size, services and resources'). It adds real meaning beyond the schema, though it omits to_date, max_num_slots and service_duration.

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

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

The description gives a specific verb+resource ('first available booking slots of a location ... from a date') and even names the underlying endpoint. It is clear what the tool returns, but it never distinguishes itself from the sibling waitwhile_list_booking_slots or waitwhile_resources_availability, so an agent still has to guess which of the slot tools applies.

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 propose appointment times' gives an implied usage scenario, but there is no explicit when/when-not guidance and no routing to alternative slot tools. The agent gets a hint of context but no conditions that select this tool over its siblings.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds a meaningful disclosure beyond that — 'Contains personal data' — which is relevant for handling/output decisions, plus the underlying REST endpoint. It stops short of noting error behavior, but with annotations present this is above the bar.

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?

Compact and front-loaded: the resource and returned fields come first, then the privacy note, then the endpoint. Every fragment carries information and nothing is padding.

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

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

With no output schema, the description usefully enumerates the returned fields and flags personal data, which is enough for a single-param read-only tool. Missing only secondary details such as not-found behavior or auth requirements.

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% for the single customer_id parameter, so the schema already documents it. The description only restates 'by id' and adds no format, source, or lookup semantics, making 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?

States a specific verb and resource ('One customer by id') plus the fields returned (contact details, tags, per-location state, last visit). The singular 'by id' framing implicitly and clearly separates it from waitwhile_list_customers and waitwhile_search_customers.

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: fetch a single customer when you already hold the id. No explicit when-to-use guidance and no sibling alternatives (list_customers, search_customers) are named, so the agent must infer the routing.

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, openWorldHint=true and destructiveHint=false, and the description adds nothing beyond restating the GET endpoint. No word on permissions, error behavior, or what a missing id yields.

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 fragments with zero filler and the resource front-loaded. It is efficient, though the telegraphic style omits a verb that would make it read more naturally.

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 trivial single-parameter lookup this is minimally adequate, but there is no output schema and the description says nothing about the returned field shape. Annotations cover the safety profile, so the gap is modest rather than severe.

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% for the single data_field_id parameter, so the schema already carries the semantics. The description's 'by id' adds only marginal reinforcement, which is the baseline 3 case.

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 (a single data field) and scope (by id), which is enough for an agent to understand it retrieves one record. It does not explicitly contrast itself with the sibling waitwhile_list_data_fields, so it falls short of a 5.

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

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

No when-to-use guidance, no prerequisites, and no statement of when the list variant is preferable. The agent must infer that this is for fetching one field when its id is already known.

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, openWorldHint=true, and destructiveHint=false, so the safety profile is fully carried by structured data. The description adds only the HTTP method/path and the fact that a short name is the public-URL segment; it says nothing about return shape, errors, or rate 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?

One sentence plus the endpoint, front-loaded with the resource and accepted identifier forms. No filler, 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 trivial single-resource fetch with annotations covering safety and a 100%-documented schema, this is nearly complete. The only gap is that no output schema exists and the description does not hint at what a location object contains or how an invalid identifier is reported.

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

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

Schema coverage is 100% and the single parameter is documented there, so baseline is 3. The description earns an extra point by defining what a 'short name' actually is ('the part of its public Waitwhile URL'), a clarification the schema does not provide.

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

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

States a specific verb (get) and resource (one location), plus the exact endpoint GET /locations/{shortNameOrId}. It implicitly contrasts with list_locations and get_location_status by scoping to 'one location by id or short name', though it never names those siblings 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 rather than stated: an agent can infer this is for retrieving a single known location. There is no explicit when-to-use, no guidance on choosing this over waitwhile_list_locations or waitwhile_get_location_status, and no mention of failure behavior for an unknown id.

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, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds the useful behavioral signal that the data is 'live' status and enumerates what is returned, but says nothing about freshness/refresh cadence, auth scope, or failure behavior for a closed/invalid location.

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

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

Two tight sentences: the resource and its returned fields are front-loaded, and the endpoint is a compact trailing detail. 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 correctly compensates by naming the returned fields. It is nearly complete for a single-read tool, though it omits any note on units/format of the estimated wait or behavior when the location is not currently serving.

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?

Only one parameter exists and schema description coverage is 100%, so the schema already carries the semantics; the baseline is 3. The description adds nothing about location_id format or where to obtain it beyond the {locationId} path placeholder.

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 ('live status of one location') plus the concrete return fields (open/closed, waiting and serving counts, estimated wait) and the underlying endpoint. This distinguishes it from the sibling waitwhile_list_location_status, which covers many locations, without needing to open either schema.

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

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

Usage is implied rather than stated: the word 'live' suggests real-time polling versus the aggregated list endpoint, and 'one location' implies a known location_id. There is no explicit when-to-use/when-not guidance or named alternative (e.g., list_location_status for all locations, get_location for configuration).

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 a genuinely useful disclosure that the payload 'Contains personal data', but says nothing about permissions, error behavior, or whether data is masked.

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 fragments with the core meaning front-loaded and no filler. The 'GET /messages/{messageId}' fragment is largely redundant with the parameters but minimally reinforces the path binding.

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 field-level return expectations are unstated, and no permission or error context is given. For a trivial single-id lookup with full annotation and schema coverage this is minimally adequate but not rich.

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% for the single required message_id, so the schema already documents the parameter fully. 'One message by id' adds no format, source, or example beyond what the schema states.

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

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

States a specific verb ('Get') and resource ('message') scoped to a single record by id, which distinguishes it from the sibling waitwhile_list_messages. It is clear but does not explicitly name that sibling as the 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?

No when-to-use or when-not-to-use guidance is given. The single-record framing implies it is for fetching one known message rather than enumerating, but the agent must infer that this fits better than waitwhile_list_messages when it lacks an id.

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 fully covered structurally. The description adds nothing behavioral beyond restating the endpoint — no error/not-found behavior, no note on what a resource contains. No contradiction, but no added value either.

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

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

Two short sentences, front-loaded with the operation. The second sentence largely repeats the first in URL form, which is mildly redundant but costs almost nothing in length.

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

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

For a single-parameter getter with full schema coverage and annotations covering safety, the description is minimally sufficient. It omits any hint of what a resource object is or what happens on an invalid id, and with no output schema the agent gets no return-shape context from anywhere.

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?

One parameter with 100% schema description coverage ('Resource id.'), so the schema carries the meaning. The description's 'by id' adds no format, source, or constraint detail beyond it, which matches the baseline 3 for fully documented schemas.

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-less but unambiguous operation (fetch one resource) plus the resource and the underlying REST endpoint GET /resources/{resourceId}. An agent can distinguish it from waitwhile_list_resources because of the singular 'one resource by id'. It stops short of a fully explicit verb phrase like 'Retrieve a single resource', so not a 5.

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

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

No when-to-use guidance and no mention of the obvious alternative, waitwhile_list_resources, or of any prerequisite (e.g. needing an id obtained from the list call). The singular/by-id phrasing only weakly implies single-record lookup.

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 fully covered structurally. The description adds only the raw endpoint (GET /services/{serviceId}) and says nothing about error behavior for a missing id or the shape of the returned object.

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 telegraphic fragments with zero filler and the essential scoping ('one service by id') front-loaded. It is efficiently sized for a trivial getter, though the endpoint fragment is largely redundant with the tool name.

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

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

For a single-parameter read tool whose annotations carry the safety profile and which has no output schema, the description is sufficient to invoke it correctly. Minor gaps remain around not-found behavior and return contents.

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% for the single parameter, so the schema already documents service_id. The description's 'by id' adds no format, source, or constraint detail beyond that baseline.

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

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

States a specific verb and resource ('Get service', 'One service by id'), which cleanly separates it from the sibling list_services. It stops short of naming that sibling explicitly, so an agent must infer the singular/plural split from names alone.

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?

'by id' implies the precondition that a service_id is known, which is useful implied guidance. However, there is no explicit when-to-use or when-not-to-use statement and no mention of waitwhile_list_services as the alternative when the id is unknown.

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, destructiveHint=false and openWorldHint, so safety is covered. The description adds value by enumerating what the response contains (customer, state, tags, services, resources, party size, position, estimated wait, timestamps), which matters since 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?

A single front-loaded sentence that leads with the scope and then lists return contents, plus the REST endpoint on the tail. 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?

For a one-parameter read tool with no output schema, the description gives the agent a solid picture of the returned fields and the underlying endpoint. Only minor omissions (e.g., behavior when the id is not found) remain.

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 visit_id is fully documented in the schema. The description only restates 'by id' without adding format, source, or lookup guidance, 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 ('One visit ... by id') and clarifies the domain term ('waitlist entry or booking'). The singular 'by id' scope cleanly distinguishes it from list_visits and search_visits without needing to name them.

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 id' tells the agent an id is required and that this is the single-record fetch. It never explicitly says when to prefer this over list_visits or search_visits, nor when an id would be unavailable.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=true), lowering the bar. The description adds the entity-type coverage of the log, which is genuinely useful context, but says nothing about pagination behavior, date-filter semantics, or result volume beyond what the schema exposes.

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 tightly packed sentences: purpose and scope first, filtering second, endpoint last. Every clause earns its place with no redundancy.

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

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

For a 9-parameter, all-optional read tool with no output schema, the description supplies purpose, filter dimensions, and the underlying endpoint. Pagination mechanics are left to the schema, which is reasonable, so the only minor gap is guidance on result volume and cursor reuse in the description itself.

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 78%, near the baseline-3 threshold, but the description goes further by grouping the filters into meaningful dimensions (type, event, entity, location, date) that map onto type, event, entity_id, location_id, and from/to_date. It is silent on desc, limit, and start_after, which the schema handles on its own.

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 pair (list the account's audit log) and immediately defines its content scope (who changed what and when) plus the covered entity types. No sibling tool offers audit data, so the agent can route here without ambiguity.

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

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

'Filter by type, event, entity, location or date' implies the retrieval use case but never states when to use this versus other list tools or what prerequisite access it needs. Since no sibling overlaps in domain, the absence of an explicit alternative is tolerable but still leaves usage implied rather than 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=true and destructiveHint=false, so the safety profile is covered. The description adds genuine context with 'Dates are local to the location' and the endpoint path, but says nothing about pagination, result limits, how far a date range may span, or how the free-spot data is shaped, so it only modestly exceeds the annotations.

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

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

Two tight, front-loaded sentences: the resource and scope come first, then date semantics and endpoint. The trailing 'GET /visits/availability' is mild filler for an agent, but nothing is padded or repetitive.

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 and a fully documented input schema, the description covers what the tool returns at a high level and how dates are interpreted. It is close to complete, though a note on range limits or pagination would close the remaining 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%, so every parameter already documents itself (format, min/max, semantics); baseline is 3. The description's mention of 'free spots per resource and service' loosely maps to show_min_spots/resource_ids/service_ids but adds no syntax, defaults, or range guidance 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?

The description states a specific verb and resource ('Booking slots of a location') plus scope (date range, free spots per resource and service), and even names the underlying endpoint. It is clear on its own, but it never differentiates itself from close siblings such as waitwhile_first_available_slots or waitwhile_resources_availability, which an agent could easily confuse with this one.

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

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

The clause 'so you can see when an appointment can be booked' implies the intended use case, but there is no explicit when-to-use framing, no prerequisites, and no routing advice toward first_available_slots or resources_availability. Usage is inferable but not stated.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds the response record shape (content, author, visit/location, timestamps), which is useful given there is no output schema, but it says nothing about pagination, ordering, or volume limits for a list 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?

Two short, front-loaded fragments with no filler; the purpose and returned fields come first. The trailing HTTP route is slightly redundant with the structured schema but not wasteful.

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 purpose and the shape of returned notes, which is enough for an agent to invoke it correctly. The main omission is pagination or result-limit 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?

Only one parameter exists and schema description coverage is 100%, so the schema fully documents customer_id. The description's '{customerId}' path notation merely restates the single required parameter without adding format or constraint detail, making the baseline 3 correct.

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 customer notes') plus the fields returned, which is more than a tautology. It is distinguishable from the write sibling waitwhile_add_customer_note by the verb, but the description never names or contrasts that sibling explicitly, so it stops short of a 5.

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

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

Usage is only implied: an agent can infer this is the read path for customer notes, but there is no statement of when to call it versus waitwhile_get_customer (which likely also carries notes) or waitwhile_list_messages, and no prerequisites or exclusions are 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 readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds genuinely useful context beyond that: cursor-based paging with a 20-per-page default and an explicit warning that the payload contains personal data. It omits auth/permission requirements and rate 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?

Three short clauses with zero filler: scope and returned fields first, then paging/filtering, then the PII warning and endpoint. Everything is front-loaded and each sentence earns its place.

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

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

With no output schema, the description correctly compensates by enumerating returned fields, and it covers pagination, filter dimensions and the PII caveat. What remains missing is routing guidance against search_customers and any note on permissions, which for a read-only list tool is a minor gap.

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

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

Schema description coverage is 86%, so the schema already documents desc, limit, the date params, location_id and start_after. The description restates the filterable dimensions (location, external id, date) and the page size default but adds no syntax or format detail the schema lacks, so the baseline 3 applies.

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

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

States a specific verb and resource ('List customers') and enumerates the returned fields (name, phone, e-mail, tags, last visit, created/updated), which is more than a restatement of the title. It does not, however, position itself against the obvious sibling waitwhile_search_customers or waitwhile_get_customer, so an agent must infer the boundary.

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 conveys implied usage through its filter list (location, external id, created/updated date) and paging behavior, so an agent can infer when it is applicable. It never explicitly says when to choose this over search_customers or get_customer, nor does it state any prerequisites.

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 payload shape (type, options, where they apply) and the underlying GET /data-fields endpoint, but says nothing about pagination limits or rate behavior; the cursor hint lives in the schema instead. With annotations carrying the safety burden, this modest added context lands at 3.

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

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

Two tight sentences followed by the endpoint, with the resource definition front-loaded before the usage hint. No padding, though the raw "GET /data-fields" endpoint adds little for an agent that already has the tool name.

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

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

With no output schema, the description does carry the burden of describing returns, and it partially does so (type, options, applicability). Pagination is covered by the start_after schema entry. For a simple zero-required-parameter list tool this is close to complete, missing only explicit sibling routing.

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 80%, so the schema already documents q, limit, location_id and start_after; only external_id lacks a description. The description contributes nothing beyond that, though "where they apply" loosely gestures at the location_id filter. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific verb (List) and resource (custom data fields), and clarifies the resource with a parenthetical that ties it to intake/booking form questions. The singular sibling waitwhile_get_data_field is implicitly distinguished by the list-vs-fetch framing, and the description names what the records contain (type, options, applicability).

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 the ids to read answers on visits" gives downstream context for the returned ids, which is genuinely useful. However, it never says when to use this tool versus waitwhile_get_data_field, nor any prerequisite or exclusion. Usage is implied by the list semantics rather than 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=true, destructiveHint=false and openWorldHint=true, so the safety and scope profile is covered. The description adds the returned field set and the underlying GET /locations call, but says nothing about pagination behavior or rate limiting beyond what the cursor param already implies.

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 plus the endpoint marker, front-loaded with the resource and its payload. No filler or repetition.

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 what comes back, which is the main gap it needs to fill. It stops short of describing pagination or ordering behavior, but the schema covers those parameters adequately.

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% – desc, limit, external_id, start_after and country_code are each documented in the schema. The description lists response fields rather than adding parameter meaning, so the baseline 3 applies.

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

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

States a specific verb+resource ('List the account's locations') and enumerates the returned fields (id, name, address, time zone, opening hours, settings). The plural 'locations' plus the 'GET /locations' endpoint cleanly separates it from the sibling waitwhile_get_location.

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 downstream context ('Use the ids to filter visits, services and resources') but never states when to pick this over waitwhile_get_location or waitwhile_get_location_status, and offers no exclusions or prerequisites. Usage is implied rather than directed.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds that the data is 'live' and lists the returned fields, but says nothing about pagination behavior, rate limits, or freshness/staleness of the live counters.

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 enumerates return fields, followed by the endpoint. Nothing is wasted, though the trailing 'GET /location-status' adds little for an agent that already has the tool name.

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

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

With no output schema, the description usefully names the returned fields, and pagination is fully handled by the schema. It falls short only in not routing the agent against the closely named waitwhile_get_location_status sibling.

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 (limit, start_after) are fully documented in the schema, so the baseline of 3 applies. The description contributes no additional parameter meaning such as default page size or cursor lifetime.

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 (location status) and enumerates exactly what the response contains: open/closed state, waiting/served counts, wait time, booking counters. 'Every location' makes the aggregate scope explicit, so an agent can distinguish it from waitwhile_get_location_status (single location).

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 'every location' implies a cross-location aggregate use case, but the description never states when to prefer this over waitwhile_get_location_status or waitwhile_list_locations, nor any exclusions or prerequisites. Usage is only implied by the scope wording.

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 that with the PII warning ('Contains personal data') and the explicit 'cannot send' constraint. It omits pagination mechanics and rate/auth context, so not 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?

Three tight sentences plus the endpoint, fully front-loaded: resource and scope first, then filters, then the read-only/PII caveat. Every clause 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 usefully enumerates return fields and the state values, and it covers the read-only behavior. For a 10-parameter listing tool it could still note pagination behavior and the external_customer_id filter, so it is strong but not fully complete.

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

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

Schema coverage is only 50%, so the description must compensate, and it does by naming the filterable dimensions (location, visit, customer, state, date) that map to location_id, visit_id, customer_id, state, from_date/to_date, and by listing the state enum values in prose. It leaves external_customer_id, desc, limit and start_after solely 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 precise verb+resource ('List the SMS/e-mail messages Waitwhile sent to and received from customers') and enumerates the returned fields (channel, recipient, body, delivery state, error), plus the underlying endpoint GET /messages. It does not explicitly name the sibling it differs from, so it falls just short of 5.

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

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

'This only reads; it cannot send' usefully bounds usage, and the filter list implies when to reach for it, but there is no explicit when-to-use vs waitwhile_get_message or waitwhile_list_visits guidance. Usage is implied rather than 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=true, openWorldHint=true and destructiveHint=false, so the safety profile is covered by structured data. The description adds the transport hint ('GET /resources') and enumerates 'name, locations, services, availability flag and category structure', which tells the agent roughly what comes back, but says nothing about pagination despite a start_after cursor parameter.

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 tight sentence followed by the endpoint path, front-loaded with the verb and resource. Every clause carries information; the trailing 'GET /resources' is mildly redundant but harmless.

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 8 optional parameters and no output schema, the field enumeration compensates somewhat for the missing return definition. However, it omits pagination behavior and gives no sense of which filters combine or what defaults apply, leaving gaps for a tool this wide.

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 88%, so the schema already documents nearly every parameter including q, email, parent_id, is_category, location_id and the start_after cursor. The description only alludes to 'availability flag and category structure', adding no filter syntax or format detail beyond the schema — 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 (List) and resource (resources) and clarifies the domain meaning — 'the people, rooms, tables or equipment that serve customers' — which separates it from waitwhile_get_resource (single fetch) and waitwhile_resources_availability. It never names those siblings explicitly, so the differentiation is implicit rather than stated.

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

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

The description implies the browsing/listing use case but gives no explicit when-to-use guidance and no exclusions against the many sibling list tools (list_services, list_locations, list_users) or against waitwhile_get_resource for single lookups. An agent can infer the situation, but nothing is 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 readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the concrete transport detail 'GET /services' confirming the read path, and, with no output schema present, partially discloses the returned shape (name, duration, price, locations, resources, category structure), which is genuinely useful behavioral context the structured fields do not provide.

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 plus the endpoint reference; no padding or repetition. The trailing 'GET /services' is mildly redundant with readOnlyHint but is cheap and useful for agents that reason about REST paths.

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, zero-required list tool with no output schema, the description supplies the resource definition and a reasonable sketch of returned fields, and annotations carry the safety profile. It stops short of covering pagination behavior or the filter/parent-category relationships, but nothing critical for invoking it 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 86%, so the schema already documents nearly every parameter (q, limit, parent_id, is_category, location_id, start_after). The description's field list refers to returned data rather than query inputs and does not explain the undocumented external_id parameter or filtering composition, so it adds little beyond baseline.

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

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

States a specific verb and resource ('List services') and immediately clarifies the domain concept ('what customers book or queue for'), then enumerates the return fields. A reader can distinguish it from waitwhile_get_service by the list-vs-single semantics, though the description 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?

There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as waitwhile_get_service for a single record or the filter parameters for narrowing results. Usage is only inferable from the verb 'List', which is not stated 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 and destructiveHint=false, so the safety profile is covered. The description adds valuable disclosure that password data and tokens are never returned, but says nothing about pagination behavior (only the schema's start_after param hints at it), result ordering, or rate 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 tight sentences: the first front-loads what is returned, the second covers the data-hygiene constraint plus the HTTP route. Zero 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 annotations covering the safety profile and 83% schema coverage, the description is nearly complete. It could add a note on pagination or result ordering, but omitting it is minor for a read-only 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 83%, so the schema already documents q, role, limit, location_id, and start_after. The description adds no parameter-level detail (e.g. that q is a prefix match, or that role/location_id are arrays), leaving only external_id's purpose undocumented. 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+resource ('List the staff users of the account') and immediately enumerates the returned fields, which distinguishes it from siblings like waitwhile_list_customers and waitwhile_list_locations.

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 'staff users of the account' scoping, but no explicit when-to-use guidance or alternative-tool routing is provided. 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 declare readOnlyHint=true, openWorldHint=true and destructiveHint=false, so safety is covered. The description adds genuinely new context beyond that: it is cursor-paged, it exposes customer contact details (a privacy/data-sensitivity signal), and it maps to GET /visits. Return format specifics remain unstated but pagination and data sensitivity are useful additions.

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

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

Three dense sentences, front-loaded with the resource and its two flavors, followed by returned fields, filters, then behavioral notes. No filler, though the long enumeration of returned fields is heavy and could be trimmed.

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 14-param read tool with no output schema, the description enumerates returned fields, notes cursor pagination (matching start_after/next_start_after in the schema), and flags customer contact details. The one real gap is that it never routes the agent toward or away from search_visits when both could plausibly serve a lookup.

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?

With 14 params at 57% schema coverage, the description compensates by naming the filter dimensions (location, state, tag, customer, service, resource, booking date, created/updated date) and by clarifying that booking date is local time, distinguishing it from created/updated date which the schema covers separately. It does not account for external_customer_id, limit or desc, so coverage is good but not complete.

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) plus resource (visits) and disambiguates the resource itself: waitlist entries (people in line) and bookings (appointments). It also enumerates the returned fields, so an agent knows exactly what a visit contains. However, it does not differentiate itself from the sibling waitwhile_search_visits, leaving the List-vs-Search boundary 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?

The description lists what can be filtered by (location, state, tag, customer, service, resource, booking/created/updated date), which implies the use case of retrieving and narrowing visits. It never states when to prefer this over search_visits or get_visit, nor any exclusions or prerequisites, 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description confirms this is a GET and clarifies that 'availability' here means working hours per resource, adding some interpretive value, but it says nothing about pagination, timezone handling for the date, or what happens when date is omitted beyond the schema default.

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

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

Two tight sentences that front-load the purpose and meaning, with the example clarifying the ambiguous term 'availability'. The trailing endpoint path is mild redundancy but harmless.

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

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

There is no output schema, so the description should carry more of the return-shape burden; it conveys the concept but not the structure (per-resource entries, time ranges, whether all resources are returned when resource_ids is omitted). Adequate but with clear gaps for a read tool whose callers must parse the result.

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 all three parameters (date, location_id, resource_ids) are already documented in the schema. The description adds no format, default, or filtering nuance beyond that, so the baseline 3 applies.

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

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

States a specific resource (a location's resources) and the exact data returned (working hours/availability on a date), with a concrete example ('who is working today'). It is clear and specific, but does not explicitly differentiate itself from siblings like first_available_slots or list_booking_slots, which also surface time-based availability.

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

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

Usage is only implied: an agent can infer this is for checking staff/resource working hours, but the description never states when to pick this over first_available_slots or list_booking_slots, nor any prerequisites. No exclusions or alternatives are named.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful context beyond that: it warns the results 'Contains personal data' (PII handling) and notes the result set is 'Page-numbered', plus the underlying GET /customers/search endpoint. It does not describe ordering or what happens on no-match.

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

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

Three tight clauses, front-loaded with the primary search behavior, then the optional narrowing, then the PII/pagination caveats. No filler sentences and nothing buried.

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 search with no output schema, the description covers the matching rule, the narrowing filters, pagination existence and the PII sensitivity. The main omission is any statement of result ordering or how the agent should page using next_page, but the schema's page description partially covers that.

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 only 50%: q, page and limit carry descriptions, while tag, state and location_id are bare enums/strings in the schema. The description compensates by explaining that results can be narrowed by location, visit state or tag, and it restates the prefix-match semantics of q. Page/limit behavior is left entirely to the schema, so it adds value but not complete coverage.

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

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

States a specific verb and resource ('Search customers') plus the exact matching semantics ('prefix match on name, phone, e-mail or customer id'), which distinguishes it from the sibling list_customers that presumably enumerates without a query term. It stops short of explicitly naming list_customers or get_customer as the alternative, so it doesn't fully earn a 5.

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

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

The description implies when the tool applies (you have a partial identifier and want a prefix match) but never states when to use it instead of waitwhile_list_customers or waitwhile_get_customer, and gives no exclusions or prerequisites. Usage is inferable rather than 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=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds useful context beyond annotations: it is page-numbered, contains customer contact details (sensitive data), and maps to GET /visits/search. Auth requirements and rate limits are still absent, but the added behavioral context is solid.

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 tightly packed sentences with zero wasted words. Purpose is front-loaded, followed by filters, pagination behavior, data sensitivity, and the underlying endpoint, all in a logical order.

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 search tool with no output schema and annotations that cover safety, the description is nearly complete: it states the search mechanism, optional filters, pagination, and PII content. It omits sorting, empty-result behavior, and authorization requirements, but those are minor gaps given the structured fields already provide most parameter details.

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

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

Schema description coverage is 57%. The description repeats the q parameter's schema description and names the optional filters (location, state, tag, excluded tags), which adds some meaning for location_id, state, and tag that lack schema descriptions. However, it does not explain enum values, syntax, or the tag vs exclude_tags distinction, so it only partially compensates for the coverage gap.

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

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

The description names a specific verb (Search), resource (visits), and matching mechanism (prefix match on customer name, phone, e-mail or customer id). It distinguishes the tool's core behavior from a plain list operation, though it does not explicitly name the sibling waitwhile_list_visits as 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?

The description states what the tool does and what optional filters exist, which implies when it should be used. However, it offers no explicit guidance on when to choose this tool over waitwhile_list_visits, waitwhile_search_customers, or waitwhile_get_visit, and no when-not-to-use conditions.

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

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

Annotations declare destructive/idempotent/openWorld, but the description adds genuinely non-obvious behavior: default notification suppression may only stop the immediate status message while scheduled reminders still fire per location settings, and send_notifications=true contacts this ONE customer. It also discloses the partial-update mutation model and the HTTP verb/path, none of which structured fields carry.

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

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

Front-loaded with 'WRITE:' so the mutation nature is visible immediately, and each sentence carries routing or behavioral content. The notification caveat is stated in the description and then again in the schema, a mild redundancy, but overall density is appropriate for an 8-parameter mutation.

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?

Covers mutation scope, notification side effects, and the endpoint for a tool with no output schema. The one soft spot is the response shape — since there is no output schema, the agent gets no signal about what the update returns, though this is minor for a field-patch tool whose annotations already flag it as destructive.

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 88%, so the schema already documents parameters; the description still contributes domain meaning via state-flow examples (WAITING to SERVING to COMPLETE, or BOOKED) and concrete tag examples (ARRIVED, CONFIRMED, NO-SHOW). The send_notifications explanation largely restates its schema description, so it adds domain color more than net-new parameter semantics.

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

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

States a specific verb and resource ('change ONE visit') and enumerates the mutable surface: state, tags, booking date/duration, party size. It is immediately distinguishable from siblings by contrasting with waitwhile_cancel_visit and by scoping to a single visit versus create/list operations.

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?

Names an explicit alternative ('Use waitwhile_cancel_visit to cancel') with the condition that selects it, and clarifies the partial-update contract ('Only the fields you pass change'), which tells the agent it need not supply the full object. Nothing about tool selection is left dangling.

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 GET operation. Beyond that, the description usefully discloses that the tool returns aggregated rather than record-level data, and enumerates the metrics and breakdown dimensions the agent can expect. It still omits details such as default period behavior, rate limits, or pagination, so it is helpful but not fully comprehensive.

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

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

The description is a single dense sentence front-loaded with the core purpose, followed by an endpoint reference. The long enumeration of metrics and breakdowns is informative rather than wasteful, though the list is lengthy enough to slightly reduce readability.

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

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

With no output schema and annotations covering safety, the description does a good job listing the returned metrics and breakdown dimensions, and it names the endpoint and response format. It is nearly complete for an analytics tool, but it does not clarify default date range semantics or the exact response structure.

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 to_date, from_date, and location_id clearly. The description adds no parameter-level meaning beyond the schema—it does not explain date format edge cases, default period behavior, or how location_id interacts with breakdowns. Baseline 3 is appropriate when the schema carries the parameter semantics.

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

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

The description states a specific resource and return type: aggregated visit statistics for a period, explicitly listing the metrics and breakdown dimensions. It clearly distinguishes this analytics tool from sibling listing/search tools like list_visits and search_visits, which return individual visit records rather than aggregates.

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

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

The description implies usage through 'for a period' and the metric list, but it does not explicitly say when to use this tool versus alternatives such as list_visits or search_visits. No when-not conditions, prerequisites, or alternative routing guidance are provided.

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