youcanbookme

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

Annotations only mark destructiveHint=true, but the description goes further by stating the mutation effect, the underlying PATCH operation, reversibility, and that it returns the updated booking. This gives the agent accurate expectations beyond the annotation.

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 deliver the mutation warning, purpose, endpoint equivalence, reversibility, and return value with no filler. The key action is front-loaded before implementation details.

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 mutation with no output schema, this description covers the effect, mechanism, reversibility, return value, and safety posture. Nothing essential is missing for an agent to select and invoke 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?

The input schema already fully documents bookingId with 100% coverage, including that it is a required path parameter. The description reinforces the endpoint but does not add new parameter-level meaning, so 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: 'cancels a booking' on YouCanBookMe data. It also clarifies it is a convenience wrapper for PATCH /v1/bookings/{bookingId} with { cancelled: true }, distinguishing it from both deletion and the broader update_booking tool.

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

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

The description gives clear usage context: it is the safer, reversible alternative to deleting, and explicitly points to 'update_booking cancelled=false' for reactivation. It does not explicitly enumerate when not to use it, but the wrapper explanation and sibling reference provide solid 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 reinforces the destructiveHint annotation with an explicit 'MUTATES' label and goes beyond the annotation by explaining the path/body distinction and how extra fields flow through the `fields` passthrough. It does not discuss reversibility or auth, but the annotation already flags the destructive nature.

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

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

Three dense, purposeful sentences with no filler. The mutation warning and core action lead, followed by the endpoint and the critical caveat about `profileId`, making the description easy to scan and act on.

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

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

For a destructive creation tool with nested fields and no output schema, the description covers the essential invocation details: endpoint, required fields, passthrough behavior, and path/body split. It omits return-value behavior, but that is a minor gap given the tool's simple creation purpose and absent output schema.

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

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

The schema already documents all parameters, so the baseline is 3. The description adds practical value by marking `name` as required, naming example passthrough fields like description/slotLength/price, and clarifying that `profileId` is path-only and never 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 an appointment type to a profile' and even gives the exact API endpoint. This clearly separates it from siblings like update_appointment_type and list_appointment_types.

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: use this tool when creating a new appointment type for a profile. The POST verb and 'adds' make the creation semantics obvious, though it does not explicitly call out alternative tools or exclusion conditions, so it stops 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?

The annotations only provide destructiveHint=true, and the description adds useful behavioral context: it creates persistent data via a POST request, requires ISO 8601 times, passes complex fields through the fields passthrough, and returns the created booking. It does not mention possible side effects like confirmation emails, but the disclosure is still strong beyond the annotation.

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 dense, front-loaded sentences with no filler. It opens with the mutation warning, then provides API endpoint, required and optional parameters, complex-field guidance, and return behavior — every sentence earns its place.

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

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

For a mutation tool with no output schema, the description covers required inputs, optional inputs, the non-obvious fields passthrough, and the return value. It is complete enough for an agent to make a correct call, though it could be slightly richer on what side effects to expect beyond 'creates a booking.'

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

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

The schema already documents 100% of parameters, so the description's extra grouping of required and optional parameters is helpful but not strictly necessary. It adds real value by explaining the fields passthrough for complex fields like answers and linkFields, which the schema alone does not clarify semantically.

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 action and resource: it creates a booking (appointment) on a profile and names the exact API endpoint, POST /v1/bookings. This clearly separates it from siblings like create_appointment_type, create_location, or update_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?

It gives clear usage context by marking the operation as MUTATES, listing required vs optional fields, and explaining how complex fields like answers and linkFields should be passed. It does not explicitly call out alternatives such as update_booking or cancel_booking, so the guidance is clear 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?

The description adds substantial behavioral detail beyond the destructiveHint annotation: it declares the operation as a mutation, specifies the YCBM API endpoint and JSON body, notes required fields, explains the fields passthrough behavior, and clarifies that profileId is path-only. This is exactly the kind of context that helps an agent invoke the tool correctly.

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

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

Three dense sentences, each earning its place. The mutation warning and core action are front-loaded, followed by endpoint details, required params, and the path-vs-body caveat. No filler or repetition of schema prose.

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

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

