MCP Near Me

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

With annotations covering destructiveness and idempotency, the description adds meaningful operational context: the cancellation frees capacity, sends transactional notifications, and requires a one-time approval from a protected form. It does not contradict the annotations and enriches the behavioral picture beyond the structured hints.

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

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

Three sentences, each earning its place. The critical precondition is front-loaded, followed by behavior and retry semantics, 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?

The description covers authorization, idempotency, and side effects for a destructive mutation, and an output schema exists so return values need not be explained. However, three of five required parameters remain undocumented, and no alternative sibling tool is named, leaving gaps 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 only 20%, so the description must compensate. It adds some meaning for the authorization token and idempotency key, but source, anonymous_session_id, and correlation_id receive no explanation in either the schema or the 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 cancels the authorized active booking, frees capacity, and sends notifications. It does not explicitly distinguish this tool from related siblings such as reschedule_service_booking or prepare_service_booking_change, so sibling differentiation is left to the name and title.

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 precondition: use only with the one-time approval issued after the user confirms the exact cancellation inside the protected management form. It also specifies that safe retries must reuse the same idempotency key. It does not name alternative tools or explain when to use those instead.

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 cover idempotency and non-destructiveness, so the burden is lower. The description adds valuable behavioral context about its legacy/compatibility-only nature and a critical chat-safety guardrail about not asking for SMS codes. Side effects are not detailed, but annotations already establish 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?

Three sentences with no filler. The core purpose is front-loaded, followed by critical prohibitions and an alternative route. 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?

With an output schema present, one parameter, and strong annotations, the description supplies purpose, exclusions, and alternative routing. It could more explicitly define what counts as an 'explicitly initiated legacy profile-link session,' but that is a minor gap for a compatibility-only endpoint.

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

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

Schema description coverage is 0%, so the description must compensate. It refers to an 'explicitly initiated legacy profile-link session' and the parameter is named linking_session_id, but the description never explicitly defines the parameter, its origin, or how to obtain it. The mapping is inferable but not stated.

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 tool's specific role: 'compatibility-only completion for an explicitly initiated legacy profile-link session.' It distinguishes this from new-booking and existing-appointment flows, preventing confusion with sibling booking-management 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?

Explicit when-not-to-use guidance is given: 'Never call it as part of a new booking' and 'never ask for an SMS code in chat.' It also names the alternative path for existing appointments: 'starts Connect through the corresponding booking-management 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?

Adds real context beyond the annotations: this is an anonymous action, it must not trigger Connect or phone verification, server-context fields must not be passed or reconstructed, and retries must reuse the idempotency key (corroborating idempotentHint=true). It does not describe what the booking mutation destroys despite destructiveHint=true, or any auth/token expiry failure modes.

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 sentences, each load-bearing, with the critical precondition front-loaded and the retry rule last. 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?

Output schema exists so return values need no explanation, and annotations cover safety/idempotency, letting the description focus on preconditions and the anonymity constraint. The main gap is the half-documented parameter set, which no structured field covers.

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 0% across 6 params, so the description carries the burden; it explains idempotency_key retry semantics and loosely ties booking_authorization_token to the 'one-time authorization', but source, campaign_id, correlation_id, and anonymous_session_id remain undocumented anywhere. It also warns about server-context values that are not even present as schema parameters, which is useful guidance but not parameter documentation.

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

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

States a specific verb+resource ('create…service booking') and qualifies it as 'the confirmed service booking' that 'completes the booking', which reads distinctly from the prepare/reschedule/select siblings. It stops short of naming which sibling to use for the non-final steps, so differentiation is inferred from the 'final card / Confirm' precondition rather than stated outright.

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

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

Gives a firm precondition: 'Use only from the protected final card with its one-time authorization after the user presses Confirm,' plus a clear exclusion ('must not trigger Connect or phone verification'). It never names the alternative tool for the pre-confirm flow, so routing is strong but not fully closed.

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

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

Annotations already establish read-only, idempotent, and non-destructive behavior. The description adds useful context beyond those annotations: the appointment must belong to the connected customer, and behavior differs between historical and current manageable appointments. No contradiction with annotations exists.

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

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

