Servana

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

Annotations already declare readOnly=true, idempotent=true, destructive=false, so the safety profile is covered. The description adds real behavioral context: the return shape ('per business, whether it replied and the latest reply') and the hard precondition that refs must originate from send_message_to_vendor. It does not say whether results reflect live or cached reply state, which is a minor gap for a polling-style tool.

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 tight sentences loaded front-to-back: trigger condition, required input with provenance, expected output, then exclusions. Every clause earns its place with no restatement of the name or title.

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 carries the return-value burden and does so ('per business, whether it replied and the latest reply'). Combined with annotations covering the safety profile and full schema coverage of the sole parameter, the definition is nearly self-sufficient; only freshness/caching of reply data is unstated.

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% and the single parameter is already documented, so the baseline is 3. The description goes further by specifying provenance ('Pass the enquiry_refs that send_message_to_vendor returned'), which tells the agent where valid values come from — meaningfully more than the schema's type/maxItems 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?

States a specific verb and resource (check whether a business replied to an enquiry) and anchors it to the producing sibling send_message_to_vendor. An agent can distinguish it from search_vendors/get_vendor without opening any 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?

Explicit when-to-use (user asks whether a business answered an enquiry sent earlier in this conversation) plus explicit when-not-to-use (enquiries sent outside this conversation or without a ref) and an anti-pattern warning ('never guess a ref'). Nothing is left to inference.

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

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

Annotations cover the safety profile (readOnly, idempotent, non-destructive), and the description adds behavior the annotations cannot: the confidence tiers and their sample-size thresholds, that a category-wide median is used, and the hard constraint to label output an estimate rather than a quote.

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?

Front-loaded with the triggering user utterance, then return shape, then the labeling constraint and the sibling exclusion. Dense but every clause earns its place; the confidence-level parenthetical is the only slightly heavy passage.

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?

There is no output schema, so the description must carry return semantics, and it does: a rough range, a confidence level with defined thresholds, and an explanation naming the sample. Combined with full schema coverage, an agent has everything needed to call and interpret 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?

Schema description coverage is 100%, so all five parameters (including the city/state slug conventions and the hours-vs-job_size precedence) are already documented in the schema. The description adds only an illustrative query, not new parameter meaning, 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?

States a specific verb (estimate) and resource (local service cost in a city) with a concrete example query. It explicitly distinguishes itself from the sibling get_vendor, so an agent can route without opening either 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?