For a create tool with no output schema and no enum constraints, the description covers endpoint, required fields, and body semantics well. It does not describe the response shape or error conditions, but those are not essential for selecting and invoking the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by highlighting that fields can carry value and notes, and by explicitly warning that profileId is never sent in the body, which is not obvious from the schema alone.

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

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

The description states a specific verb and resource: "adds a location to a profile." It clearly distinguishes this from sibling tools like create_booking or create_team_member by naming the exact entity being created.

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

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

Usage context is implied rather than explicit: the tool is for adding a location, and required fields are noted. However, it does not explicitly contrast with alternatives such as list_locations or create_appointment_type, nor does it state when not to use this tool.

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 says 'MUTATES YouCanBookMe data,' matching and reinforcing the destructiveHint annotation. It also adds useful behavior beyond annotations: the HTTP method/endpoint and that profileId is path-only and never sent in the body.

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

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

Three dense sentences provide the mutation warning, endpoint, required parameter, calendar lookup hint, passthrough usage, and path/body distinction with no filler. The most important constraint is front-loaded.

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

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

The description covers the call pattern, required inputs, calendar linkage, and the fields passthrough mechanism. Since there is no output schema, it could mention what the response contains, but for a straightforward create operation the provided detail is sufficient for an agent 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?

Schema coverage is already 100%, so the baseline is 3. The description adds value by explaining that name is required, that calendarId links to a calendar discoverable via list_available_accounts, and that fields is a passthrough for email, description, pic, and similar properties.

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 states the verb and resource: 'adds a team member to a profile,' and cites the exact YCBM POST endpoint. This distinguishes it from siblings like list_team_members and update_team_member.

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 clear context for using the tool, including that calendarId should be found via list_available_accounts. It does not explicitly state when not to use it or contrast with update_team_member, so it stops just short of full routing guidance.

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

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 the GET endpoint and the return type ('booking object'), which is useful but does not cover auth, error behavior, or default field set 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?

The description is compact and front-loaded with the primary action. The endpoint reference and fields guidance earn their place, though the phrase 'booking object' adds only mild additional value.

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

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

For a simple two-parameter read operation with full schema coverage and a readOnlyHint, the description is sufficient for correct invocation. It states what is returned and how to narrow fields; the lack of an output schema is partially mitigated by the explicit 'returns the booking object' statement.

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 bookingId and fields are already well documented. The description reinforces that fields controls returned fields but adds no meaning beyond the schema.

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

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

The description states a specific verb ('Fetch'), a specific resource ('a single booking'), and the key qualifier ('by id'). This clearly distinguishes it from list_bookings, which retrieves multiple bookings, and from create/update/cancel variants.

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 provides clear context: use this tool when you need a single booking by its ID. It does not explicitly name alternatives or exclusions, but the singular 'by id' framing implies the right condition for selection.

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

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

The readOnlyHint annotation already establishes that this is a safe read operation. The description adds meaningful behavioral context beyond that: the exact API endpoint, the ability to select fields including nested sub-resources, and the fact that it returns the profile object.

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

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

Three short sentences, each earning its place: the core purpose, the API endpoint, and the parameter behavior. The most important information is front-loaded, and there is no redundancy.

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

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

For a simple read-by-id tool with one required parameter and full schema coverage, the description covers purpose, endpoint, parameter use, and return value. There is no output schema, but 'Returns the profile object' adequately addresses the return expectation.

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 naming concrete nested sub-resources (appointmentTypes, teamMembers, locations) that the schema does not list, giving the agent a clearer picture of what the fields parameter can express.

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 explicitly states 'Fetch a single profile (booking page) by id,' giving a specific verb, resource, and scope. This clearly distinguishes it from list_profiles and other sibling tools that operate on collections or different 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?

The description gives clear context: use this when fetching one profile by id. It does not explicitly name list_profiles as the alternative for fetching multiple profiles, but the single-by-id framing makes the usage boundary obvious.

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 adds useful behavioral detail beyond the readOnlyHint annotation by specifying the underlying GET endpoint, the field selection on the profile resource, and the shape of the returned appointmentTypes block. This gives the agent a concrete model of the API call and response without needing an output schema.

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

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

The description is compact and front-loaded: the first sentence states the action and resource, and the second provides the API endpoint and return fields. Every sentence earns its place with no redundant wording.

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 read-only list tool, the description is complete. It explains what the tool returns, names the API endpoint, and lists the relevant fields, so an agent has enough context to invoke it correctly without an output schema.

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

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

