YouCanBook.me MCP by usefulapi

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

Annotations only flag destructiveHint=true; the description adds that the change is reversible, how to reverse it, and what is returned ('the updated booking'). That is meaningful context beyond the annotation, though it doesn't cover side effects like notifications sent to the booker.

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 chain with the mutation warning front-loaded, followed by implementation, safety, reversal path, and return value. 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 mutation with no output schema, the description covers effect, mechanism, reversibility, alternative, and return value. 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?

Only one parameter and schema coverage is 100% — the schema already documents bookingId as a required path id. The description adds no format, example, or lookup guidance beyond that, so this sits at the baseline for fully-covered 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 and resource ('cancels a booking') and immediately identifies the underlying operation (PATCH /v1/bookings/{bookingId} with { cancelled: true }). The contrast with deleting makes it distinguishable from update_booking and any delete sibling.

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

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

Explicitly frames this as the safer alternative to deleting and names the reversal path (youcanbookme_update_booking with cancelled=false). What's slightly left implicit is when an agent should pick this over calling update_booking with cancelled=true directly, since the description admits they are the same operation.

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 destructiveHint=true; the description adds real value beyond that by naming the exact endpoint (POST /v1/profiles/{profileId}/appointmenttypes/items) and clarifying that profileId is a path parameter never sent in the body. It stops short of explaining irreversibility or side effects on existing appointment types.

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-loads the MUTATES warning, then endpoint, then required/path-vs-body rules in tight clauses. Every sentence carries operational 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?

For a 3-param mutation with a nested passthrough object and no output schema, the description covers endpoint, required fields, path/body split, and the passthrough escape hatch. Missing only guidance on where profileId values come from (e.g., list_profiles) and return shape.

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

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

Schema coverage is already 100%, so baseline is 3, but the description adds meaning: it specifies `name` as required, explains that `fields` is a passthrough for description/slotLength/price, and reiterates that profileId is path-only. This is useful value beyond the schema.

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

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

States a specific verb and resource: 'adds an appointment type to a profile'. The resource is unambiguous and distinguishable from sibling mutations like create_booking or create_location, though it doesn't explicitly contrast with update_appointment_type.

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 MUTATES warning and required-field note give creation context, and it hints at using `fields` for extras, but it never states when to choose this over update_appointment_type or which sibling handles listing/inspecting profiles first. Usage is implied rather than guided.

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

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

The description's 'MUTATES' warning is consistent with destructiveHint=true and adds the concrete write endpoint and expected return value, which annotations do not cover. It omits meaningful side effects an agent would want to know — slot-availability conflicts, attendee notification emails, and uniqueness/duplicate handling.

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 that front-load the mutation warning, then required fields, then the passthrough escape hatch. No filler and nothing buried at the end.

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

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

For a mutation tool with no output schema, it does the right things: states the return value, the transport, and the required/optional split. The remaining gap is failure behavior — what happens when the requested slot is taken, or whether the call is idempotent — which matters for a booking-creation 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 coverage is 100%, so the baseline is 3; every parameter already has a description. The one genuine addition is routing complex payloads (`answers`, `linkFields`) through the `fields` passthrough, which is not evident from the schema's generic merge wording. Everything else (ISO 8601, IANA time zone) merely repeats the schema.

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

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

States a specific verb and resource ('creates a booking (appointment) on a profile') plus the exact API route POST /v1/bookings. This is unambiguously distinguishable from siblings like create_appointment_type, update_booking, or cancel_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 'MUTATES ... creates' framing and the explicit required-field list give a clear precondition for invoking it. It never names alternatives (e.g. use update_booking to modify an existing booking, or list_bookings to check for conflicts), so it stops short of full when/when-not 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?

The description explicitly labels the operation as a mutation and provides the concrete API endpoint POST /v1/profiles/{profileId}/locations, which adds useful context beyond the destructiveHint annotation. It does not describe permissions, response behavior, or any irreversibility details, but annotations already cover the safety profile.

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-loads the mutation warning and purpose. Each sentence carries practical information: endpoint, required fields, passthrough usage, and path-body separation.

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 rich schema coverage and a destructiveHint annotation, the description gives enough to call it correctly, including required fields and body/path handling. It does not state what the API returns or describe side effects beyond mutation, but no output schema exists and the core invocation guidance is present.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful semantics: it reiterates required kind and strategy, explains how fields is used for value/notes/other documented fields, and clarifies that profileId is path-only and not sent in the body.

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: it adds a location to a YouCanBookMe profile. It is clearly distinguishable from sibling read/list tools such as list_locations and from booking/team-member creation tools.

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

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

