AdvocateMCP

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

Beyond annotations, it discloses a direct provider commit with no owner approval, states that booking_pending leaves the provider outcome uncertain, and clarifies that repeated calls check the stored outcome without retrying the provider write automatically. This goes well beyond the structured annotation flags.

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 purposeful sentences cover the main action, code-handling constraint, commit semantics, and retry behavior without fluff. The critical operation is front-loaded in the first sentence.

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 and full parameter documentation, the description covers prerequisites, sequencing, side effects, and pending-state handling. An agent has what it needs to call the tool correctly and set appropriate expectations.

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 all three parameters, and the description largely restates the schema's code provenance guidance and the reservation_id link to reserve_slot. It adds no significant new parameter-level semantics beyond the structured 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 first sentence states a specific action — 'Confirm a reservation made with reserve_slot' — with a clear resource and predecessor tool. It also gives concrete behavioral scope: relay only a customer-supplied code and never generate, guess, or fetch it.

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

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

The description establishes the intended workflow: use it on reservations created by reserve_slot, and for an active configured calendar with a verified code it attempts a direct commit. It gives a retry guideline for booking_pending, but does not explicitly name exclusions or 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 beyond annotations by explaining that availability depends on the business's configured timezone, duration, operating hours, and current occupancy, and that results can change before confirmation, including when the calendar provider is unavailable. Although readOnlyHint is false, the description does not directly contradict that annotation because it never explicitly promises no state change.

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 earn their place: one defines the result and inputs, one states the intended booking follow-up, and one warns about volatility and provider failure. There is no filler or redundant restatement of the schema.

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?

Combined with a fully documented input schema and an output schema, the description covers what the tool returns, how the result should be used, timezone handling, and the important reliability caveat about changing availability and provider unavailability. Nothing critical is missing for an agent to call the tool correctly.

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

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

Schema description coverage is 100%, and the schema already explains slug, window_start/window_end defaults, absolute instants, and how to interpret the response timezone. The description adds useful context about the business's configured calendar, but it does not meaningfully extend the per-parameter semantics already present 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 names a specific verb and resource: 'Return available windows from the business's active configured calendar.' It also clarifies the tool's role by saying to use a returned window to start a booking, which distinguishes it from reservation or confirmation siblings like reserve_slot 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 gives clear context that this tool is the availability-lookup step before booking, and the caveat that availability can change before confirmation implies a firmer sibling should be used when a guarantee is needed. It does not explicitly name when-not-to-use alternatives, so it stops short of a 5.

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

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

Annotations only indicate idempotent and non-destructive behavior. The description adds meaningful behavioral context by revealing the response includes agent guidance on framing the policy and appropriate freshness caveats. This is useful beyond what annotations provide.

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 tight sentences with no filler. The main purpose is front-loaded, and the usage guidance and response caveat each earn their 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?