With 100% schema description coverage, the single parameter profileId is already documented as 'The profile (booking page) id.' The description adds no significant new parameter semantics, only restating the profile context already present in 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 uses the specific verb 'List' with the resource 'appointment types configured on a profile (booking page)', making the tool's purpose immediately clear. It also cites the exact YCBM API endpoint, which helps distinguish it from related tools like get_profile or create_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 description clearly implies when to use the tool: whenever the agent needs the appointment types configured on a specific profile. It does not explicitly name alternatives or exclusion cases, but the scope is specific enough that an agent can reliably select it over the listed sibling tools.

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 annotation already signals a safe read operation. The description adds meaningful context beyond that: it specifies the HTTP method and path, notes that accountId comes from configured credentials, and states the return type (JSON array). This gives the agent a good understanding of the tool's behavior without needing to inspect the API.

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 sentences, with the core purpose and usage intent front-loaded, followed by the API endpoint and return format. Every word contributes value; there is no redundancy or 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 parameterless, read-only tool, the description covers the essential details: what it lists, why it is used, the endpoint, and the return type. It does not specify the exact fields in the returned array (e.g., 'calendarId', 'name'), but the stated purpose strongly implies the array contains the needed calendarId. This is adequate but could be slightly more explicit.

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

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

The tool has zero input parameters, and the description appropriately clarifies that accountId is taken from configured credentials rather than being an input. With no parameters to document, the baseline of 4 applies and the description does not need further elaboration.

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 states the action ('List'), the resource ('accounts/calendars'), and the purpose ('find the calendarId for a team member'). It also identifies the API endpoint, leaving no ambiguity about what the tool does or how it differs from sibling tools like 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 description provides a clear use case: to retrieve available accounts/calendars when you need to find a calendarId for a team member. It does not explicitly mention alternative tools or when not to use it, but the stated purpose gives sufficient context for an agent to decide.

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 provide readOnlyHint=true, and the description adds read-only behavioral context: the GET method, endpoint, optional filter semantics, pagination model, and JSON array return. It does not cover auth or rate limits, but those are less critical given the read-only annotation.

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 with the core action, then efficiently packs endpoint, filter capabilities, pagination, field selection, and return format into a few clauses. Every sentence and clause contributes useful information without filler or redundancy.

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

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

For a read-only listing tool with no output schema, the description covers the endpoint, filtering semantics, pagination, field selection, and return format. All parameters are individually documented in the schema, so nothing essential is missing for correct invocation.

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 input schema already documents all nine parameters thoroughly. The description summarizes which filters exist and notes that page is 0-based, but it adds little semantic value beyond what the schema provides, so the baseline score 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 ('List') and resource ('bookings/appointments on the YouCanBookMe account'), identifies the underlying GET endpoint, and describes the return value as a JSON array. This clearly distinguishes it from single-booking get_booking and mutation siblings like create_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 description establishes clear usage context: retrieve multiple bookings with optional filters, pagination, and field selection. It does not explicitly name alternatives or say when not to use this tool, but the list-vs-get distinction is strongly implied by the name and the statement that it returns a JSON array of bookings.

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 discloses that this is a GET request, which aligns with the readOnlyHint annotation. It also adds useful behavioral context by specifying the field selection and the structure of the returned locations block, going beyond what the annotation alone provides.

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 with the main purpose, then adds the API path and return shape. Every sentence contributes useful information without redundancy.

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

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

For a simple one-parameter read-only tool with no output schema, the description is complete: it states the API call, the parameter context, and the exact returned fields. Nothing critical is missing for an agent 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?

The schema already fully documents the single parameter profileId with a clear description. The tool description does not add much beyond restating that profileId references the booking page, so a baseline score of 3 is appropriate due to the 100% schema coverage.

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

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

The description clearly states the specific action ('List the locations configured on a profile') and the resource scope ('booking page'), and even names the exact API endpoint. This makes it easy to distinguish from sibling tools like 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?