The context is clear: this is the creation/mutation path for a profile location, and it names the required fields. It does not explicitly route against alternatives like list_locations for checking existing locations, so it stops short of full when/when-not 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?

The annotations only flag destructiveHint=true; the description adds real value by leading with 'MUTATES YouCanBookMe data', naming the HTTP method/path, and clarifying that profileId travels in the path and is never placed in the body — a non-obvious behavioral detail. It stops short of covering failure modes or what the mutation returns.

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-loads the mutation warning and endpoint, then required fields, then the passthrough tip. Every clause carries information; nothing is padding despite the terse telegraphic style.

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 create tool with annotations present and a nested `fields` object, the description covers endpoint, required inputs, path-vs-body separation, and the passthrough escape hatch. With no output schema, one more line on what is returned (e.g., the created member id) would make it complete.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds the merge semantics hint and concrete examples of which attributes belong in the `fields` passthrough (email, description, pic), helping an agent decide between typed params and the escape hatch.

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 ('adds a team member to a profile') and even gives the underlying endpoint POST /v1/profiles/{profileId}/teammembers/items, which unambiguously separates it from youcanbookme_update_team_member and youcanbookme_list_team_members.

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 concrete routing guidance by pointing at youcanbookme_list_available_accounts for obtaining a calendarId, and tells the agent to use `fields` for non-typed attributes. It never explicitly contrasts with youcanbookme_update_team_member, so the create-vs-update choice is only implied by the verb.

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?

readOnlyHint=true is consistent with a fetch operation, so no contradiction. The description adds the endpoint path and states that the booking object is returned, but says nothing about not-found behavior, permission requirements, or whether `fields` filtering affects nested objects.

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 purpose before the endpoint and parameter hint. Every sentence carries information; only the trailing 'Returns the booking object' is near-redundant given the name.

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

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

For a two-parameter read-only getter with full schema coverage and an annotation declaring its safety profile, little else is required. The absence of output schema is noted but the description signals the return type adequately for this complexity level.

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 schema already explains both bookingId and the comma-separated/dotted-path semantics of `fields`. The description only echoes that `fields` selects which fields to return, adding no syntax or edge-case detail beyond the schema.

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

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

Specific verb and resource ('Fetch a single booking by id') plus the underlying endpoint, which makes the single-record scope clear enough to distinguish it from youcanbookme_list_bookings. It stops short of naming the sibling explicitly, leaving the distinction implied by 'single' and 'by id'.

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

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

The lookup condition (having a booking id) is implied by the required parameter and the phrase 'by id', but there is no explicit statement of when to prefer this over list_bookings or what to do when the id is unknown. 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, so safety is covered; the description adds the concrete API call and states what comes back ('Returns the profile object'). It does not cover error behavior when the id is unknown, but for a simple read that is a minor gap.

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

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

Four short sentences, front-loaded with the verb, resource and identifier, then the endpoint, then the fields behavior and return value. Nothing is redundant and every sentence carries information.

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

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

With only two well-documented parameters and no output schema, the description covers the essentials, including the return value that would otherwise be missing. Slightly short on how missing/invalid ids behave, but adequate for a simple read tool.

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

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

Schema coverage is 100%, so baseline is 3, but the description earns a bump by naming the nested sub-resources selectable via `fields` (appointmentTypes, teamMembers, locations) — information the schema's generic 'dotted paths' note 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 and resource ('Fetch a single profile (booking page) by id') and pins the scope to a single record, which cleanly separates it from youcanbookme_list_profiles. It even names the underlying endpoint, leaving no ambiguity about what the tool does.

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 'single ... by id' phrasing implies the use case relative to list_profiles, and mentioning `fields` hints at sparse-fetch usage. However, there is no explicit when-to-use/when-not or comparison to siblings like list_profiles or youcanbookme_request.

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?

