AdvocateMCP

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

Annotations already declare readOnlyHint=false, destructiveHint=true, and idempotentHint=true. The description adds valuable context beyond these: the refund window logic, the distinction between full refund and forfeited deposit, the meaning of 'pending refund', and the already_cancelled response for duplicate calls. It doesn't contradict the annotations. The only minor gap is that it doesn't explicitly state what happens to the booking record itself (e.g., whether it's deleted or marked cancelled), but the destructiveHint and the refund discussion cover the key behavioral traits.

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

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

The description is a single dense paragraph that front-loads the core action and token requirement, then explains refund behavior and edge cases. Every sentence adds meaningful information. It's slightly long but justified given the complexity of refund logic. The structure is logical: action → refund timing → pending state → token ownership → duplicate behavior.

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 essential behavioral context: what constitutes a full refund, when deposit is forfeited, what pending refund means, token ownership, and duplicate handling. The output schema exists, so return values don't need to be described. The only minor gap is that it doesn't explicitly mention prerequisites like having a payment receipt or the business's refund policy details, but the description references the policy and the token requirement sufficiently.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters (slug, reservation_id, cancel_token). The description adds the crucial semantic link that cancel_token comes from the payment receipt and that reservation_id is for the paid reservation, but it doesn't go beyond what the schema already states. Baseline 3 is appropriate since the schema does the heavy lifting.

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

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

The description states a specific verb ('Cancels'), a specific resource ('a paid, confirmed booking'), and the key mechanism ('using the cancel_token from its payment receipt'). It clearly distinguishes this from siblings like confirm_booking and create_booking_payment_link by focusing on the cancellation action and its token requirement.

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 explicit context for when to use the tool: for paid, confirmed bookings with a cancel_token. It also gives clear behavioral guidance on refund timing ('Within 60 minutes of paying, or before the business's refund window'), how to report refund status ('report it as full only after the payment ledger confirms it'), and what to do about pending refunds. It even addresses the edge case of double cancellation ('Cancelling twice answers already_cancelled'). This is strong usage 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 signal a non-read, destructive operation, but the description adds valuable behavioral context beyond them: a verified code attempts a direct calendar commit with no owner approval, booking_pending means the provider outcome is uncertain with no automatic provider retry, and paid bookings have no code. This meaningfully explains side effects and state transitions 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?

The description is dense but every sentence earns its place: it states the core action first, then covers the code rule, commit behavior, pending outcome, and the paid-booking exception. There is no filler or repetition of schema 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 mutating, stateful confirmation tool, the description covers the main success path, the uncertain provider outcome, the no-retry behavior, and the paid-booking branch. An output schema exists, so return-value details do not need to be in the description, and schema validation covers the code format. Nothing essential for selecting and invoking this tool correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds extra value by explaining the lifecycle of the code parameter: it must be customer-supplied, never generated or fetched, and is absent for paid bookings. This goes beyond the schema's own documentation, though slug and reservation_id semantics remain mostly schema-dependent.

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 ('Confirm a reservation made with reserve_slot') and clearly distinguishes this from related payment and booking tools. It also names the alternative for paid bookings, so an agent can tell it apart from create_booking_payment_link and reserve_slot without opening their 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?

The description gives explicit when-to-use guidance and exclusions: use it when a reservation exists and a customer supplies the code; for paid bookings with payment.required=true, route to create_booking_payment_link; for payment_in_flight, wait; for booking_pending, repeat confirm_booking later. These conditions and alternatives are stated directly rather than 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?

Annotations already declare readOnly, idempotent, and non-destructive. The description adds meaningful behavioral context: the agent itself pays via an HTTP 402 challenge using the person's wallet credential, and no code is sent to the customer for paid bookings. It also clarifies the not_payable response for free bookings. This goes beyond annotations without contradicting them.

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 sentences, concise and front-loaded with the trigger condition. It includes essential behavioral details (payment mechanism, free-booking alternative) without redundancy, so each sentence earns its place.

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

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

Given the tool's complexity (payment flow) and that an output schema exists, the description covers the trigger, the return values, and the alternative for free bookings. It also explains the payment process. The output format is not detailed, but that is covered by the output schema, so 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?

Schema coverage is 100% for both parameters, and the description only reiterates that reservation_id comes from reserve_slot with payment.required = true, which is already in the schema description. No new semantics are added beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

The description states the specific purpose: for a reservation with payment.required = true, it returns the payment link, amount charged now, and balance due. It explicitly distinguishes this from confirm_booking by noting that free bookings (not_payable) should use confirm_booking instead. The condition is precise, so an agent can clearly identify when this tool applies.

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

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

It gives explicit when-to-use guidance (reserve_slot returned payment.required = true) and when-not-to-use (free bookings answer not_payable), and names the alternative tool (confirm_booking). This is complete routing information with no ambiguity.

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, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral context beyond these: it explains that availability is computed using the business's timezone, duration, operating hours, and occupancy, and it discloses that results can change before confirmation, including when the calendar provider is unavailable. This reinforces the openWorldHint and provides operational insight without contradicting 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 three sentences with no filler. The first sentence delivers the core functionality, the second gives a direct usage instruction, and the third adds a critical caveat and an alternative route. It is front-loaded and 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 read-only tool with a full output schema, the description covers the key context: what it does, how results are computed, that they can change, and what to do for unsupported providers. Nothing essential for an agent to correctly invoke this tool is missing.

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

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

The input schema descriptions cover all three parameters with 100% coverage, explaining window_start and window_end defaults and the timezone handling. The description does not add any additional parameter-specific meaning beyond what the schema provides, so it stays at the baseline for full 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 states the exact purpose: 'Return available windows from the business's active configured calendar' – a specific verb, resource, and scope. It clearly differentiates from siblings by mentioning get_booking_destination as an alternative for unsupported providers, and it implies that this tool is for retrieving availability, not for booking directly.

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 explicitly states when to use this tool ('Use a returned window to start a booking') and provides an alternative condition: 'If this business uses an unsupported calendar or booking provider, call get_booking_destination'. This gives clear routing guidance and covers the primary use case and exclusion.

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 behavior beyond annotations: external provider pages are links only, and Advocate does not sync their availability or make bookings there. This is important, non-obvious behavioral context that helps an agent interpret results safely. It is consistent with the readOnlyHint and idempotentHint 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?

Three sentences, all purposeful: the core function, the usage context, and the critical behavioral caveat. The information is front-loaded and no words are wasted. This is an ideal length for the tool's complexity.

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 the single parameter, rich annotations, and the presence of an output schema, the description covers everything needed to use the tool correctly. It explains the edge case of external provider pages and clarifies the limitations around availability syncing and booking, so an agent can act appropriately on the result.

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

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

The schema already fully describes the single parameter 'slug' with 100% coverage, so the description does not need to add parameter details. The description's business-level context indirectly reinforces the parameter's meaning but adds no new semantic detail beyond the schema.

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

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

The description opens with a specific verb and resource: 'Returns the public booking route for a business.' It also clarifies what the tool distinguishes among external provider pages, active configured calendars using the Advocate booking flow, and businesses without a supported booking destination. This clearly separates it from sibling tools like get_availability or get_payment_handoff_url.

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 explicitly says 'Use this before helping a user book an appointment,' giving a precise when-to-use context. It does not name alternative tools or say when not to use it, but the context makes the intended placement in the workflow clear.

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

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

Annotations already provide readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds that response includes agent guidance and freshness caveats, which is useful context beyond the annotations.

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

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

Two concise sentences with no waste. First sentence states purpose, second provides usage guidance and response details. Front-loaded and efficient.

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 the simple tool structure (1 param, read-only, idempotent, with output schema), the description fully covers purpose, usage, and response content. No gaps.

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 has 100% coverage for the single parameter 'slug' with its description. Description does not add additional meaning to the parameter beyond what schema already provides, so baseline score of 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?

Description clearly states verb 'Returns' and resource 'cancellation policy text'. Distinguishes from siblings like get_availability or get_credentials by specifying exactly what business policy is returned.

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 'Use this when a user asks about cancellation terms, fees, or no-show policies' and mentions that response includes agent guidance on framing with freshness caveats.

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 indicate read-only, non-destructive, idempotent behavior. The description adds critical context: the response is 'self-reported' and agents should not upgrade claims to verified facts, which is valuable beyond the annotations.

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

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

Two concise sentences: first states purpose, second provides usage guidelines and key behavioral note. No filler or redundancy; 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?

Given the tool's simplicity (one parameter, output schema present, read-only), the description covers purpose, usage context, and critical behavioral nuance completely. No gaps remain.

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

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

Schema coverage is 100% with a description for the only parameter (slug). The description does not add additional parameter semantics beyond what the schema provides, 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 clearly states the tool returns business credentials (licenses, insurance, etc.) and uses specific verbs. It is easily distinguishable from sibling tools like get_availability or get_cancellation_policy which cover different aspects.

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 recommends use for trust-sensitive verticals and gives example user queries ('are they licensed?'). While it lacks explicit 'do not use' statements, the guidance is clear and actionable.

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 idempotent and non-destructive annotations, the description discloses the key behavioral constraint: the URL must be handed to the customer and not followed by the agent. It also adds the deposit_taken context and clarifies the next step, adding real behavioral value.

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 dense but every sentence earns its place: output first, then the critical warning, then usage preconditions, then the deposit caveat. It is well-structured and front-loaded with the most important information.

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

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

With two fully described parameters, an output schema, and clear annotations, the description covers the output contents, customer context, usage conditions, and the relevant sibling tool. An agent has everything needed to invoke this 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 schema already fully documents both parameters with descriptions, so the baseline is high. The description adds useful context by explaining that offer_id comes from get_quote or a booking flow and that the result interacts with deposit status, helping the agent pick the correct value.

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 precisely what the tool returns: a plain-text summary of a priced offer plus a customer-facing URL, and it enumerates the summary fields. It clearly distinguishes itself from sibling tools by emphasizing the URL is for the customer to open, not for the agent.

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 an explicit precondition ('once get_quote or a booking flow has produced an offer_id'), a readiness condition, and an exclusion for already-paid deposits via create_booking_payment_link. It also gives the critical do-not-open/fetch/follow instruction, which is essential operational 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 goes beyond the annotations by disclosing that exact configured prices may create a time-limited offer, and that unmatched requests use a third-party AI estimate that is not firm merchant pricing and must be confirmed. This is valuable behavioral context beyond readOnlyHint and idempotentHint.

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 sentences with no filler. It front-loads the core purpose, then adds the critical caveat about pricing behavior, and finally gives a practical usage trigger. Every sentence contributes meaningful information.

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

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

The description, combined with the rich schema, output schema presence, and annotations, provides enough context for an agent to call the tool correctly. It explains what the tool does, when to use it, and the important caveat that some quotes are non-binding estimates.

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 has 100% description coverage for slug, service, and params, so the description does not need to repeat parameter details. The description adds no additional parameter-level meaning beyond the schema, placing it at the baseline for well-covered schemas.

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

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

The description clearly states that the tool returns a price quote for a service at a business, using a specific verb and resource. It does not explicitly distinguish itself from sibling tools like submit_quote_request or list_services, so it stops short of full differentiation.

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 explicit usage guidance: 'Use this when a user asks how much does X cost?' This gives clear context for when the tool is appropriate. However, it does not mention when not to use it or point to alternatives, so it earns a 4 rather than 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 description adds useful nuance beyond the annotations, especially the idempotent key behavior and the server-side composition of notification bodies. However, the annotations mark destructiveHint true and the description does not disclose any destructive or irreversible effects, leaving part of the behavior unexplained.

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 purpose, then adds only the two most decision-relevant clarifications: mode behavior and idempotency. No sentence is wasted.

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, annotations, and 100% schema description coverage, the description fills the remaining gaps around mode semantics and idempotent behavior. It does not detail destructive aspects, but for the tool's complexity it is sufficiently 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?

The schema already covers all 12 parameters, but the description adds significant meaning: callers supply contact and reason fields in human mode, message is a deprecated alias, and idempotency prevents duplicates. This helps the agent choose and populate parameters correctly 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 clearly states the tool begins a handoff and gives the two concrete modes (human operator vs. another agent), making the verb, resource, and scope unambiguous. It also distinguishes its function from the sibling tools without requiring schema inspection.

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 explains when this tool is relevant, including the two distinct handoff targets and how human notifications are composed server-side. It does not explicitly name alternative tools or spell out exclusion caveats, but the context is clear enough for a selecting agent.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: the silent fallback to an estimate with no offer when a name is not on the list, and the condition that only payable services return an exact price with offer_id. This goes beyond the annotations and helps the agent anticipate 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?

The description is compact and front-loaded: it states the core purpose in the first sentence, then immediately provides the critical usage ordering and fallback warning. Every sentence earns its place, and there is no redundant repetition of schema or annotation information.

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

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

Given the tool has a single parameter, a rich output schema, and annotations covering safety, the description is complete. It explains the prerequisite relationship with get_quote, the payable-service condition, and the failure mode for unlisted names. An agent has everything needed to call this tool correctly and interpret its role in the workflow.

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 the slug parameter. The description does not add extra meaning about the parameter beyond what the schema provides, but it does imply the slug identifies the business whose services are listed. Baseline 3 is appropriate because the schema carries the parameter documentation burden.

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 lists configured services with prices and quoting arguments, and explicitly distinguishes it from get_quote. It names the specific resource (services) and the action (list), making its purpose unambiguous.

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

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

The description explicitly instructs to call this BEFORE get_quote, explains the dependency (service name must match a configured service), and warns about the fallback behavior when quoting an unlisted name. This is strong when-to-use guidance with clear alternatives and sequencing.

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 important behavioral traits beyond the annotations: the question and public profile are processed by an AI provider, the interaction is recorded, and users should avoid entering sensitive personal, medical, payment, or authentication information. This meaningfully supplements the sparse annotation metadata and warns about side effects and privacy.

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 sentences with no filler: the first states the outcome, the second covers privacy/processing behavior, and the third gives usage guidance. Every sentence earns its place and the key action 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 tool with an output schema and well-documented parameters, the description provides sufficient context: what the tool does, what it returns, when to use it, what side effects exist, and what information to avoid. An agent selecting or invoking this tool has the essential information it needs.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters. The description does not add substantial parameter-level detail, though it does reinforce the nature of the query as a visitor question about a single business. This meets the baseline but does not exceed it.

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 opens with a precise verb+resource: 'Ask a registered business's AI advocate a question and get a citation-ready answer plus a referral link.' It clearly scopes the tool to questions about a single business and names the output format, distinguishing it from sibling tools like search_businesses or request_service.

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

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

The description explicitly states when to use the tool: 'Use this for questions about one business's services, hours, policies, or fit.' It does not explicitly name sibling alternatives or state when not to use them, but the one-business scope and question-oriented purpose provide clear usage context.

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 declare destructiveHint=true, but the description says 'Submit a callback request' and emphasizes idempotency, indicating a non-destructive create operation. This is a direct annotation contradiction. The description does disclose delivery-not-guaranteed and follow-up needs, but the contradiction forces the lowest score.

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 fluff: purpose, delivery caveat, and idempotency behavior are each covered. The information is front-loaded and 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 9-parameter state-changing tool, the description covers purpose, external delivery behavior, failure handling, and idempotency, which is solid given the output schema and full parameter schema coverage. The main gap is the lack of alternative-tool routing, and the destructiveHint contradiction adds confusion.

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 fully documents each parameter; the description adds value by explaining idempotency_key behavior and the SMS/email channel context. This matches the baseline of 3 where the schema does the heavy lifting.

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

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

The description states a specific verb and resource ('Submit a callback request') and adds useful context (on behalf of a user, via lead routing). It is clearly distinct from siblings like request_service or submit_quote_request, though it does not explicitly name or contrast those alternatives.

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

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

The description implies when to use the tool (when a user wants a callback) and provides post-use guidance about failed or pending notification results requiring follow-up or retry. However, it does not explicitly state when to choose this tool over alternatives or provide exclusion criteria.

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 annotations by disclosing that the tool only shows the business and service catalog, does not submit or book, requires explicit customer consent, and logs operational access. This gives the agent clear expectations about side effects and usage constraints.

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 concise and well-structured, front-loading the core action and identifier source, then adding key behavioral caveats in short sentences. Every sentence earns its place with no redundancy.

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

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

For a single-parameter tool with a full schema description and an output schema, the description is complete. It explains when to use it, what it does and does not do, the consent requirement, and logging behavior, leaving no important gap for an agent.

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 describes business_id as an exact public slug or provider_business_id obtained from search or the business feed. The description repeats this same information without adding new parameter-level meaning, so the baseline of 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 clearly states the tool opens a quote-request form for a specific business, using a specific identifier. It explicitly distinguishes itself from submitting a request or booking anything, which separates it from siblings like submit_quote_request and confirm_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 provides clear context for when to use the tool: after obtaining a business slug or provider_business_id from search or the business feed. It also implies exclusions by saying it does not send a request or book, though it does not explicitly name alternative 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 description goes well beyond annotations by disclosing the 15-minute expiry, the confirmation code delivery mechanism, idempotent re-use behavior, and the deposit edge case where no code is sent and payment amount appears in the result. Annotations already flag idempotency and write intent, but the description adds operational detail that materially affects agent 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 dense but every sentence earns its place: main purpose, return value, code delivery, expiry, idempotency, and the deposit exception. It is front-loaded with the core action and progressively adds edge cases. No filler or repetition of schema 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?

For a tool with 7 parameters, nested objects, and an output schema, the description covers all critical operational aspects: what it does, how to handle idempotency, deposit requirements, and contact preferences. It does not need to describe return values since an output schema exists. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so each parameter is already documented. The description adds cross-tool meaning by explaining how offer_id ties to get_quote and the consequence of omitting it (quote_required). It also clarifies the customer_contact requirement (must include email or phone) beyond the schema's structural requirement, which is useful. This exceeds the baseline for high 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 states a specific verb ('Reserve'), a clear resource ('a time slot on an active configured calendar'), and distinguishes it from siblings by mentioning it returns a pending_offer reservation and sends a confirmation code. It clearly differentiates from get_availability (listing) and confirm_booking (confirming).

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: it is the reservation step, and it explicitly addresses the deposit scenario by instructing to pass offer_id from get_quote and warning about the quote_required result when omitted. It does not explicitly name alternatives like confirm_booking, but the flow is unambiguous from the sibling list and the description's own details.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the behavioral detail that results include slugs, which helps the agent understand the output shape. No contradictions; the added context is valuable but not extensive.

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, no filler, and the core action is front-loaded. The sentence about calling it before business-specific tools is a useful addition without waste. Every word 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 simple search tool with an output schema present and annotations covering safety, the description is sufficient. It states the purpose, the optional filter, and the return value, plus the operational order. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%—both 'search' and 'location' are fully described in the schema. The description merely restates 'by search term and optional location' without adding new semantic detail. Baseline 3 is appropriate because the schema carries the 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 a specific verb ('Find'), resource ('registered businesses'), and criteria (search term + optional location), and explicitly notes the return value (matches with slugs). Clearly distinguishes from the business-specific sibling tools by framing it as the entry point for locating businesses.

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?

Provides direct sequencing guidance: 'Call it before the business-specific tools.' This tells the agent when to use it, but does not explicitly mention when not to use it or name an alternative. The context is clear enough for a search-first workflow, so it earns a 4 rather than 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?

Beyond the annotations, the description discloses idempotency behavior: reuse the same idempotency_key AND details to check an uncertain submission, and never automatically start a new request. It also warns to exclude sensitive medical, payment-card, and authentication information, and clarifies that this action does not create a booking, payment, or price commitment.

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: it starts with the consent condition and core action, then adds exclusions, idempotency guidance, and sensitive-data warnings. Every sentence contributes meaningful behavioral or usage information with no redundancy.

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

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

For a 9-parameter mutation tool with an output schema and many siblings, the description covers the essential context: when consent is required, where the context token comes from, how to handle idempotent retries, what the tool does not do, and what content must be excluded. Return values need not be described because an output schema exists.

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 67%, so the schema already documents most parameters. The description adds useful operational semantics: context_token should come from request_service, idempotency_key must be reused with the same details when checking an uncertain submission, and details must exclude sensitive information. It treats contact_name, contact_email, and contact_phone collectively as 'contact details' but does not individually explain each, so it does not fully compensate for the missing schema 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 clearly identifies the operation: save the customer's service requirements and contact details, then send a notification to the business. It explicitly scopes the action as requesting a business response rather than a price commitment, booking, or payment, which distinguishes it from siblings like get_quote and confirm_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 a clear precondition ('After the customer explicitly agrees'), a prerequisite source ('Use context from request_service'), and explicit exclusions ('not a price commitment, booking or payment'). It does not name sibling alternatives directly, but the when-not conditions are specific enough to guide 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?

Beyond the annotations (idempotentHint, mutating hints), the description discloses the full workflow: the subscription is pending until the user clicks a confirmation URL, the URL is user-exclusive, and it expires within 7 days. It also specifies what idempotency means in practice — reusing the key returns the original subscription. This is exactly the behavioral nuance an agent needs and cannot derive from 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?

Three sentences with zero waste: purpose first, then the confirmation workflow, then idempotency semantics. Every sentence carries load-bearing information, and the most decision-relevant facts (pending state, 7-day window, user-only click) 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?

Complete for this tool's complexity. The output schema covers return values, annotations cover the mutating/idempotent profile, the schema documents all five parameters, and the description covers the workflow quirks (pending, expiry, confirmation). No critical gap remains for an agent to call this 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 genuine semantics on top: it ties contact_email to the confirmation flow and, more importantly, explains that re-using idempotency_key returns the original subscription — a behavioral consequence absent from the schema's bare 'Idempotency key' label.

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 opens with a specific verb+resource: 'Start a pending email subscription to updates from a business.' This is unambiguous and clearly distinct from the sibling tools (booking, quoting, availability, payment), so an agent can identify what this tool does without opening the schema.

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

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

Usage context is implied by the purpose statement — this tool is for email subscriptions to business updates, which is outside the booking/quote/payment domain of the siblings. However, there is no explicit when-to-use or when-not-to-use guidance, and no alternative tool is named, so the agent must infer applicability.

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