Servana

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so safety is covered. The description adds significant behavioral context: it emphasizes the heuristic nature, explains that vendor-specific pricing is not reflected, and details the confidence level thresholds and fallback to a median. This goes beyond annotations and helps the agent interpret results accurately.

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 front-loaded with the core purpose. It packs essential information (heuristic nature, confidence levels, fallback logic) into a single, well-structured sentence. While it is a bit lengthy due to the detailed confidence explanation, every sentence adds value and no redundant content exists.

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 what the response includes (confidence level and explanation string) and describes the fallback behavior. It also clarifies the heuristic nature, which is critical for correct use. It could provide a sample response or exact field names, but for a tool of this complexity, the information is adequate for an agent to call and interpret 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?

The input schema provides complete descriptions for all five parameters (100% coverage), including slugs, enums, and defaults. The description does not add extra detail about parameter formats or constraints, so it does not enhance semantics beyond the schema. Baseline of 3 is appropriate given high schema coverage.

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

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

The description states a specific action ('Get a rough price estimate') for a specific resource ('service in a given city') and clearly distinguishes it from vendor-specific quotes. It also mentions the basis (vendors' posted rates) and that it's heuristic, which differentiates it from sibling tools like search_vendors or get_vendor.

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 it (for rough estimates) and clarifies that it is not a quote, which hints at not using it for actual pricing. However, it does not explicitly name alternative tools or state conditions for choosing this over siblings like search_vendors or send_message_to_vendor. The confidence-level explanation gives some context on reliability, but explicit guidance is missing.

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 operation read-only, idempotent, and non-destructive. The description adds that this is a public profile fetch and lists the fields an agent can expect, though it does not describe error behavior for a missing or invalid slug.

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 one tight, front-loaded sentence that names the action, subject, and expected contents without redundant words. It carries exactly the information an agent needs at a glance.

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 explicitly lists the return contents: name, description, services and pricing, verification status, rating, and page URL. Combined with the detailed parameter schema and safety annotations, this is complete for a simple read-only lookup 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 100%: the single parameter is required and clearly documented as the vendor slug from search_vendors or a URL. The tool description adds no additional parameter meaning, 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 uses a specific verb ('Get'), names the exact resource ('one Servana vendor's public profile'), and enumerates the returned fields. The singular scoping distinguishes it from search-oriented siblings like search_vendors and search_services.

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 parameter description clarifies that vendor_slug comes from search_vendors results or a servana.ai URL, implying this tool is used after identifying a specific vendor. It does not explicitly contrast it with search_vendors or other alternatives, but the intended context is 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 declare readOnlyHint, idempotentHint, and destructiveHint false, covering the safety profile. The description adds that it maps everyday requests to category slugs, which is meaningful behavioral context beyond the annotations. It does not mention edge cases like no matches, but that is a minor gap for a simple lookup.

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 the main purpose front-loaded followed by usage guidance. However, the final clause is grammatically awkward ('the category slug search_vendors and estimate_service_request expect'), which slightly detracts from clarity despite the brevity.

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 lookup tool with annotations covering safety, the description provides purpose, input format, and how the output is consumed downstream. An agent can invoke it correctly and know what to do with the result. Minor gaps like result multiplicity or failure behavior are not blocking.

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 concrete examples ('fold my laundry', 'deep clean my apartment') and clarifies that the query is a task description rather than a category name, going slightly beyond the schema field description.

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 ('Look up'), resource ('Servana's service categories'), and input type ('free-text description'). It differentiates the tool by explaining the output is a category slug expected by search_vendors and estimate_service_request, making its role unambiguous.

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

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

Explicitly directs the agent to 'Use this first when you don't already have an exact service slug', providing a clear condition and rationale. It also names the downstream tools that consume the output, so the agent knows how the result is used.

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 idempotentHint, so the safety profile is covered. The description adds useful behavioral context: it returns a listing of local businesses with specific fields such as verification status, rating, pricing, and page URLs, which helps an agent anticipate results.

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 entire meaning fits in one front-loaded sentence with no filler. The search scope, criteria, and return fields are all presented efficiently.

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 bounded search tool with annotations covering safety, the description is complete: it states what is searched, what dimensions filter it, and what the result contains. No output schema exists, so explicitly listing the returned fields is especially valuable.

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?

Input schema coverage is 100%, so the schema already documents state, city, and service formats with examples. The description only restates the criteria at a high level and adds no new parameter-level meaning beyond the schema.

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

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

The description opens with a specific verb ('Search'), names the resource ('Servana's directory of local service businesses'), and defines the search dimensions (US state, city, service). It also lists return fields, making it clearly distinct from siblings like get_vendor and search_services.

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 the tool is for location/service-based directory lookups by stating the search criteria. However, it does not explicitly say when to prefer this over get_vendor or search_services, so the usage guidance is inferred rather than stated.

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 flag destructive behavior, but the description adds meaningful context beyond that: the vendor sees the message in their Servana inbox, and the action contacts a real business requiring the user's explicit approval. This explains the real-world consequence and approval prerequisite without contradicting the annotations.

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

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

The description is compact and front-loaded with purpose, followed by user-required content guidance and the approval warning. Every sentence earns its place, and there is no 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?

For a two-parameter messaging tool, the description covers the purpose, expected message content, vendor-side visibility, and the approval requirement. It is complete enough for an agent to invoke correctly, though it does not address post-send outcomes or error scenarios, which is a minor gap given the simple scope.

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 both vendor_slug and message are already documented structurally. The description reinforces that the message should include the user's needs and contact details, but it does not add new parameter information beyond the schema.

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

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

The description states a specific verb and resource: sending a message or booking enquiry to a Servana vendor on the user's behalf. It clearly distinguishes this from the sibling tools like search_vendors and estimate_service_request by focusing on direct vendor messaging and the user-approval requirement.

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

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

The description gives clear context for when to use the tool: when the user wants to contact a vendor with an enquiry. However, it does not explicitly contrast this with estimate_service_request or state when not to use this tool, so the usage guidance is implied rather than explicitly differentiated.

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