Two compact sentences with the core purpose and read-only nature front-loaded. The second sentence adds important state-dependent behavior without fluff 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 simple read-only tool with an output schema and strong annotations, the description sufficiently covers purpose, ownership, and state-dependent behavior. The main omissions are explicit parameter semantics and explicit sibling routing, but those are partially recoverable from the schema and tool names.

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 0%, so the description must compensate for parameter meaning, but it does not mention booking_id or intent explicitly. The reschedule/cancellation wording hints at the intent enum, but an agent gets no direct guidance on what booking_id identifies or how intent changes the returned card. This is a meaningful gap.

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

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

The description uses a concrete operation ('Open') and a clear resource ('an appointment that belongs to the connected customer'), and explicitly labels the tool as read-only. It also differentiates it from mutation-focused siblings by noting that historical appointments have no management actions.

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

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

The description conveys when to use this tool: to open a connected customer's appointment, and for currently manageable appointments, to obtain the protected card for reschedule or cancellation review. It does not explicitly name sibling tools or state when to prefer cancel_service_booking or reschedule_service_booking directly, so a fully explicit exclusion is missing.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior. The description adds useful context: data is live and aggregated, company names are omitted, and no capacity is reserved, which goes beyond the generic safety hints.

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

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

Three sentences, each with a distinct job: when to use, what it returns, and what it does not do. No filler or repetition.

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

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

With an output schema, rich annotations, and only one parameter, the description covers usage, behavior, and exclusions well. The only notable gap is not explaining where request_id comes from, but the low complexity and self-describing parameter keep it nearly 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 0% and the description never explains request_id, its origin, or its relationship to the intake flow. The property name is self-explanatory as an ID, but the description adds no parameter-level meaning to compensate for the missing schema documentation.

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

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

The description uses a specific verb and resource: it returns live aggregated potential windows and the current refinement batch, and explicitly scopes itself by saying it does not select a provider or reserve capacity. This clearly distinguishes it from sibling tools like select_service_option.

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 explicit timing: use after intake required fields are known, or to refresh matching data. It also states what the tool does not do (select/reserve), but it does not name the alternative tool to use for those actions.

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 readOnly/idempotent annotations, the description adds substantial behavioral context: it precisely defines 'active' as a confirmed or rescheduled appointment whose arrival window has not ended, states that past/terminal bookings are never active, instructs the agent to present choices rather than guess, and warns not to ask for phone/code because Connect is handled by the platform. This materially shapes both tool invocation and conversation behavior.

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

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

The description is four short, purposeful sentences, front-loaded with the immediate-use directive. Each sentence earns its place: when to use, status semantics, multi-result handling, and platform/communication guardrails. There is no filler or repetition of the annotation flags.

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

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

The tool is a read-only listing operation with two optional parameters and an output schema, and the description covers the key semantic nuance (active status), multi-result behavior, and user-communication constraints. It does not mention limit/pagination behavior or explicitly contrast with the singular get_my_service_booking, but these are relatively low-stakes given the output schema and the rest of the context. Overall, sufficient 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?

The status parameter is already documented in the schema with essentially the same wording as the description, so the description adds only minor clarification ('past or terminal bookings are never active'). The 'limit' parameter receives no semantic explanation in either the schema or the description, and the description does not compensate for that gap. With 50% schema description coverage, the description is adequate but not additive 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 clearly states a specific verb and resource: 'list my service bookings' / 'List my appointments' and says to use it 'immediately when the user asks to see or manage appointments.' However, it does not explicitly distinguish this listing tool from the sibling 'get_my_service_booking' (singular), so sibling differentiation is implicit rather than explicit.

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 strong context for when to use the tool: use it for seeing/managing appointments, pass status='active' for cancellation or rescheduling, and show choices instead of guessing when multiple active appointments are returned. It does not state when not to use the tool or name alternatives, so it lacks explicit exclusions.

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

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

Beyond the annotations (readOnlyHint false, idempotentHint true, destructiveHint false), the description adds critical behavior: it does not change the booking, it temporarily reserves a live slot for reschedule, and the user must separately confirm before any write tool runs. This meaningfully clarifies the side-effect profile without contradicting the annotations.

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

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

The description is compact and well-structured: each sentence adds a distinct, necessary piece of information — access requirement, non-mutating review purpose, slot source and temporary reservation, and the confirmation gate. There is no redundant or filler text.

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 purpose, access context, side effects, slot source, and workflow sequencing well, and an output schema exists so return values do not need explanation. However, it leaves the idempotency_key contract and the connection to the specific write tools implicit, so it is not fully complete for an agent invoking it cold.

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

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

