Look up Servana's service categories by free-text description (e.g. 'someone to fold my laundry', 'deep clean my apartment'). Use this first when you don't already have an exact service slug: it maps everyday requests to the category slug search_vendors and estimate_service_request expect.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Free-text description of what the user needs (a task, not a category name) |
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.
Add one secure layer between your agents and this server.
Each tool targets a distinct action: estimating pricing, fetching a single vendor, mapping free text to service categories, searching vendors, and messaging vendors. Even though search_vendors and get_vendor both involve vendor data, one returns lists based on criteria and the other retrieves a specific profile, so there is no ambiguity.
All tool names follow a consistent verb_noun pattern in snake_case: estimate_service_request, get_vendor, search_services, search_vendors, send_message_to_vendor. The verbs (estimate, get, search, send) are clear and match the action.
Five tools is well-scoped for a service discovery and booking directory. Each tool serves a necessary step in the user workflow without redundancy, and the count is neither too sparse nor overloaded.
The tool surface covers the full lifecycle for a user: discovering service categories, finding vendors, getting price estimates, viewing vendor details, and contacting vendors. There are no obvious missing operations that would prevent an agent from accomplishing the server's intended purpose.
