qasper

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

Annotations already declare openWorldHint and destructiveHint, signaling that the tool may take consequential actions. The description adds useful context by noting the agent can invoke its configured business tools for bookings and inquiries, explaining what the agent might do beyond a simple Q&A. However, it does not explicitly warn that a question could trigger a booking or other state changes, relying on the annotation to carry that risk.

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

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

The description is two sentences with no fluff; the first states the action and resource, the second gives usage guidance. Every phrase earns its place, and the most critical information (prerequisite slug) 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?

Given the tool's open-ended nature and absence of an output schema, the description does enough by explaining the agent's access to business tools and the required slug. It lacks an explicit note about response format, but the 'same chat path' phrase implies a conversational response, and the schema covers the input contract.

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 provides 100% coverage for all three parameters, including descriptions for slug, question, and conversationId. The description reinforces the need to copy the slug verbatim from specific source tools but adds no new semantics beyond the schema, 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 clearly identifies the tool as a general-purpose conversational interface to a specific business agent ('Ask one specific Qasper business agent'), distinguishing it from the structured sibling tools like book_appointment and check_availability. The reference to the public agent page further clarifies the interaction model.

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 a firm prerequisite: use only after selecting a business and copying the exact slug from search_businesses or get_business_info, which tells the agent when this tool is appropriate. It also explains the agent's capabilities (services, pricing, availability, bookings) but does not explicitly exclude using sibling tools for those same actions, so the guidance stops short of a full decision tree.

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

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

Beyond the destructiveHint annotation, the description discloses critical behaviors: the status field semantics ('pending', 'confirmed', 'completed'), the deduplication behavior of clientRequestId on retries, and the warning not to misreport 'pending' as 'confirmed'. It also details the address requirement condition, adding rich behavioral context.

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

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

The description is front-loaded with the core purpose and then delivers dense, high-value guidance. Every sentence addresses an essential operational detail—status handling, feature gating, address requirements, and idempotency—without redundant filler.

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

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

With no output schema, the description compensates by explaining return fields (reference number and status). It covers prerequisites, conditional requirements, and error-prone customer messaging. For a complex mutation tool with 9 parameters, this description is remarkably 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?

Even though schema coverage is 100%, the description substantially enriches parameter semantics. It explains that clientRequestId must be generated once and reused on retries to avoid duplicate calendar events, that dateTime must come from check_availability to respect bookingStartPolicy, and that customerAddress is conditionally required.

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

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

The description clearly states the tool's function: 'Book an appointment with a local service business. Creates a booking record and adds the appointment to the business calendar.' This specific verb and resource combination distinguishes it from siblings like check_availability and send_inquiry.

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 conditions: 'ONLY call this if the business has booking in its enabledFeatures array.' It also instructs to use a dateTime from check_availability and specifies when to provide customerAddress, giving clear when-to-use and prerequisite 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?

Beyond the readOnlyHint and openWorldHint annotations, the description discloses internal logic about bookingStartPolicy and maxParticipants. It clarifies that starts remain available until capacity is full, giving agents a precise mental model of the returned time windows. 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 tightly written with five sentences, each contributing new information: the core action, return value, capacity nuance, precondition, and fallback. There is no fluff or repetition, making it efficient for agents to parse.

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 explains the return type ('time windows') and the factors affecting it (bookingStartPolicy, maxParticipants). It also covers the prerequisite (enabledFeatures) and the alternative action, making the tool self-contained and actionable 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 input schema already provides detailed descriptions for all three parameters (100% coverage). The description adds domain context (bookingStartPolicy, maxParticipants) but does not add parameter-specific semantics beyond the schema. Baseline 3 is appropriate as the schema carries the parameter-level 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 uses a specific verb 'Check' and clearly identifies the resource: 'available appointment slots for a specific service at a local business on a given date.' It distinguishes from sibling tools like find_next_available_appointments by emphasizing the fixed date and business, and from book_appointment by focusing on availability only.

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 call: 'ONLY call this if the business has ''booking'' in its enabledFeatures array.' It also provides a clear alternative: 'If the business doesn't support booking, share their contact info from get_business_info instead.' This is exemplary 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?

Beyond the readOnlyHint and openWorldHint annotations, the description discloses that responses only include businesses with direct booking support and slots meeting bookingStartPolicy/remainingCapacity criteria. It also clarifies that an empty result does not mean no businesses exist, only that no bookable slots were indexed, adding critical interpretation context.

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 ideal (8 sentences), but every sentence serves a purpose: examples, exclusions, parameter guidance, response criteria, and fallback behavior. The primary purpose is front-loaded in the first sentence, and the length is justified by the tool's nuanced 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?

