Appointedd MCP by usefulapi

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

The description adds the irreversibility warning ('cannot be undone') and the side effect that Appointedd may notify customers according to organisation settings. These details go beyond annotations, though it does not cover permissions, response behavior, or idempotency context that annotations imply.

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

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

The description is front-loaded with 'WRITE (cannot be undone)' and then proceeds directly to scope, side effects, alternative, and endpoint. Every sentence earns its place and there is no 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?

For a simple one-parameter destructive cancel, the description covers irreversibility, notification side effects, sibling differentiation, and the endpoint. Combined with annotations and schema, an agent has enough to invoke it correctly.

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

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

There is one parameter and schema description coverage is 100%, so the schema already documents booking_id fully. The description adds no additional meaning about the parameter beyond the endpoint path template, so the baseline of 3 is appropriate.

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

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

The description states a specific verb and resource: cancel a whole booking. It explicitly distinguishes this from appointedd_cancel_booking_customer, which handles removing one customer from a group booking. An agent can identify the correct sibling without opening either schema.

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

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

It names the alternative tool and the condition that selects it: use appointedd_cancel_booking_customer to remove one customer from a group booking. This makes the whole-booking scope explicit and prevents misuse.

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, so the safety profile is known. The description adds value by spelling out irreversibility ('cannot be undone') and the partial-cancellation semantics (other customers remain), plus the underlying endpoint. It does not describe response behavior for an already-cancelled customer.

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/cannot-be-undone warning, then the scope, then the id provenance, then the endpoint. Dense and zero 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?

Two required string params, full schema coverage, rich annotations, and no output schema — everything an agent needs to invoke it correctly is present. Only minor gap is not stating error/idempotent behavior when the customer is already cancelled.

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 says customer_booking_id comes from the booking's customers list, so the description's restatement adds little beyond provenance emphasis. Baseline 3 applies since the schema carries parameter documentation.

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

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