readOnlyHint already declares the read-only nature, and the description adds real value on top: the underlying GET endpoint, the fact it uses a field selection, and the shape of the returned appointmentTypes block. It stops short of noting behavior for missing/empty profiles or whether results are paginated.

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

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

Three short sentences, front-loaded with the purpose, then endpoint and return shape. 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 annotations and full schema coverage, the description covers purpose, data source, and return contents. No output schema exists, yet the agent still knows what to expect back.

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

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

Schema coverage is 100% with a single required profileId that the schema already documents as the profile (booking page) id. The description restates the same meaning without adding format or sourcing detail, 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 the appointment types configured on a profile'), plus the exact API endpoint and returned fields. It is clearly distinguishable from sibling mutators like create_appointment_type and update_appointment_type.

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: call it when you need the appointment types for a known profileId. There is no explicit guidance on when to prefer a sibling (e.g., get_profile) or what to do if the profile has none, 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?

The readOnlyHint already establishes that this is a safe read operation. The description adds useful context beyond the annotation by naming the API endpoint, explaining that accountId comes from configured credentials, and stating the return type is a JSON array.

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, starting with what the tool lists and its primary use case. The endpoint and return information follow without unnecessary detail.

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-parameter, read-only list tool with annotation coverage, the description is complete enough to call correctly. It explains the purpose, credential-derived accountId, endpoint, and that the result is a JSON array.

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

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

There are zero input parameters, so the schema baseline is 4. The description adds a relevant clarification that accountId is taken from configured credentials rather than supplied as a parameter.

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

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

The description uses a specific verb and resource: 'List the accounts/calendars available to your account.' It also states the concrete purpose, finding the calendarId for a team member, which distinguishes it from sibling tools such as list_profiles or list_team_members.

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

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

It gives a clear usage context: the tool is 'used to find the calendarId for a team member.' However, it does not explicitly state when not to use it or name an alternative tool for obtaining that information.

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, so the safety profile is covered. The description adds real value beyond that: 10-per-page limits, cursor-based pagination (not page numbers), and the two distinct cursor param sets for filtered vs unfiltered reads.

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-loads the core purpose, then layers endpoint/pagination detail in a compact block. Dense but every sentence carries operational meaning; only slightly crowded with endpoint notation.

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 closes the gap by stating it 'Returns a JSON array of bookings' and explains both pagination schemes. Complete enough to call correctly; the only minor gap is not covering the fields parameter behavior explicitly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds cross-parameter meaning the schema lacks: after is required for filtered reads, maxResults is 10-500, and params carries direction/boundaryStartsAt/boundaryId or fromBookingId depending on mode.

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 on your account') and draws a clear line between unfiltered and filtered reads. It does not explicitly differentiate from siblings like get_booking or list_profiles, 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?

Gives explicit conditions selecting the unfiltered read (GET /v1/{accountId}/bookings) versus the filtered query ('supply after as the required start of the time range'). Clear context for choosing between the two modes, though it never mentions when to prefer get_booking for a single record.

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, so the safety profile is covered. The description adds genuine context beyond that: the exact API call (GET /v1/profiles/{profileId} with a locations field selection) and the shape of the returned block, including per-location fields (id, kind, value, notes, strategy).

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 purpose, then implementation detail, then return shape. No filler and nothing misplaced.

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 compensates by naming the returned fields explicitly. For a single-parameter read-only tool this covers everything an agent needs to select and 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?

Single parameter at 100% schema coverage, so the baseline is 4. The description's parenthetical '(booking page)' reinforces what profileId means, matching the schema's own clarification without adding confusion.

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 scoped resource (locations configured on a profile/booking page), and names the underlying API endpoint. It is clearly distinguishable from create_location and get_profile, which the agent can tell apart without opening the schema.

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

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

The read/list framing implies when to use it, and it is implicitly the sibling to create_location, but the description never states explicit conditions, prerequisites, or when to prefer get_profile instead. 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?

readOnlyHint=true already covers the safety profile, so the description's value-add is pagination semantics, the field-selection mechanism, and the return shape ('Returns a JSON array of profiles'). It omits the API's default page size and whether a `params` passthrough is ever needed, but the behavioral picture is solid for a read-only list.

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

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

Front-loaded with the verb and resource, then the endpoint, then the domain definition, then usage hints — a sensible order with no filler. Mild redundancy against the schema (the `fields` example appears twice) keeps it from a 5.

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

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