Schema description coverage is only 20%, so the description must compensate for undocumented parameters. It adds useful meaning for new_slot_id ('a live slot returned inside the protected form') and loosely covers action, but it does not explain booking_id or the required idempotency_key, which are essential for correct invocation.

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 'prepares the exact reschedule or cancellation review but does not change the booking.' It clearly distinguishes this preparation tool from final write tools like reschedule or cancel by emphasizing that confirmation must happen before a write tool can run.

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: use it 'only from the protected management form after secure appointment access' and before the user confirms the preview. It implies the write tool is the alternative but does not explicitly name a sibling such as reschedule_service_booking or cancel_service_booking, so it falls just short of full 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 communicate read-only, idempotent, and non-destructive behavior. The description adds practical context that this tool surfaces a final card with specific fields and instructs the agent not to collect PII, which is useful behavioral guidance beyond the annotations. No contradiction exists between the description and annotations.

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

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

The description is extremely concise and front-loaded: the trigger condition is the first thing stated, and every sentence adds necessary information about when to use the tool and what it does. There is no wasted text or repetition of already-structured metadata.

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

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

For a simple, read-only tool with a single parameter and existing annotation coverage, the description covers the key operational context: trigger, content of the card, and interaction guidance. The only minor gap is that request_id semantics are not explicitly explained, but the tool is simple enough that this is unlikely to block correct usage.

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 for parameters is 0%, so the description had to carry meaning for request_id, but it does not mention this parameter at all. The schema only provides length constraints, not semantic meaning. An agent must infer that request_id is the identifier from the preceding update_service_request response, which is not explicitly stated.

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

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

The description clearly identifies the tool's specific function: rendering the final service confirmation card, with exact content (provider options, booking fields, policies, Confirm). It also distinguishes itself from the workflow by tying its use to a specific next_action from update_service_request, which sets it apart from the sibling tools that handle booking actions.

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 an explicit trigger condition: use only when update_service_request returns next_action=render_service_request_form. It also provides a clear exclusion: do not ask for contact PII in chat. This tells an agent when and how to use the tool, and what to avoid.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds substantive context: prior-time history is preserved, the old capacity is freed, and transactional notifications are sent. It also explains how to retry safely by reusing the same idempotency key, which is concrete operational guidance beyond the boolean hint.

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 dense sentences with no filler; the authorization precondition is front-loaded and the side effects and retry rule follow. It is appropriately sized for a destructive mutation, though the second sentence packs several distinct effects into one long clause.

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?

An output schema exists, so return values need not be described. The description covers the authorization prerequisite, the mutations performed, and idempotent retry behavior, leaving only the peripheral source/correlation/session parameters unexplained.

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

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

Schema description coverage is only 20%, so the description must carry more weight. It clarifies the authorization token's origin and the idempotency key's retry semantics, but source, correlation_id, and anonymous_session_id are left entirely to the bare schema types.

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+resource ('moves the existing booking to the reserved available time') and the title confirms it is a reschedule of an approved appointment. It distinguishes itself from prepare_service_booking_change by requiring the one-time approval token rather than producing a change, though it never names that sibling explicitly.

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

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

'Use this only with the one-time approval issued after the user confirms the exact reschedule inside the protected management form' gives a clear and restrictive precondition for invocation. It lacks explicit routing to alternatives (e.g. prepare_service_booking_change for the pre-approval step), 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 discloses critical behavioral traits beyond the annotations: it rechecks availability, releases any previous selection, creates a temporary hold, returns the protected booking schema, and explicitly does not create a booking. These side effects are essential for the agent to understand the non-read-only, state-changing nature of the operation.

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

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

Three short sentences with no filler. The usage restriction is front-loaded, followed by a compact sequence of behaviors and a final clarifying exclusion. Every sentence adds 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?