The tool has one simple parameter and an output schema, so the description doesn't need to detail return values. It covers the core purpose, typical trigger conditions, and a notable response trait. A minor gap is the lack of any mention of required authorization or error behavior, but these are less critical given the tool's simplicity.

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% for the single 'slug' parameter, and the schema already explains it as a 'Business slug identifier'. The description adds no extra parameter-level detail, 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 uses a specific verb ('Returns') and names a concrete resource ('the business's cancellation policy text'). The use-case hint ('when a user asks about cancellation terms, fees, or no-show policies') also helps distinguish it from sibling tools like get_quote or get_availability.

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 states when to use the tool: when the user asks about cancellation terms, fees, or no-show policies. It does not mention when not to use it or alternatives, but the sibling set contains no direct competitor for this specific retrieval task, making the guidance adequate.

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 a valuable behavioral caveat beyond what annotations provide: the data is self-reported and the response carries explicit framing so agents do not treat tenant claims as verified facts. This directly informs how an agent should interpret and relay the returned information.

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 adding distinct value: what is returned, when to use it, and a caveat about the self-reported nature of the data. 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 single-parameter tool with an output schema, the description covers the domain, the trigger conditions, and the key trust caveat. Nothing critical is missing for an agent to invoke it correctly and interpret its results appropriately.

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 single parameter 'slug' is already documented in the schema with 100% coverage, so the description adds little beyond identifying whose credentials are returned. 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?

The description names a specific verb ('Returns') and a precise resource: the business's self-reported licenses, insurance, bonding, and certifications. It clearly distinguishes itself from sibling tools like get_quote or search_businesses by focusing on credential and verification data.

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 concrete trigger conditions: trust-sensitive verticals and literal user questions like 'are they licensed?' or 'are they insured?'. It does not explicitly discuss when to prefer a sibling tool such as query_business_agent, but the use case is clear 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?

Adds meaningful behavioral context beyond the annotations by describing the plain-text return content and including a critical warning: the URL is for the customer to open, not for the agent to fetch or follow. This is valuable operational guidance that the idempotentHint and destructiveHint annotations do not convey.

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 well-structured sentences with no filler: the first front-loads the return value and its contents, and the second carries the URL caution and timing guidance. 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?

Complete for a two-parameter tool with full output schema and annotations. The description covers what is returned, when to call it, and the key behavioral constraint about not following the URL, leaving no critical 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 100%, so the baseline is 3. The description reinforces that offer_id comes from get_quote and relates to a priced offer, but does not add parameter-level detail beyond what the schema already provides.

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

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

States a specific verb and resource: returns a plain-text summary of a priced offer plus a customer-facing URL, listing the exact contents (service, amount, currency, cancellation policy, price validity). It also distinguishes itself from the get_quote/booking flow by requiring an existing offer_id and a user ready to review or continue.

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 clear usage context: use after get_quote or a booking flow has produced an offer_id and the user is ready to review/continue with a priced offer. It does not explicitly name alternative tools or state when-not-to-use cases, so it falls just short of full routing guidance.

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

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

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?

The description adds meaningful behavioral context beyond the annotations: quoting a non-listed name silently falls back to an estimate with no offer, and exact prices require a service marked payable. This is important failure-mode information that neither the idempotentHint nor destructiveHint annotations convey.

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 first states the function, the second gives the critical usage ordering, and the third explains the failure mode. The most actionable information is front-loaded, and there is 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?

Given that the tool has one simple required parameter, an output schema, and rich sibling-tool context, the description covers purpose, ordering, dependencies, and failure behavior. Nothing essential is missing for an agent to correctly select and invoke this tool.

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

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

The schema already describes the only parameter, slug, as 'Business slug identifier' with 100% coverage. The description does not add additional parameter-level detail, so the baseline of 3 is appropriate; the schema carries the burden for this dimension.

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 what the tool does: 'Lists the services a business has configured, with their prices and the exact arguments to quote each one.' It names a specific verb, resource, and output details, and further distinguishes itself from get_quote and get_payment_handoff_url by explaining its role in the quoting flow.

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 'Call this BEFORE get_quote' and explains the dependency: the service name must match a configured service, and only payable services return an offer_id for get_payment_handoff_url. It also warns about the silent fallback to an estimate, making the when-to-use guidance remarkably 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?

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 adds concrete behavior beyond the annotations: it returns a 'pending_offer reservation,' sends a '6-digit confirmation code' to the customer, expires in 15 minutes, and clarifies idempotent reuse semantics by stating the original reservation is returned without resending the code. This materially enriches what the agent knows beyond readOnly/idempotent 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 compact and front-loaded with the core purpose, followed by behavior, expiry, and idempotency. Every sentence earns its place and none repeat what the schema or annotations already state redundantly.

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, the rich input schema, the output schema, and the annotations, the description covers the essential operational behavior: what it returns, how confirmation codes are delivered, the 15-minute expiry, and idempotency semantics. An agent has enough information to select and invoke it correctly.

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

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

Schema description coverage is 100%, so the schema already documents all parameters and their semantics. The description adds no new parameter-level meaning beyond what the schema provides, so the baseline score of 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Reserve a time slot on an active configured calendar.' It clearly distinguishes this from confirmation by stating it returns a 'pending_offer reservation' and sends a confirmation code, which implies the reservation is not yet confirmed and therefore differs from 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 implies usage context—reserving a slot from an active calendar, then later confirming—but it never names an alternative tool or states when to prefer confirm_booking or get_availability. An agent must infer the workflow from the sibling list and the word 'pending_offer,' so the guidance is implied rather than explicit.

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

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

The description adds useful behavioral context by noting the tool returns matches with slugs and restricts results to registered businesses. However, with readOnlyHint false and idempotentHint true, the description does not clarify potential side effects or lack thereof; it relies mostly on the annotations for 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?

Two sentences with no filler. The core action is front-loaded, the return value is specified, and the sequencing instruction earns its place by helping the agent decide when to call it.

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 low-complexity search tool with a full input schema and an output schema, the description covers the essential purpose, result content, and when to call it. It could be slightly more explicit about its relationship to query_business_agent or other search-adjacent siblings, but overall 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?

Schema description coverage is 100%, so the schema already fully documents 'search' and 'location'. The description restates that there is an optional location filter but does not add meaningful meaning beyond the schema, so the baseline 3 applies.

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

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

The description states a specific verb ('Find'), a clear resource ('registered businesses'), and the criteria ('by search term and optional location'). It also distinguishes the tool from the many sibling tools by noting it returns slugs and should be called before business-specific tools.

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

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

The description gives explicit when-to-use guidance: 'Call it before the business-specific tools.' This gives the agent a clear trigger and sequence. It does not explicitly name alternative search-like tools such as query_business_agent or state when not to use it, so it stops short of a full 5.

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

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

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.