Appointment Booking

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds essential behavioral context beyond that: it does NOT fetch the URL, is free, takes ~20ms, and only classifies the URL shape rather than confirming liveness. This fully informs the agent of side-effect-free, limited 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 long but well-organized with clear sections (core purpose, examples, when to use, when not, cost, latency) and front-loads the essential purpose. Minor redundancy exists ('free' appears twice, 'sub-100ms' vs '~20ms'), but every section earns its place.

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

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

For a one-parameter read-only classifier with no output schema, the description fully covers what is returned (platform, smb_id, channels, country), how to decide next steps, and what the tool will NOT do. An agent has everything needed to call it correctly and interpret its role in the booking 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?

The schema already documents the single 'url' parameter with 100% coverage, so the baseline is 3. The description adds meaning with concrete example values ('https://cal.com/jane', 'https://www.opentable.com/r/acme-bistro') and shows exactly how the parameter maps into example tool calls, which helps the agent invoke it correctly.

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: 'pre-flight check for a booking URL' that 'classifies which booking platform a URL belongs to' and tells whether import_booking_url will accept it. It explicitly distinguishes itself from import_booking_url and verify_business, so an agent can immediately tell what this tool is for.

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 'WHEN TO USE' section says to call it 'the moment a user pastes a URL' and 'before you commit to a paid schedule_appointment,' and gives concrete fallback behavior for supported=true versus supported=false. The 'WHEN NOT TO USE' section explicitly names verify_business and import_booking_url as alternatives, leaving 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 cover readOnly/idempotent/non-destructive, and the description adds valuable context beyond that: the supply network is mostly sample data with [DEMO] entries, availability_window is not applied, no live calendars are held, and no key is required. No contradiction with 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 well-structured with a front-loaded core statement, labeled usage sections, example queries, and operational notes like cost and latency. Every section earns its place; the examples are repetitive but directly help with parameter mapping.

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?

Even without an output schema, the description conveys what the response contains (ranked candidates with an is_demo flag), warns how to treat sample data, and connects the tool to downstream scheduling/messaging usage. For a read-only search tool with strong annotations, this is 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 examples add real semantics by mapping natural-language queries to exact vertical values, location formats, and capability strings, and the schema itself documents availability_window's non-applied behavior. However, price_band and max_results receive only surface-level coverage, with no deeper explanation of ranking implications or formatting, so it falls just short of perfect.

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 opening sentence names a specific action (return ranked candidate businesses) and a resource (our supply network), while enumerating the matching criteria. It also differentiates the tool from discovery-focused workflows and sibling tools by framing it as the search step before scheduling or messaging.

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

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

Explicit WHEN TO USE and WHEN NOT TO USE sections tell the agent to invoke this before schedule_appointment or send_message when no SMB target exists, and to avoid it when a verified target is already known or when outside the supported verticals. This is strong routing guidance.

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

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

Annotations already mark it read-only and idempotent; the description adds valuable context: it requires a completed operation, returns the final receipt with cost and reason codes, is free, and has ~50ms latency. This goes well beyond the structured 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?

Every sentence earns its place: core action, use conditions, non-use conditions, cost, and latency. The WHEN TO USE/NOT format makes it skimmable and decision-ready without padding.

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

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

For a single-parameter read-only tool with rich annotations, the description covers the precondition, the sibling workflow, operational characteristics, and the content of the result. Nothing essential is missing for an agent 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?

Although the schema provides zero description coverage for operation_id, the tool description supplies the meaning implicitly: it is the ID of a completed operation, and its value comes from the workflow after get_status. This is sufficient for a single clearly-named parameter, though explicit format/source details would make it stronger.

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 ('Retrieve') and resource ('final OutcomeReceipt for a completed operation'), which clearly distinguishes it from get_status and other siblings. The description also enumerates what the result contains: cost and reason codes.

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 WHEN TO USE after get_status returns success/failure/partial, and WHEN NOT TO USE for pending/executing operations, naming get_status as the alternative. This gives an agent actionable routing logic 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 read-only, idempotent, and non-destructive behavior. The description adds meaningful operational context: cost is free, no API key is required, latency is ~50ms, and polling frequency is rate-limited. No contradictions with annotations.

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

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