Given the absence of an output schema, the description explains response filtering criteria and empty-result interpretation. It covers when to use, how to extract parameters, what the response includes, and what to do when no results are returned, making it operationally complete 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?

While schema coverage is 100%, the description adds operational meaning by instructing the caller to extract structured search fields the same way as search_businesses and to pass service/activity wording in serviceQuery. This cross-reference and explicit assignment of serviceQuery goes beyond the schema's field 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 clearly defines the tool's purpose with a specific verb ('find') and resource ('next available bookable appointment starts') across local service businesses. It explicitly distinguishes itself from discovery tools like search_businesses by stating it should not be used for generic discovery, and provides concrete examples of triggering queries.

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 this tool ('ONLY when the user explicitly asks for availability, booking, the soonest appointment, or a specific appointment time') and when not to use it (generic discovery), naming the alternative tool (search_businesses). It also provides fallback instructions: if no results, call search_businesses before responding.

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

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

Beyond the readOnly and openWorld annotations, the description adds valuable behavioral details: it notes that profile images are only present if uploaded, identifies cardChips/cardChipGroups as UI-only and instructs to ignore them, and mentions that the slug is echoed for reuse. These disclosures go well beyond the structured annotations and greatly aid the agent's decision-making.

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 compact paragraph with each sentence conveying essential guidance: what fields are returned, how to use attributeDetails, which fields to ignore, and the slug echo behavior. No superfluous content; the structure is straightforward and 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?

Given the single parameter and no output schema, the description thoroughly explains the return contents and gives actionable guidance on using attributeDetails and ignoring UI fields. It is complete for the tool's purpose, with no additional clarification needed.

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 sole parameter 'slug' is fully documented in the schema with format and source instructions ('returned by search_businesses... copy it verbatim'). The description reinforces the reuse instruction but adds no new semantic meaning beyond the schema, so a baseline score of 3 is appropriate given the 100% schema coverage.

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

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

The description clearly states the tool's function: retrieving business information, and enumerates the specific fields returned (name, type, service area, etc.). It distinguishes this from sibling tools by focusing on a general business profile rather than specific aspects like services or pricing.

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 context that this tool is always available and that the slug should be sourced from search_businesses and reused verbatim. It also instructs the agent to use attributeDetails for reasoning about fit. However, it does not explicitly contrast with sibling tools like get_services or get_pricing, so exclusions are absent.

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

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

Annotations already provide readOnlyHint=true and openWorldHint=true. The description adds useful behavioral context such as 'Takes into account emergency requests, weekend rates, and other pricing rules' and 'Always available for any business,' which goes beyond the annotation hints and clarifies the tool's behavior regarding special pricing conditions.

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 front-load the core purpose, with no filler. The second sentence adds valuable context about availability and pricing rules 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?

The description adequately covers the tool's purpose and key behavioral nuances, and the schema handles all parameter details. It does not describe the return format, but given the simplicity of the tool and absence of an output schema, this is a minor gap that does not impair selection or 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 coverage is 100%, so baseline is 3. The description adds meaning by explicitly mentioning 'emergency requests' and 'weekend rates,' which maps to the isEmergency and requestedDate parameters, helping the agent understand how these parameters affect pricing beyond their 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 states the tool's function: 'Get a price quote for a specific service from a local business.' This is a specific verb+resource combination that distinguishes it from siblings like get_services (listing services) or book_appointment.

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 by mentioning emergency requests and weekend rates, but it does not explicitly state when to use this tool versus alternatives, nor does it provide exclusions. The phrase 'Always available for any business' offers some guidance but lacks direct comparison to sibling tools.

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

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

Annotations already declare readOnlyHint and openWorldHint, so the description's role is lighter. It adds valuable behavioral context: what the return contains (attributes plus universal serviceMode options), the refinement flow, and the conditional skip behavior. This is more than annotations alone provide, though not exhaustive (e.g., no error cases).

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 yet information-dense, with a clear front-loaded statement of purpose followed by actionable usage guidance and return summary. Every sentence earns its place; no filler or repetition of schema fields.

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 one simple parameter, no output schema, and strong annotations, the description covers all necessary aspects: when to call, what it returns, how to handle the refinementAvailable flag. It is complete for an agent to invoke the tool correctly in a conversation flow.

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 provides 100% coverage of the single parameter, with a detailed enum and clear guidance on how to pick the value. The description itself adds little beyond 'specific subcategory', but because the schema fully handles meaning, 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 starts with a specific verb ('List'), a clear resource ('refinement dimensions'), and a scope ('for a specific subcategory'). It distinguishes this tool from siblings by explicitly mentioning search_businesses and the 'before' relationship, making the purpose unmistakable.

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 explicit when-to-use guidance: 'Call this BEFORE search_businesses when the user's request is broad', with concrete examples. It also specifies the interaction pattern (politely ask whether to narrow, offer all results option) and the conditional fallback ('If refinementAvailable is false, skip refinement and go directly to search_businesses'). This is exemplary guidance.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, but the description adds value by listing the exact return fields (price ranges, booking start policy, address requirement) and the 'always available' guarantee, which provides behavioral context beyond the annotations. It does not disclose edge cases like invalid slugs, but that is covered by the schema's 'exact URL slug' instruction.

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?