Gives explicit when-to-use ('when the user asks what a local service costs in a city') and when-not ('Do not use for one business's prices; use get_vendor'), naming the alternative tool. Nothing is left to inference.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false, covering the safety profile. The description adds value beyond that by disclosing the shape of the result (services, prices, rating, claim status, AI-message acceptance), which matters since there is no output schema. It does not mention auth or rate limits, so it stops short of a 5.

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, both front-loaded with the operative condition first ('Use this when...') and the exclusion second. No filler or restated boilerplate.

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

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

For a read-only lookup with a single fully-documented parameter and no output schema, the description supplies the missing return-field information (services, prices, rating, claim status, messaging acceptance) plus precise usage routing. Nothing an agent needs to call it correctly is absent.

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?

There is a single parameter at 100% schema coverage, and the schema already documents that vendor_slug comes from search_vendors results or a servana.ai URL. The description echoes this same sourcing without adding format or syntax detail, so the schema is doing the heavy lifting — baseline 3.

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 (get one specific business) and enumerates exactly what the profile contains: services, prices, rating, claim status, and AI-message acceptance. It also explicitly distinguishes itself from the sibling search tool with 'Do not use to search for businesses.'

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

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

It states a clear trigger ('when the user asks about one specific business from search_vendors results or a servana.ai page') and an explicit exclusion ('Do not use to search for businesses'), effectively routing the agent between this tool and search_vendors.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered; the description reinforces it with 'It sends nothing' and adds useful behaviour the annotations cannot express — it surfaces a pre-filled form for the user to check and send. Minor gap: no detail on what happens if details are incomplete.

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?

Front-loaded with the trigger condition and limits, and every sentence carries routing or behavioural information. Slightly padded by restating the non-sending point after already describing the user-confirmation form, but nothing 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?

For a non-mutating form-preparation tool with no output schema and full schema coverage, the description covers trigger, limit, alternatives and the fact that nothing is sent. What the tool renders on success is only loosely described, but that is largely inferable.

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 all six parameters including the nested details object are already documented with field keys and the 'never invent' guidance. The description only gestures at fields ('date, area, size and so on') without adding syntax or constraints, so 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?

States a specific verb and resource (prepare a quote request for 1-3 Servana businesses) and explicitly scopes it against siblings by saying it should be preferred over a free-text message and limited to businesses returned by search_vendors. An agent can distinguish this from request_quote and send_message_to_vendor without opening a 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?

Gives explicit when-to-use (user wants quotes/availability), when-not-to-use (businesses not returned by search_vendors), and a named alternative behavior (free-text message) that this should be preferred over. The prerequisite that slugs come from search_vendors is stated up front.

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 the write/open-world/destructive/non-idempotent profile, so the bar is lower. The description adds real context beyond that: it emails the user the businesses' replies, and on missing details it returns which fields are absent with a directive to ask the user rather than invent. It stops short of explaining the irreversible/destructive nature flagged by 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?

Four tight sentences, front-loaded with the use condition, then behavior, then validation handling, then the exclusion. No filler; every sentence changes how an agent would 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?

No output schema exists, yet the description covers the trigger, side effect (emails replies), missing-field handling, and negative scope. Only the semantics of a few secondary parameters are left thin, which is minor for a well-scoped workflow 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 coverage is only 29%, so the description carries more burden. It clarifies the 1-3 business limit (mapping to vendor_slugs bounds) and that details are the fields the businesses asked for, but says nothing about service, notes, or the customer_* fields. Partial compensation for a low-coverage 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?

States a specific verb and resource (send an approved structured quote request to 1-3 Servana businesses) and ties it to the originating sibling, the prepare_quote_request form. It also explicitly carves out what it is not (no booking, no payment), so an agent can distinguish it from siblings without opening a 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?

Gives an explicit trigger (user approved a structured quote request, usually from prepare_quote_request) and explicit exclusions ("Do not use to book or pay"). The alternative source of requests is named, leaving nothing to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered structurally. The description adds the routing behavior (returns a slug consumed by other tools) and the boundary that it is not for online products or emergencies, which is useful context beyond the annotations, though it says nothing about result count or ambiguity handling.

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?

Front-loaded with the trigger scenario, then the skip-list, then exclusions. The middle sentence enumerating eight slugs is long but each slug earns its place by preventing an unnecessary call; overall it is dense rather than padded.

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 lookup with no output schema, the description covers the trigger, the routing purpose, and the negative boundaries, which is most of what an agent needs. It could state what a match returns (single slug vs ranked list) when the query is ambiguous, but the coverage is otherwise solid.

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% and the schema already specifies that the query is a task description, not a category name. The description's embedded examples reinforce the expected input style but add no syntax or format detail beyond the schema, 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 states a precise verb+resource: it converts a user's described in-person local service into Servana's category slug. It explicitly names the downstream consumers (search_vendors, estimate_service_request), so an agent can distinguish it from its siblings without opening any 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?

It gives explicit trigger conditions with example utterances, an explicit skip-list of eight known slugs with what each covers, and explicit exclusions (online products, emergencies, medical/legal/financial advice). When-to-use, when-not-to-use, and the alternative path are all present.

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 flag this as a non-read-only, non-idempotent, open-world, destructive action. The description adds substantial context beyond that: Servana emails the user when the business replies, the 3-business fan-out limit, the requirement to show the user the exact message and get approval first, and the exclusion of businesses not accepting AI-assistant messages.

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?

Front-loads the trigger condition and keeps each sentence functional (usage, mechanics, fan-out, follow-up, prerequisites, exclusions). It is dense and slightly long, but no sentence is redundant.

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?

No output schema exists, yet the description explains what the call produces (enquiry_refs to be used with check_enquiry_replies) and the reply flow. For a 6-parameter mutation tool with an open-world side effect, the guidance 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?

Schema coverage is 100%, so the baseline is 3, but the description adds meaning: pass customer_name/customer_email only when the user provided them, and that also_vendor_slugs brings the total to up to 3 recipients rather than the schema's maxItems of 2. It also ties the returned enquiry_refs to check_enquiry_replies.

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 ('sends the user's enquiry to the business') and scopes the trigger to a chosen Servana business. It clearly distinguishes itself from sibling check_enquiry_replies, which it hands off to via enquiry_refs.

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 ('user has chosen a Servana business and asks you to contact it, request a quote, or ask about availability') plus explicit when-not ('Do not use to confirm a booking or take payment... or for businesses marked as not accepting AI-assistant messages'). It also names the follow-up tool (check_enquiry_replies) and the prerequisite approval step.

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