The description is compact and well-organized: the core sentence is front-loaded, followed by clearly labeled when-to-use, when-not-to-use, cost, and latency sections. Every line contributes useful information without redundancy.

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

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

For a simple single-parameter polling tool, the description covers core purpose, polling guidance, rate limits, cost, and latency. It does not describe the shape of the returned status or values, but the absence of an output schema and the straightforward semantics make this a minor gap.

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

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

With schema description coverage at 0%, the description needed to compensate for the undocumented operation_id. It only restates that the operation is queried by operation_id, without explaining where the ID comes from, its format, or any example, so it adds little beyond the property name.

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 opening sentence states a specific action ('Query the current state') on a clear resource (in-flight async operation) keyed by operation_id. It is unambiguous, though it does not explicitly differentiate itself from the sibling get_outcome tool.

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

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

The 'WHEN TO USE' and 'WHEN NOT TO USE' sections provide explicit conditions: poll pending_async operations when no webhook has arrived or to check progress, and avoid polling more often than once per 10 seconds in favor of webhooks. This is clear, actionable guidance with exclusions.

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

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

Beyond the idempotentHint annotation, the description explains idempotency semantics ('calling twice returns the same smb_id'), discloses cost ('free, no credits'), latency (~600ms), and the email-verified key requirement. This is meaningful behavioral context that annotations do not provide. No contradiction with 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 longer than average but structured with clear sections (purpose, examples, WHEN TO USE, WHEN NOT TO USE, cost, latency). Some redundancy exists between the example queries and the WHEN TO USE patterns, but the examples earn their place by showing parameter mapping.

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 an 8-parameter tool with no output schema, the description tells the agent everything needed: the core transformation, idempotent behavior, supported platforms, success path to schedule_appointment, and exclusions. No critical operational detail 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 the schema documents all 8 parameters. The description adds value with concrete example user queries mapped to exact parameter values, demonstrating how to populate booking_url and vertical for different platforms. This goes beyond the schema's dry constraints.

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 states a specific verb ('Turn') and resource ('public booking URL') into a concrete artifact ('callable smb_id'), and immediately connects to sibling tools. It distinguishes itself from find_business in the WHEN NOT TO USE section, so the agent understands exactly what this tool is and is not.

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?

WHEN TO USE and WHEN NOT TO USE sections are explicit, with example user queries and routing to find_business for non-URL requests. It also directs to /supply/platforms for unsupported websites, leaving no ambiguity about when to invoke this tool.

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

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

Annotations already mark it readOnly and idempotent, and the description adds complementary context: it does not promise an accuracy percentage, returns exact vs range, requires no key, and has ~100ms latency. No contradiction with 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 core behavior is front-loaded, and the formatted examples, usage guidance, cost, and latency each add non-redundant information. It is longer than minimal but every section earns its place.

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

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

With no output schema, the description covers return behavior (fixed vs range, no accuracy promise) and operational constraints (cache, key-free, latency), but it does not spell out the exact output field names beyond cost_range. This is a minor gap in an otherwise complete definition.

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

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

With 50% schema coverage (operation is undescribed), the examples compensate by showing valid operation values and the nested params shape. It could go further by enumerating valid operation names or constraints, but it adds substantial meaning beyond the bare schema.

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

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

The description states a specific verb and resource: it returns cost, latency, and success-probability estimates for a proposed call before execution, and even clarifies fixed vs min/max pricing. This clearly distinguishes preview_cost from its siblings, none of which are preview/cost tools.

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

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

It provides explicit WHEN TO USE ('under a budget constraint...before any operation') and WHEN NOT TO USE ('do not use in a hot loop...cache for at least 60 seconds'). The example queries also give concrete triggers.

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?