A single, information-dense sentence that front-loads the primary action ('Get the service catalog') and lists the key return elements. Every word adds value, and there is no redundancy or filler.

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

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

For a simple read-only tool with one fully-documented parameter, no output schema, and strong annotations, the description sufficiently covers the return content and availability. It explains what the tool returns and confirms it works for any business, making the tool fully understandable 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?

Schema description coverage is 100% for the single 'slug' parameter, with clear guidance to copy it verbatim from search_businesses or get_business_info. The tool description itself adds no additional parameter semantics, so the baseline 3 applies.

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

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

The description clearly states 'Get the service catalog for a local service business' and enumerates specific content (service names, durations, price ranges, etc.), which strongly distinguishes it from sibling tools like get_pricing (pricing-only) or get_business_info (business details). The verb+resource+scope pattern is clear and specific.

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 with 'Always available for any business' implying no prerequisites or restrictions. However, it does not explicitly mention when to use it versus alternatives (e.g., 'use this instead of get_pricing when you need the full service catalog'), so it lacks explicit exclusion guidance.

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

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

Beyond the readOnlyHint and openWorldHint annotations, the description reveals key behaviors: server handles geocoding/ranking, results may include non-bookable businesses, enabledFeatures semantics, agentChatAvailable gating, UI-only fields to ignore, and slug reuse. This is rich contextual behavior not inferable from the annotations alone.

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

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

The description is excessively long and repetitive, especially the output-ordering rules which are reiterated multiple times ('MUST include', 'rank and present', 'MUST NEVER appear', 'MUST NOT omit'). While structured in paragraphs, it could be substantially shortened without losing critical information, making it not concise.

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 thoroughly explains return-value fields (enabledFeatures, agentChatAvailable, attributeDetails, cardChips, slug) and instructs the agent on which to ignore or reuse. It also covers fallback behavior (get_refinement_options) and edge cases (map viewport overrides), making it effectively complete for this complex 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 provides complete descriptions for all 9 parameters (100% coverage), so the baseline is 3. The description adds valuable guidance on caller responsibility for extracting subCategory/locationText/countryCode, when to pass latitude/longitude, and how to populate attributeFilters from get_refinement_options. This elevates it above the baseline, though some points merely restate schema text.

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 function statement: 'Search for local service businesses by structured fields,' and immediately lists concrete use cases ('find me a dentist in Paris'). It clearly differentiates this discovery tool from siblings like check_availability and get_refinement_options by defining its role as the first search source.

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 the tool ('Use this as the first search source whenever the user wants to find, compare, recommend...') and when not to skip it. It contrasts with alternatives such as get_refinement_options for broad requests and clarifies that availability search (e.g., check_availability) is only for explicit booking, availability, or appointment-time queries.

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 annotation destructiveHint: true indicates potential side effects, and the description adds context by explaining that the business owner will be notified immediately via all enabled channels and will contact the customer directly. This goes beyond the annotation by describing the specific behavioral outcome, though it could further emphasize the irreversibility of the notification.

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, front-loaded with the core purpose, followed by usage context and a critical prerequisite. Every sentence earns its place; there is no wasted wording.

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

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

For a send-type tool with no output schema, the description covers the action, the prerequisite, and the immediate side effect. It lacks explicit detail about the return value or idempotency behavior, but the annotations (idempotentHint: false) and the schema's clientRequestId hint at retry semantics. Overall, it is adequately complete for a well-annotated 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?

Schema description coverage is 100%, so the schema already documents all six parameters. The tool description adds minimal parameter-specific guidance beyond the schema (e.g., 'visual details about damage, location, severity, and urgency' is in the message property description). The baseline of 3 is appropriate when 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 uses a specific verb ('Send a general inquiry') and clearly states the resource ('local service business'). It explicitly distinguishes itself from bookable services ('doesn't fit a specific bookable service'), which differentiates it from sibling tools like book_appointment and get_pricing.

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 when-to-use scenarios (question, custom quote, issue that doesn't fit a service) and a critical when-not-to-use condition ('ONLY call this if the business has 'inquiry' or 'email_inquiry' in its enabledFeatures array'). It implies alternatives for bookable services but does not explicitly name sibling tools.

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