With no output schema, the description carries the return-value burden and does so ('Returns a JSON array of profiles'), plus it covers pagination and field selection. The only gap is the undocumented `params` escape hatch for arbitrary query filters.

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 are already documented in the schema. The description repeats the 0-based `page` + `maxResults` pairing and the `fields` example, adding only marginal clarity and nothing on the `params` filter object. 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 all profiles (booking pages) on the account') and even defines what a profile is — a bookable page with its own subdomain, appointment types, team members, and locations. The 'list all' scope makes it trivially distinguishable from the singular youcanbookme_get_profile sibling.

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

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

Explains how to shape the response ('Use `fields` to select fields') and how to page through results, which is clear actionable context. It never explicitly contrasts itself with get_profile or list_bookings, so routing guidance is implied by scope 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, so the safety profile is covered; the description adds value beyond that by disclosing the underlying API call (GET /v1/profiles/{profileId} with a teamMembers field selection) and enumerating the returned member fields (id, name, email, description, pic, calendarId), which matters because there is no output schema. It stops short of noting pagination, empty-list behavior, or auth requirements.

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

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

Three short sentences, front-loaded with the action and scope, followed by the API detail and the return payload. Every sentence earns its place, with no filler or restatement of the tool name.

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

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

For a single-parameter read tool with no output schema, the description supplies the missing return-shape information and the underlying endpoint, and the readOnly annotation covers safety. Minor gaps remain around pagination and error/empty behavior, but nothing needed to invoke it correctly is absent.

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

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

There is a single parameter with 100% schema description coverage, so the schema already carries the semantics. The description reinforces that profileId refers to the profile/booking page but adds no format, sourcing, or retrieval guidance 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 (List) and resource (team members configured on a profile), and disambiguates 'profile' as the booking page, which separates it from list_profiles and from the create/update_team_member siblings. It also names the exact endpoint used and the fields returned, leaving no ambiguity about what is retrieved.

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

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

Usage is only implied by the scope statement: you use it when you need the team members of a given profile. There is no explicit when-to-use vs. alternative guidance (e.g., get_profile vs. this call, or how it relates to list_profiles), and no prerequisites 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 the description corroborates with READ-ONLY / only-GET. Beyond that it adds real context: the FULL path including query string must be passed, and the return is parsed JSON. It omits error behavior for invalid paths and rate limits, so not a full 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 compact sentences, front-loading the escape-hatch purpose, then the read-only constraint, then the path format and return. Zero filler; every clause carries information.

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

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

No output schema exists, but the description covers the return ('parsed JSON') and the calling format, and the read-only profile is stated. What an agent might still need — error responses for malformed paths or undocumented endpoints — is absent, keeping it just short of complete.

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

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

Schema coverage is 100% and the single parameter description already states the full-path-after-origin format, so the description largely restates it. It reinforces with a second example and the 'INCLUDING any query string' emphasis, but adds no syntax the schema lacks. Baseline 3 is 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 (GET) and resource (any YCBM API path not wrapped by a dedicated tool), and explicitly frames itself as the escape hatch relative to the wrapped siblings like list_bookings or get_profile. An agent can tell immediately this is a raw passthrough, not another wrapped endpoint.

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?

"Any YCBM API path not wrapped by a dedicated tool" gives an explicit selection condition, and "only GET is allowed" excludes write usage. It does not name any sibling as the preferred alternative ('if you need bookings, use list_bookings'), so the routing is inferable rather than 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?

The description reinforces the mutating nature with 'MUTATES' and the PATCH endpoint, and adds useful implementation context: partial update semantics, path IDs not being sent in the body, and fields being passed through. The destructiveHint annotation already covers the safety profile, and the description adds meaningful operational detail without contradicting it.

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, starting with the mutation warning and then providing endpoint and parameter guidance. Every sentence contributes useful information without 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 mutation tool with full schema coverage and no output schema, the description provides enough context for correct invocation: endpoint shape, partial-update behavior, field passthrough usage, and path ID handling.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by giving examples of supported fields (`name`, `description`, `slotLength`, `price`) inside the generic `fields` passthrough and by clarifying that path IDs are not part of the body.

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: updates an appointment type on a profile. It distinguishes the tool from siblings like create_appointment_type and update_profile by naming the exact resource and operation.

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

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