The description conveys the workflow and output shape well, and the output schema covers return values. However, all four input parameters are required and undocumented in both schema and description, so the agent cannot reliably construct a valid request. The missing semantics for expected_state_version and idempotency_key make the definition only minimally 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 description coverage is 0%, so the description must compensate for the four required parameters. It only implicitly maps option_key to 'one exact provider option' and gives no meaning for request_id, expected_state_version, or idempotency_key. This is a significant gap for correctly invoking the tool.

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 precise verb and resource: selecting one exact provider option from the final protected card. It lists specific actions (rechecks availability, releases previous selection, creates temporary hold, returns booking schema) and explicitly disambiguates from create_service_booking by saying it does not create a 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 an explicit when-to-use condition: 'Use only from the final protected card when the user selects one exact provider option.' It also provides a when-not by clarifying it does not create a booking. However, it does not directly name alternative sibling tools, so 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?

Annotations already declare idempotentHint=true and readOnly=false, which are consistent with the description's claim of creating a request. The description adds valuable behavioral context: it returns a vertical-specific introduction and a next step, instructs how to format the reply, and warns against collecting PII. This goes beyond the annotations and gives agents clear expectations.

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

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

The description is front-loaded with the action trigger and then flows logically through usage, behavior, and constraints. Every sentence adds value; there is no redundancy or filler. The structure is clear and easily digestible for an agent.

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?

Given that an output schema exists, the description does not need to explain return values. It covers the essential context: when to use, what to pass, what to expect in return, and how to respond. It is sufficiently complete for a tool with this complexity, though it could benefit from a brief mention of error handling or fallback behavior.

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

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

Schema description coverage is only 20%, so the description must compensate. It does explain the purpose of user_intent (complete intent) and provider_hint (only when named), and hints at answers via 'every public service detail already stated'. However, it does not clarify idempotency_key or the structure of nested answers beyond what the schema keys show. The description adds some meaning but leaves gaps for agents.

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 tool's purpose: to start a service request when the user asks to book a local service. It specifies the action (creates server-side request), the resource (service request), and distinguishes itself from siblings by being the immediate entry point. The phrase 'Use this immediately' differentiates it from other booking-related 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?

It provides a clear trigger condition ('when the user asks to book a supported local service') and gives specific usage constraints: pass complete user intent, send provider_hint only when a company is named, and do not collect contact PII. While it doesn't explicitly name alternatives, the instruction to use it immediately implies it is the first step, which is sufficient 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 adds significant behavioral context beyond the annotations. It discloses that this is a partial-update operation, that absent fields are treated as omitted per batch, that optional/conditionally required omissions don't block progress, and that the latest expected_state_version must always be passed (implying optimistic concurrency control). Annotations already indicate idempotency and non-destructiveness, and the description complements these without contradiction. It provides actionable behavior that isn't evident from schema or annotations alone.

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

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

The description is three concise sentences with no fluff. The purpose is front-loaded, followed by essential usage constraints (what to pass, how omissions are handled, and the version requirement). Every sentence adds value, and the structure is clean and easily digestible for an agent scanning tool descriptions.

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 core behavioral nuances: partial response handling, omission semantics, and version requirement. It also implicitly guides which fields to populate. Since an output schema exists, return values don't need explanation. The only minor gap is not explicitly stating when to use this vs. sibling tools, but that's addressed in usage guidelines. Overall, the description is complete for the complexity of the tool, which involves a nested answers object and concurrency controls.

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 itself provides per-property descriptions (e.g., 'Brand. Use the exact key brand.'), but the tool description adds critical parameter semantics: instructing to pass only user-supplied fields plus selected_time_key, and emphasizing the need for the latest expected_state_version. This compensates for the 0% schema description coverage by guiding how to construct the answers object and which required parameters are mandatory. It doesn't explain idempotency_key or request_id, but those are already required in 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 clearly states the tool's purpose: updating a service request with a user's partial response to the current intake or matching batch. It names the resource (service request) and the action (update via partial response). While it doesn't explicitly differentiate from siblings like reschedule_service_booking or prepare_service_booking_change, the 'current intake or matching batch' context implies it's for in-progress requests, which distinguishes it from booking lifecycle tools. The description is not a tautology and adds specific context about partial responses.

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 opens with 'Use this for the user's partial response to the current intake or matching batch,' which is an explicit when-to-use instruction. It clarifies that only user-supplied values plus selected_time_key should be passed, and explains how omitted fields are treated (they don't block progress). However, it doesn't explicitly mention when NOT to use this tool or name alternatives, such as using create_service_booking for new bookings or reschedule_service_booking for changes. The guidance is clear but lacks explicit exclusions.

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