The description provides clear context: use this tool to retrieve locations associated with a specific profile. It does not explicitly name alternatives or exclusion conditions, but the scope is unambiguous enough for an agent to select it appropriately.

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=true annotation already signals a safe read operation; the description adds value by disclosing the exact endpoint (GET /v1/profiles), that it returns a JSON array of profiles, and that it is paginated via page + maxResults. No rate-limit or error-shape details are provided, but the core behavior is well covered.

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 four focused sentences: purpose, API endpoint, domain definition, and pagination/fields/return behavior. No filler; each sentence contributes useful information, and the most important purpose statement is front-loaded.

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

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

For a read-only list tool with four optional parameters and no output schema, the description covers the endpoint, return type, pagination model, and field projection—sufficient for correct invocation. Minor omissions like explicit alternative routing and default-value edge cases are acceptable given the schema already documents defaults.

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 page, fields, params, and maxResults in detail. The description mostly restates schema content ('Use fields...', 'page (0-based) + maxResults'), adding only a minor example without substantive new parameter meaning.

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

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

States 'List all profiles (booking pages) on the account' with a specific verb and resource, and defines what a profile is (a bookable page with subdomain, appointment types, team members, locations). This clearly differentiates the tool from get_profile and other list_* 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?

The description gives clear context for when to use the tool: when listing all profiles on the account, with pagination and field-selection behavior spelled out. It does not explicitly name alternatives like get_profile for single-profile lookups, so it stops short of full when-not/exclusion guidance.

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

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

Annotations already provide readOnlyHint=true, and the description adds meaningful behavioral context beyond it: the exact API endpoint, the teamMembers field selection, and the returned block's composition (id, name, email, description, pic, calendarId). It does not contradict the read-only annotation.

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 with zero waste: the action is front-loaded, the API mapping is one line, and the return shape is one line. Every sentence earns its place.

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

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

For a one-parameter, read-only tool with full schema coverage and no output schema, the description covers what it does, how it calls the API, and what it returns. The only gaps are minor: no behavior for missing/invalid profileId and no clarification of the relationship to the get_profile sibling.

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

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

Schema description coverage is 100% — profileId is already documented as 'The profile (booking page) id.' The description only restates profileId in the endpoint URL and adds no new format, constraints, or usage semantics, 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 verb and resource: 'List the team members configured on a profile (booking page).' This differentiates from create_team_member/update_team_member and list_profiles implicitly, though it never names a sibling explicitly, so an agent must infer the contrast rather than being told.

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

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

Usage context is implied: when you have a profileId and need its team members, this is the tool. However, there is no explicit when-to-use guidance or exclusions, and since the underlying call is GET /v1/profiles/{profileId} — the same endpoint a get_profile sibling would use — the description does not clarify when to choose this tool over get_profile.

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 provide destructiveHint=true, but the description adds 'MUTATES', 'PATCH', 'partial update', and clarifies that path ids are never sent in the body. This gives meaningful behavioral context beyond the structured annotation.

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, each earning its place: mutation warning, endpoint/method, and body/path-behavior detail. 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?

The description covers the mutation nature, HTTP method, partial-update semantics, field passthrough, and path-id behavior. With no output schema it leaves return-value details implicit, but everything necessary for safe invocation 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?

Although schema coverage is 100%, the description adds real value by explaining that changed fields go through the `fields` passthrough and by explicitly noting that profileId and appointmentTypeId are path-only parameters. This clarifies usage beyond the raw schema.

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

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

The description states a specific verb and resource: 'updates an appointment type on a profile' and pins it to the YCBM PATCH endpoint. This clearly distinguishes it from create/list appointment type 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 description makes clear this tool modifies an existing appointment type via partial update, which implies when to use it. However, it does not explicitly contrast with create_appointment_type or list_appointment_types, so some routing is left to inference.

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

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

The description goes well beyond the destructiveHint annotation by clarifying this is a PATCH partial update, that the bookingId is path-only and never sent in the body, and that `fields` is a passthrough for additional documented fields. These are concrete behavioral details that help the agent call the API correctly.

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 with the mutating nature and purpose, then adds protocol details and field guidance without fluff. Every sentence earns its place, and the most important routing information appears first.

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 10 parameters, a destructive annotation, and no output schema, the description is largely complete: it covers purpose, HTTP method, partial-update behavior, supported fields, the passthrough mechanism, and path handling. It does not describe the response shape, but the described PATCH semantics plus schema coverage give enough context for correct invocation.

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?