It clearly establishes that this is a partial-update operation for an existing appointment type and instructs the agent to send changed fields through `fields`. It does not explicitly name alternatives or when not to use it, but the update context is clear.

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

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

Annotations supply only destructiveHint=true; the description earns credit by disclosing partial-update semantics (PATCH, unspecified fields preserved), which materially reduces the risk of accidental data loss on a destructive tool. It stops short of noting permission/auth requirements, whether cancelling is reversible via this same call, or any 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 sentences, zero filler, and the most important signal (MUTATES) is the very first word. The endpoint/body-format notes and the fields-passthrough hint follow in descending order of importance.

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 destructive mutation with no output schema, the description covers what changes, how (partial PATCH), where the id goes, and how to pass undocumented fields. The remaining gap is sibling routing versus youcanbookme_cancel_booking and the absence of any success/return indication.

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

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

Schema coverage is 100%, so baseline is 3; the description mostly restates schema property names (title/startsAt/endsAt/cancelled/noShow/timeZone/locale/units). The one genuinely additive note is that the path id is never sent in the body, plus the reminder that `fields` is merged over the typed fields — though the schema already says that for `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?

Opens with a specific verb and resource ("MUTATES ... updates an existing booking") and enumerates the concrete intents: reschedule, rename, mark cancelled/no-show. That is enough for an agent to separate it from youcanbookme_create_booking, youcanbookme_get_booking and youcanbookme_list_bookings without opening a schema.

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

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

Gives real operating context: it is a PATCH partial update, so only supplied fields change, and the `fields` passthrough is the escape hatch for answers/linkFields or other documented fields. It does not, however, route the agent against the overlapping sibling youcanbookme_cancel_booking (which this tool can also do via cancelled=true) or state when not to use it.

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 only supply destructiveHint=true; the description adds real context: the underlying endpoint (PATCH /v1/profiles/{profileId}), that the update is partial and JSON-based, that fields use YCBM's own names, and that the path id must not appear in the body. It stops short of warning what a bad write could break (e.g. changing subdomain invalidating booking links), 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, front-loaded with the mutation warning and the resource, then the endpoint and the parameter contract. 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?

For a two-parameter destructive mutation with no output schema and an open-ended passthrough object, the description covers endpoint, partial-update semantics, and field naming conventions adequately. It omits any note on consequences of changes or what the response returns, but the essential calling information is present.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds value the schema doesn't: profile fields are numerous and must use YCBM's native names, and the path id is path-only and never sent in the body. That clarifies the otherwise opaque free-form `fields` passthrough.

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 ('MUTATES ... updates a profile's (booking page) configuration') and flags the operation class with a leading MUTATES marker. An agent can distinguish it from youcanbookme_get_profile and the other update_* siblings without opening the schema.

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

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

Makes clear this is a partial update of an existing profile via PATCH, which implicitly routes against the create and get siblings. It does not state explicit exclusions or prerequisites (e.g. permissions), so it falls short of a 5.

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

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

Annotations only declare destructiveHint=true; the description adds real value by flagging 'MUTATES', confirming partial-update semantics (unchanged fields preserved), and warning that path ids are never sent in the body. It doesn't state permission requirements or reversibility, keeping it below 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, front-loaded with 'MUTATES', zero filler. Each clause (endpoint, partial-update fields, path-id rule) carries distinct information.

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

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

For a 3-param destructive mutation with no output schema, the description covers the mutation semantics, endpoint, and body construction well. It could note that unspecified fields are left untouched and what a success response looks like, but it is broadly complete.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds meaningful semantics: the `fields` passthrough is a partial-update body merged over typed fields, and profileId/teamMemberId are path-only and never serialized into the body.

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

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

States the specific verb and resource ('updates a team member on a profile') and grounds it with the exact API endpoint PATCH /v1/profiles/{profileId}/teammembers/items/{teamMemberId}, clearly distinguishing it from create_team_member and list_team_members.

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 'partial update' note and 'pass changed fields' instruction tell the agent when this tool is appropriate versus a full create. It stops short of explicitly naming the alternative (e.g., create_team_member for new members), but the context is clear.

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