With annotations already marking this as readOnlyHint=false, destructiveHint=true, and idempotentHint=false, the description still adds valuable behavioral context: routing fallback (native booking -> voice AI/web form), async execution via get_outcome, and cost/latency estimates. It does not explain hold/confirm semantics or side-effect boundaries, so a small gap remains.

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 longer than average but well-structured with headings such as WHEN TO USE, COST, LATENCY, and EXECUTION, and the purpose is front-loaded. Some repetition of 'book/reschedule/cancel' exists across the opening, examples, and usage rules, but the content remains scannable and useful.

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 (8 parameters, nested objects, no output schema), the description provides necessary routing, cost, latency, and async guidance, but it lacks parameter-level detail and does not explain what get_outcome returns. Since no output schema exists, the missing return-value information is a meaningful gap.

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

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

Schema description coverage is only 25%, so the description must compensate, but it only illustrates smb_id, action, and service. The example calls omit required or semantically important fields: a 'cancel' example has no existing_appointment_id, and a time-based booking example has no requested_time, which weakens the tool's value as parameter documentation.

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

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

The description opens with a concrete verb set and resource: 'Availability lookup, hold, confirm, reschedule, or cancel appointments with an SMB.' It is not a tautology, and it distinguishes itself from siblings such as find_business, verify_business, and get_outcome by stating its role in the booking workflow and pointing to those tools where relevant.

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 explicit WHEN TO USE and WHEN NOT TO USE guidance, including the requirement for a verified smb_id and the instruction to call find_business and verify_business first if needed. It also tells the agent to use preview_cost for exact pricing and get_outcome for async results, making routing decisions 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 mark the tool read-only and non-destructive. The description goes further by disclosing it runs 6 internal checks, reports a pass count, does not probe individual tools, requires no key, costs nothing, has ~200ms latency, and has a rate-limit consideration. No contradiction with 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 well-structured and front-loaded: purpose comes first, followed by an example, when-to-use/not-to-use rules, cost, and latency. Every section earns its place and contributes to an agent's operational decision-making.

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 no-parameter, read-only health check, the description is complete: it states scope, exclusions, usage timing, rate limits, authentication requirements, cost, latency, and expected outcome ('reports how many passed'). No output schema exists, but the description gives enough for an agent to interpret 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 tool has zero parameters and 100% schema coverage, so the schema fully defines the calling contract. The description reinforces this with an example call of self_test({}) and adds no unnecessary parameter details, which is appropriate for a no-parameter tool.

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

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

The description clearly states a specific action and resource: a 'Service health probe' that 'runs 6 internal checks and reports how many passed.' It explicitly says it does NOT probe each tool individually, which differentiates it from status/verification siblings and removes ambiguity about its scope.

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: at agent startup, before high-stakes task sequences, and after unexpected errors. It also gives a WHEN NOT TO USE rule (do not call more than once per minute in production) and clarifies that per-tool probing is out of scope.

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 mark the call as read-only, idempotent, and non-destructive, so the added value comes from the statements that this is a directory lookup and does not contact the business. It also discloses cost and latency, which help an agent decide whether this call is the right choice under 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 content is organized into short labeled sections with the core semantics first and no filler. The example, use guidance, and cost/latency notes each serve a distinct decision-making purpose.

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?

Without an output schema, the description names the returned business facts (contact channels, capabilities, last-verified date) so an agent knows what to expect. It could be fully complete by specifying what happens for an unknown smb_id or an unverified capability, but the core call context is well covered.

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 descriptions are 0% covered, so the description must compensate; it does through a concrete example mapping smb_id and capability_to_verify to values. However, it never states that capability_to_verify is optional or whether it expects a controlled vocabulary, leaving some ambiguity for a non-example call.

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 pair ('look up what we know about a business') and immediately clarifies the non-contact directory nature, setting it apart from any live-action tool. The WHEN NOT TO USE section also disambiguates it from find_business, which is the closest sibling.

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

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

It explicitly names when to use the tool (before communications/scheduling with unverified SMB identifiers or when confirmed capability is required) and when not to use it (within 24 hours after find_business). The example user query grounds the trigger in a realistic agent task.

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