Since schema coverage is 100%, the baseline is 3, and the description adds extra meaning by grouping the updatable fields, explaining the partial-update semantics, and highlighting the `fields` passthrough for answers/linkFields. The path-vs-body distinction for bookingId is also valuable beyond the schema description.

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

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

The description states a specific verb and resource: it 'updates an existing booking' and gives concrete use cases (reschedule, rename, mark cancelled/no-show). This clearly distinguishes it from create_booking, get_booking, and cancel_booking, even though cancelling can also be done via the cancelled field.

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 clearly indicates this tool is for mutating an existing booking and lists which fields can be set, so an agent knows when to invoke it. It does not explicitly name alternatives like cancel_booking or create_booking or state when not to use this tool, but the context is clear enough.

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

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

Beyond the destructiveHint annotation, the description explains that this is a PATCH partial update, that profile fields use YCBM's own names, and that the path id is never sent in the body. These details clarify mutation scope and prevent common API usage mistakes.

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 each carry essential information: mutation, endpoint, field semantics, and body/path separation. There is no redundancy or filler, and important details are front-loaded.

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

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

The description covers the operation type, API contract, parameter roles, and field naming convention. With full schema coverage and the destructiveHint annotation, nothing essential for calling the tool is missing, though return/error behavior is not described.

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%, but the description adds value by explaining that 'fields' is a passthrough with YCBM's own field names, giving an example '{ title, subdomain, ... }', and emphasizing that profileId is path-only. This goes beyond the schema's minimal descriptions.

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 action and resource: 'updates a profile's (booking page) configuration' and labels it 'MUTATES'. The verb and resource are explicit, and the tool name plus sibling set make it clearly distinct from get_profile and list_profiles.

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

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

The description gives clear context: this is the mutation counterpart to profile reads, using PATCH with partial update semantics. However, it does not explicitly name alternatives or state when not to use this tool, leaving the agent to infer from the verb and sibling names.

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 adds meaningful behavioral context beyond the destructiveHint annotation: it specifies the HTTP method (PATCH), partial-update semantics, the `fields` passthrough mechanism, and that path ids are never sent in the body. This gives the agent a clear mental model of the request construction without contradicting the annotation.

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 with the key mutation signal. Every sentence earns its place: the endpoint, the partial-update behavior, the fields passthrough mechanism, and the path-id prohibition are all essential and clearly organized.

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 tool with three parameters and no output schema, the description covers the important invocation details: what is updated, how updates are sent, and how path/body are separated. It does not describe the response shape, but that is less critical given the read-only absence and the clear focus on the write operation.

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 extra semantic value by explaining that `fields` is a passthrough for changed YCBM fields and that profileId and teamMemberId are path-only. This clarifies the body/path separation and how the nested fields object is used.

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 a team member on a profile.' The explicit 'MUTATES' prefix removes ambiguity about the operation's nature, and the full REST endpoint clearly distinguishes this from related tools like create_team_member or update_profile.

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 clearly indicates this tool is for mutating an existing team member via PATCH, and the partial-update wording implies it is appropriate for targeted changes. It does not explicitly name alternatives or when-not-to-use scenarios, but the context is clear enough that an agent can select it confidently.

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 adds that only GET is allowed, the full path including query string is required, and the response is parsed JSON. This adds useful behavioral constraints beyond the annotation without contradiction.

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

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

Three sentences, front-loaded with the escape-hatch purpose, followed by the read-only constraint and precise path instructions. Every sentence earns its place with no redundancy or filler.

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

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

For a one-parameter read-only tool with no output schema, the description fully covers what it does, when to use it, how to format the parameter, and what is returned. The sibling list further helps the agent know which dedicated tools exist.

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 description already documents the path format. The description reinforces this with emphasis on the full path after the origin, including query strings, and provides concrete examples, going slightly beyond the schema 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 (GET) and resource (any YCBM API path), and clearly frames itself as an escape hatch for paths not wrapped by a dedicated tool. This distinguishes it from the sibling tools without requiring an agent to compare schemas.

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 says to use it for any YCBM API path not wrapped by a dedicated tool, and warns that only GET is allowed, which excludes mutation use cases. This gives a clear when-to-use and when-not-to-use rule, with dedicated tools as the alternatives.

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