Specific verb+resource (cancel one customer's place on a booking) with scope clarification that the booking itself survives. This distinguishes it cleanly from the sibling appointedd_cancel_booking, which cancels the whole booking.

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

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

The parenthetical '(the booking stays for the others)' makes the selection condition clear relative to the whole-booking cancel sibling, and the description states which id to supply. It stops short of explicitly naming appointedd_cancel_booking as the alternative for cancelling everything.

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

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

Beyond annotations (readOnlyHint=false, openWorldHint=true), the description discloses the significant side effect that Appointedd may create CRM customer records via name/email/mobile matching, and that the payment-request default here differs from the API's own default. It also notes the empty-list edge case that produces an empty 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?

One dense, front-loaded sentence block starting with a 'WRITE:' marker, then the two behavioral caveats, then the endpoint. Every clause carries information; nothing is padded.

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

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

For a mutation tool with no output schema, it covers preconditions, side effects, and defaults well. The one gap is that it never indicates what the call returns (e.g., the created booking and its id), which an agent would need to chain follow-up calls.

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

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

Schema description coverage is 100%, so all five parameters (including the nested profile fields) are already documented. The description restates the send_payment_request and empty-customers semantics that the schema largely covers, adding little new meaning — 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 (turn a reservation into a booking), scopes it ('for one or more customers'), and positions it in the workflow as 'step 3' plus the HTTP endpoint. Sibling tools like appointedd_create_reservation and appointedd_update_booking are clearly distinguishable from 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 'step 3' framing and the requirement that reservation_id come from appointedd_create_reservation gives clear preconditions for use. It does not explicitly state when to call appointedd_update_booking instead of this tool, so routing guidance is strong but not exhaustive.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=true, so the safety profile is covered. The description reinforces the write nature with 'WRITE:' and the HTTP verb, but adds nothing about duplicate handling (relevant given idempotentHint=false) or what is returned on success.

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 compact sentence plus an endpoint reference, with the write nature and required fields front-loaded. Nothing is padded or redundant.

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?

Not applicable — see below.

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% — email, phone, and mobile have no schema descriptions. The description compensates partially by restating which fields are required (firstname, lastname) and which are optional, but gives no format or constraint hints beyond the field names, which the schema's required array already conveys.

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

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

States a specific verb and resource ('create a customer in the CRM') and even names the underlying endpoint (POST /customers). Against siblings like update_customer, get_customer, and list_customers, the verb alone lets an agent route correctly without opening any schema.

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

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

The 'WRITE:' prefix and the create verb imply when this applies, but there is no explicit guidance on alternatives or preconditions — nothing about checking list_customers/get_customer first to avoid duplicates. 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?

Adds real behavior beyond annotations: the hold is temporary and expires after expires_after minutes (default from the organisation setting), and omitting resource_id triggers automatic resource selection restricted by resource_group_ids. That said, it doesn't say what happens if the hold lapses or whether a reservation can be released early, which matters for a non-idempotent write.

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, front-loaded with the mutation marker and the workflow position, then the expiry rule, then the fallback behavior and endpoint. 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 10-parameter write tool with full schema coverage and annotations, the description supplies the missing essentials: workflow position, token/expiry semantics, and the returned reservation id. No output schema is needed since the agent only needs the id to proceed.

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 10 parameters are already documented. The description only restates the resource_id default and the expires_after default (which the schema also states), adding no syntax or interaction detail beyond the structured data. 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 ('hold a date and time for a booking') and immediately anchors it in a workflow ('step 2'), distinguishing it from appointedd_create_booking, which it names as the follow-up. The 'WRITE:' prefix and endpoint POST /availability/slots make the operation type 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?

Explicit sequencing: use this to hold a slot, then call appointedd_create_booking with the returned reservation id, and the start value should come from appointedd_find_available_intervals. It doesn't state when NOT to use it (e.g. when a direct booking is preferable), so it falls short of a full 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so 'Read-only' only restates structured data; the endpoint note POST /availability/days/search adds little. It does clarify the return is day-level availability, but omits behavior like how defaults (resources, duration) affect results 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?

Front-loaded single sentence plus two short supporting fragments; every clause (calendar view, use-intervals-for-times, read-only, endpoint) carries information 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 does convey the shape of the result (which days have availability). Combined with fully documented parameters it is largely complete, though it could mention result caps or empty-result semantics for a 9-parameter search.

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 nine parameters are already documented in the schema; the description adds no parameter-level detail beyond what's there, which is the expected 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 (find) and resource (days with availability) and scopes the return granularity as a calendar view, explicitly contrasting with appointedd_find_available_intervals for times.

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 the sibling alternative appointedd_find_available_intervals and the condition that selects it (when you need times rather than days), so an agent can route correctly without opening either schema.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so "Read-only" is largely redundant; however, disclosing that the endpoint is a POST despite being read-only is genuinely useful, as is describing what comes back (free resource ids per start, plus existing group bookings with room). No mention of result caps or pagination behavior.

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

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

Three short sentences, front-loaded with the outcome and followed by the workflow step and the read-only/POST note. 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 explains the shape of the result and the booking workflow for a 9-parameter search tool. Minor gaps: nothing on how many intervals are returned or whether ranges are searched independently versus merged.

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 ranges, spaces, duration, and timezone is already documented. The description only loosely links the spaces concept via "existing group bookings with room" and adds no format or constraint detail beyond the schema. 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 precise verb and resource — find the start times a service can be booked, returning free resource ids and room-holding group bookings. An agent can tell it apart from most siblings, though the distinction from appointedd_find_available_dates (dates vs. concrete start times) 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?

"Step 1 of making a booking: pick a start, then appointedd_create_reservation" gives explicit workflow context and names the follow-up tool. It stops short of saying when to prefer appointedd_find_available_dates or when not to use this search.

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 only the REST path, with no note on what a lookup for a nonexistent id returns or what fields come back.

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 resource first and no filler. The endpoint path is marginal but harmless for an agent reasoning about REST semantics.

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?

This is a simple one-parameter read with no output schema, so the description should at least hint at the returned customer shape or not-found behavior. Given the tool's low complexity, this is adequate but thin.

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 documents the 24-character hex id format. 'by id' adds nothing beyond it, 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 ('One customer by id') and names the underlying endpoint, so it is identifiable as a single-record fetch. It does not explicitly contrast with appointedd_list_customers, but 'by id' makes the distinction inferable.

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 guidance on when to use this versus appointedd_list_customers (multiple records) or appointedd_update_customer. The only implied precondition is that a customer id must already be 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 and destructiveHint=false, covering the safety profile. The description adds the endpoint path and the returned field set, but does not discuss authentication, rate limits, error behavior, or what happens for expired/missing reservations.

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 with the resource and return fields front-loaded. The endpoint path is useful supporting context and does not bloat the description.

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

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

For a simple read-only lookup with complete schema coverage and no output schema, the description is largely sufficient: it names the lookup key and summarizes the returned fields. It does not cover edge cases such as missing or expired reservations, but no major calling information 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 both parameters are documented in the schema. The description reinforces that lookup is 'by id', but adds no additional semantics for reservation_id or timezone beyond what the schema provides.

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

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

The description clearly identifies the resource (a single reservation/availability slot) and the lookup key (id), and it lists the fields returned: service, resource, times, and expiry. This distinguishes it from siblings like create_reservation and find_available_intervals, though it relies on the title and tool name for the explicit verb.

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 one reservation when you already have its id. There is no explicit guidance on when to use this versus find_available_intervals or list tools, and 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, destructiveHint=false and openWorldHint=true, so safety is covered; the description still adds real value by disclosing which fields come back (questions, durations, prices, buffers), which matters because there is no output schema. It stops short of noting lookup-failure behavior for an unknown id.

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

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

Two sentences, front-loaded with what is returned, then the endpoint path for provenance. Nothing is redundant or padded.

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

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

For a one-parameter read tool with no output schema, listing the returned fields and the endpoint is close to sufficient. Only the not-found case and any id-format expectation from the caller are left unstated.

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

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

Schema description coverage is 100% and the single parameter already documents the 24-character hex id format, so the description adds nothing parameter-level beyond 'by id'. Baseline 3 applies 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?

Names a specific verb and resource ('One service by id') and enumerates the payload it returns (booking questions, durations, prices, buffers). The word 'One' implicitly contrasts with the sibling list_services, though it never names 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?

Usage is only implied: fetch a single service when you have its id. There is no explicit guidance on when to prefer this over appointedd_list_services or appointedd_get_service_category, and no mention of prerequisites such as needing a valid id first.

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 raw endpoint path (GET /services/categories/{category_id}), which adds little behavioral context such as 404 behavior for unknown ids or what the category object contains.

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 terse fragments with no filler, and the resource identity is front-loaded. The endpoint restatement is close to redundant, but the overall length is well matched to a trivial one-parameter tool.

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

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

The tool is simple, its single parameter is fully documented, and annotations cover safety, so the description is not missing anything critical. However, with no output schema, an agent gets no hint about what fields a returned service category contains or how a missing id is signalled.

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 documents the category_id format (24-character hex string). The description's '{category_id}' path placeholder restates the parameter without adding format or validation detail, so the baseline 3 applies.

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

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

The description states a specific resource (a single service category) and the retrieval key (by id), and the singular phrasing implicitly distinguishes it from the sibling list_service_categories. It does not explicitly name that sibling, so it lands just 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?

There is no explicit statement of when to use this tool versus appointedd_list_service_categories or appointedd_get_service. The distinction between fetching one category and listing categories is only implied by the word 'One'.

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. The description adds useful behavioral detail beyond that: default newest-first ordering, pagination via `next`, the endpoint (GET /bookings), and a summary of returned booking fields including customer notes, questions and statuses. It does not cover auth, rate limits or response envelope details.

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, front-loaded with the core action and default order. Every clause carries useful information about filtering, response shape or pagination.

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 describes what each booking contains (service, resource, start/end, status, customers with notes/questions/statuses), which is essential for an agent calling the tool. Pagination and default sort are also covered. Some structured parameter details remain schema-only, appropriately so.

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

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

Schema description coverage is 100%, so the schema already documents all 18 parameters thoroughly. The description groups the filterable dimensions, which is helpful for orientation but adds little specific parameter semantics beyond what the schema provides.

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

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

States a specific verb and resource ('List bookings') and immediately establishes the default ordering ('newest first by default'). No sibling tool competes for booking listing, so the purpose is unmistakable.

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 filtering context across time, customer, service, resource, category, status and creation/update time, plus pagination guidance ('Page with `next`'). It stops short of explicit when-not-to-use or alternative-tool exclusions, but for a general list endpoint the usage is well framed.

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 the pagination behavior via `next` and the underlying GET /customers resource, but says nothing about rate limits, default ordering side effects, or the full response envelope.

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 plus an endpoint tag; the list of returnable fields is front-loaded and useful. 'GET /customers' is marginal but harmless framing.

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

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

With no output schema, the description carries the burden of explaining the return shape; it lists customer attributes and hints at a `next` cursor but omits page-level metadata (totals, `prev`, whether all fields are always present). Adequate but leaves the agent guessing about 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 every parameter is already documented, which sets the baseline at 3. The description adds nothing beyond a vague 'page with `next`' — and it references the response cursor field rather than the `start`/`end` parameter names, so it does not clarify parameter usage.

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

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

States a specific verb and resource ('List customers in the CRM') and enumerates the returned fields, which clearly separates it from the singular get_customer/create_customer siblings. It never names a sibling explicitly, so differentiation is implied 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?

Listing is a fairly self-evident operation, so usage is implied, but there is no guidance on when to prefer get_customer or how to use `ids` to narrow to specific customers. No exclusions or prerequisites 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 the pagination mechanic ('Page with `next`') and the raw endpoint, but does not mention rate limits, ordering behavior, or what an empty result means. With annotations carrying the safety profile, this is adequate but thin.

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, front-loaded sentences with no filler; the returned fields and pagination cue come first. The terse API-path sentence is the only marginal addition, though it does signal REST semantics.

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

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

For a simple read-only list tool with full schema coverage and no output schema, the description covers what is needed to invoke it correctly. It stops short of describing the response envelope (page object, prev/next fields) or when to prefer this over sibling list tools.

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 (end, ids, limit, start, order_by) is already documented in the schema with cursors, ranges, and defaults. The description adds no parameter meaning beyond that, which is acceptable given the rich schema but earns only the 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 resource groups') and names the returned fields (id and name), so an agent knows exactly what comes back. It does not explicitly distinguish itself from the sibling appointedd_list_resources, leaving room for confusion between groups and resources.

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 guidance on when to call this versus appointedd_list_resources or the other list/get siblings, and no mention of prerequisites or filtering tradeoffs (e.g. using `ids` for batch lookup). The agent must infer usage from the name 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, destructiveHint=false, and openWorldHint=true, so the safety profile is clear. The description adds useful behavioral context by noting pagination via `next` and the raw GET endpoint, and it previews returned fields even though no output schema exists.

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

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

The description is two compact sentences, front-loads the core purpose, and contains no filler. The resource definition, returned fields, pagination note, and endpoint are all delivered 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?

The description covers the resource domain, key returned fields, and pagination, and annotations cover the read-only safety profile. Given that there is no output schema, it could say more about the full return shape, but it is otherwise sufficient for an agent to call the tool correctly.

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

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

Schema description coverage is high at 86%, so the input schema already documents most parameters. The description only echoes the pagination behavior ('Page with `next`'), which is already covered by the `start` parameter description, and it adds no extra filtering or sorting 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 gives a specific verb ('List') and resource ('resources'), and it defines the resource as staff members, rooms, or equipment that bookings are made for. It also previews returned fields, which helps distinguish resources from related siblings such as resource groups and services, though it does not explicitly name those alternatives.

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 no explicit guidance on when to use this tool versus alternatives like list_resource_groups or list_services. The usage is only implied by the tool name and endpoint, and there are no exclusions or conditions 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. The description adds the pagination mechanic ('Page with `next`') and the underlying endpoint, which is genuinely useful context but stops short of describing ordering, empty-result behavior, 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?

Three terse fragments, front-loaded with the resource and return fields, then pagination, then endpoint — nothing wasted. The telegraphic style costs a little readability but no sentence is 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 zero-required-parameter read-only list tool with full schema coverage and no output schema, the description covers purpose, returned fields, and paging adequately. Only the routing versus sibling read tools 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 all four parameters (start, end, ids, limit) are already documented in the schema. The description only reinforces the cursor-paging model with 'next'; it adds no syntax, defaults, or filtering semantics beyond that, so baseline 3 applies.

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

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

States a specific verb and resource ('List service categories') and even names the returned fields (id and name), so an agent knows exactly what it gets back. It does not distinguish itself from siblings like get_service_category or list_services, which keeps it short of a 5.

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

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

There is no guidance on when to use this versus get_service_category (single lookup) or list_services, and no mention of prerequisites or exclusions. The read-only listing intent is only implied by the name and endpoint, 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 and destructiveHint=false, so safety is covered. The description adds useful transparency by enumerating the returned service fields and noting pagination via `next`, which matters because there is no output schema. It could say more about filtering, but the core behavior is clear.

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: purpose, returned fields, pagination hint, and endpoint. Every part is relevant, though the raw GET endpoint is slightly redundant.

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

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

For a simple read-only list tool with full schema coverage and annotations, the description covers purpose, returned data, and pagination sufficiently. It does not mention the `ids` filter or default page size, but those are clearly documented in the schema.

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

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

Schema description coverage is 100%, so the schema already fully documents the cursor, ids, and limit parameters. The description only repeats the pagination concept with `next` and does not add format or filtering details 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?

The description states a specific verb and resource ("List services") and clarifies what a service represents ("what can be booked") along with the fields returned (name, category, durations, prices, buffers, occupancy, booking type). It is clear without needing the schema, but it does not explicitly distinguish itself from the single-service sibling `appointedd_get_service`.

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?

Listing is implied by the verb and endpoint, but there is no explicit guidance on when to use this versus `appointedd_get_service` or `appointedd_list_service_categories`. 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?

Adds real context beyond annotations: the notification default here differs from the API's own default (send_notifications defaults false in this wrapper), and it flags that moving triggers an availability check. Annotations already declare destructiveHint/idempotentHint, so the remaining gap is mainly about failure modes when availability checks fail.

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

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

Three short sentences, front-loaded with the WRITE marker, the mutable field list, the notification caveat, and the endpoint. 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?

A 9-parameter mutation tool with no output schema gets a clear action summary, the notification behavior, and the availability-check side effect. It doesn't describe what happens when the availability check fails or what the response body returns, which would complete the picture.

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%, so the baseline sits at 3; the description goes slightly beyond by grouping parameters into intents (service/resource/label/spaces edits vs a time move via `parts`) and highlighting the notification-default divergence. It largely echoes what the schema already documents for service_id, resource_id, parts, and send_notifications.

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 'WRITE:' marker and a specific verb+resource ('change a booking's service, resource, label or total spaces'), then enumerates the move case via `parts`. This distinguishes it cleanly from create_booking, cancel_booking, and update_booking_customer.

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 field list makes the tool's scope clear (editing vs cancelling vs creating), and mentioning `parts` for relocation tells the agent which parameter selects the reschedule behavior. It stops short of explicitly naming alternatives such as cancel_booking for removal or update_booking_customer for the customer link.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, idempotentHint=true and openWorldHint=true; the description's main contribution is the 'WRITE:' prefix plus the notes-replacement semantics, which largely restate the schema. It does not explain the destructive aspect (overwriting existing notes), whether omitted fields are left untouched, or what is returned – gaps the annotations alone cannot fill.

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 with the 'WRITE:' safety signal and the resource scope front-loaded, then identifier semantics, then the endpoint. The parenthetical re-listing of the four status values is mildly redundant with the schema enum.

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 small 4-parameter mutation with no output schema, the description covers the operation, the identifier source, and the endpoint. What remains unstated – return payload and behavior of omitted fields – is minor but not trivial for a destructive, idempotent write.

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 75%, so the baseline is 3. The description explains customer_booking_id and enumerates the status values, but both facts are already in the schema and enum, so it adds no new semantics beyond structured fields.

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: set the arrival status and/or notes of one customer on a booking, and gives the exact endpoint PUT /bookings/{booking_id}/customers/{customer_booking_id}. The scoping phrase 'one customer on a booking' lets an agent separate it from the broader update_booking and the global update_customer siblings.

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

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

'set the arrival status ... and/or notes' clearly frames this as a partial update where at least one field is supplied, and the endpoint anchors it to a booking-scoped customer record. There is no explicit when-not-to-use note (e.g. 'use update_customer for the customer's global record'), so routing to the closest sibling still needs inference.

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

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

Annotations already declare the mutation profile (readOnlyHint=false, destructiveHint=true, idempotentHint=true), so the bar is lower; the description nonetheless earns credit by making the destruction concrete ('`tags` replaces the customer's tag list') and by disclosing PATCH-style semantics ('only the fields you pass are sent'). It stops short of stating auth/permission requirements or whether omitted fields are ever cleared server-side.

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 mutation marker front-loaded, then the partial-update rule, then the tag-replacement caveat and endpoint. No filler; every clause carries information an agent needs before calling.

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 destructive write with no output schema, the description covers the essentials: what mutates, partial-update behavior, tags replacement, and the underlying endpoint. Remaining gaps are modest — no return/response description and no statement of failure conditions for a nonexistent customer_id or invalid email/phone.

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

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

Schema description coverage is only 29% (just tags and customer_id documented), so the description has to carry weight. It does name the updatable fields and clarifies the replace-not-append behavior of tags, but it collapses firstname/lastname into an ambiguous 'name' and adds no format or constraint detail for email, mobile, or phone beyond what the schema already enforces.

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?

It names a specific verb ('change') plus the resource ('a customer') and enumerates the mutable fields, and the 'WRITE:' prefix plus the PUT endpoint makes the operation type unambiguous against read siblings like get_customer or list_customers. The 'name' shorthand is slightly loose versus the schema's firstname/lastname split, but the agent still identifies the operation immediately.

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: 'change a customer's name...' tells you this is the edit path, and PUT /customers/{customer_id} signals an existing-resource update, which implicitly routes create_customer elsewhere. But there is no explicit when-to-use/when-not guidance, no mention that the customer must already exist, and no reference to update_booking_customer or other update siblings.

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