AssistAnt 24/7 pro directory

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

Annotations already declare a read-only, closed-world lookup, so the bar is lower. The description adds real behavior: commercial-only shops are filtered out unless segment='commercial', matching free repair guides are returned first, and each result carries a trust tier, distance, phone, profile link and Trust Card link. It does not describe ranking logic, pagination, or empty-result 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 location and fallback guidance is front-loaded and useful, but the middle of the description is a 43-item enumeration of service keys that largely duplicates the service enum already present in the schema. The plain-language glosses add some meaning, yet the bulk is redundant and makes the actionable guidance harder to locate.

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 11 optional parameters and no output schema, the description carries the burden well: it covers input fallbacks, default trade and segment, filter scoping, and what each result contains. Only minor gaps remain, such as default limit behavior and what happens when no pros match.

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 82%, so the baseline is 3, but the description goes further by explaining that 'trade' accepts plain words equivalent to 'service', that brand/appliance/problem are silently ignored for non-appliance trades, and that segment defaults to residential. These are interaction effects between parameters that the schema alone does not convey.

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 clause gives a specific verb and resource ('Find local service businesses near a US ZIP code, or a town + two-letter state'), which is clearly a location-based directory search. It distinguishes itself functionally from get_pro, get_pro_profile, and list_trades by being a multi-result proximity search, though it never names those siblings explicitly.

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 a concrete fallback rule: use town + state when no ZIP is known. It also states the exclusion condition for commercial-only shops and that brand/appliance/problem only apply to appliance trades. It stops short of naming alternative tools for lookups of a single known pro.

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=false, so the safety profile is covered. The description adds that the result is a full public listing and shows the URL shape, but stays silent on what happens when neither optional parameter is supplied or when a slug does not resolve.

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 tight sentence with no wasted wording. Its only structural weakness is leading with a cross-reference to a sibling instead of the tool's own action, pushing the useful information to the back half.

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 read-only lookup with no output schema and safety already covered by annotations, the description supplies enough to call it correctly. The remaining unknowns, such as behavior with zero arguments, are minor for a lookup of this simplicity.

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 50%: 'url' is described as 'Profile URL' while 'slug' has no description. The description compensates partly by giving a concrete URL template (https://assistant247.net/pros/<slug>) and stating either identifier works, but it does not explain precedence if both are passed.

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 resource and scope: 'one business's full public listing', retrieved by slug or profile URL. It is clear what the tool returns, but it opens by equating itself to the sibling get_pro_profile rather than stating its own distinct purpose, so it does not fully differentiate from that 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?

'Same as get_pro_profile' implies the two tools are interchangeable, which is mild guidance, but it never says when to prefer this one over get_pro_profile, nor when not to use it. No prerequisites or failure conditions are given.

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 establish readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description goes further by enumerating what the listing contains (services, specialties, trust tier, contact, bookability, nearby alternatives), which is meaningful behavioral context for a read 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?

A single sentence, front-loaded with the purpose before the field enumeration. The colon-list is dense but every item conveys return content, so little 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 simple single-parameter read tool with no output schema, the description compensates by enumerating the returned fields, so an agent knows what it will get back. Only the absence of explicit alternative routing keeps it from being fully 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?

With only one parameter and 0% schema description coverage, the description carries the full burden and does it well: it defines 'slug' as 'the last part of its profile URL'. That format hint is exactly the kind of semantics the bare 'string' schema lacks.

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 ('get one business's profile') and pins the lookup key ('by its profile slug'). The singular 'one business' implicitly distinguishes it from the plural find_pros, though no sibling is named outright.

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?

Usage is implied by the required lookup key — you need a profile slug to call it — but there is no explicit when-to-use guidance or reference to find_pros for discovery versus this tool for details. Adequate but leaves the routing decision 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 (readOnlyHint=true, openWorldHint=false), so the bar is lower, yet the description still adds real behavioral detail: the 25-mile radius, that counts are computed within that radius, that verified entries carry a date checked, and that results are sorted verified-first. Not stated is pagination or result caps for the list.

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 operation is front-loaded effectively in the opening clause, but the description then inlines the entire 40-value service enum, which is redundant with the schema and bloats the text. The example-query sentence earns its place; the enum dump does not.

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 burden of explaining returns and does so well: business count, verified count with date, most-named brands, and a verified-first list. An agent knows what it will get back, though pagination/limits on the list remain unspecified.

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% and the service enum is fully self-documenting, so baseline 3 applies. The description clarifies that 'service' accepts any town-page service and that the radius is fixed at 25 miles, but it also re-lists all ~40 enum values verbatim, which adds no meaning the schema does not already carry.

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+resource — count businesses of one service within 25 miles, count verified ones, surface top brands, and return a list — which is a distinctly richer operation than a plain lookup. However, it never names or contrasts against the sibling find_pros, whose 'list of pros' output overlaps with this tool's final element, so sibling differentiation is left to inference.

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 concrete routing cues via example questions ('who fixes appliances in Covington, LA?') and a clear selection condition — use this 'when no ZIP is known'. That is a genuine when-to-use signal, but it stops short of naming the ZIP-based alternative or stating when to prefer find_pros instead.

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=false, so safety is covered. The description adds genuinely behavioral detail beyond them: the counting is scoped to a 25-mile radius around each town, results are sorted most-first, and the trade defaults rather than being required. It does not say how the coverage boundary ("the directory covers") affects 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?

Two sentences, zero filler, with the substantive scoping (state, trade count, radius, ordering) front-loaded and the routing guidance second. Slightly dense as a single opening sentence, but nothing needs cutting.

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 does the work of sketching return values — town plus business count, sorted descending. For a 3-parameter read-only tool with full schema coverage that is sufficient, though it leaves the response shape (field names, whether zero-count towns appear) implicit.

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 state, trade, and limit are already documented including their defaults. The description restates the trade default and repeats the 25-mile notion rather than adding format or edge-case semantics. Baseline 3 applies when the schema carries the parameter burden.

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 resource (towns in one U.S. state) and qualifies it with the directory's coverage, a trade filter with a stated default (appliance repair), a 25-mile radius, and descending ordering. An agent can distinguish this from get_town_summary or find_pros without inspecting 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?

"Use it to pick a town for find_pros or get_town_summary" gives explicit downstream routing, making this a discovery entry point feeding two named siblings. It stops short of saying when *not* to use it, or what to do if the state has no covered towns.

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 read-only and closed-world annotations, the description adds exhaustive scope through "Every live trade" and discloses that a town-page path is present only where one exists. It gives useful result behavior for a simple listing, though it does not cover ordering or other response mechanics.

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 compact statements front-load the returned content and then explain how to use the key, with no filler. Despite the fragmentary wording, the scope and workflow remain easy to understand.

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 zero-argument, annotated read-only list tool, the definition supplies scope, principal output fields, conditional path behavior, and downstream key usage. This adequately compensates for the absent output schema for purposes of selecting and invoking the 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?

There are no input parameters, so the zero-parameter baseline of 4 applies. The description additionally clarifies the semantic role of a returned service key as input to find_pros.

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?

Defines the listing as every live trade and specifies the service key, plain label, and optional town-page path included for each. The reference to find_pros also distinguishes its directory-enumeration role from professional search.

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 tells the agent to pass a returned key to find_pros as its "service" input, providing a concrete downstream workflow. It does not explain when other siblings such as list_towns or get_town_summary would be preferable, but the main use case 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=true and openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavioral context: the data is derived from real repair records and normalized as a share of diagnosed jobs, and pro_only results carry a safety restriction on DIY advice. It doesn't describe result ordering or how ties/sparse samples are handled.

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 scope and the disclaimers are front-loaded and every clause carries information, but the opening sentence is long and stacks appliance list, brand list, and the share-of-jobs metric into one dense clause. Slightly tighter phrasing would scan faster without losing content.

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 does the work of explaining what comes back (findings as a share of diagnosed repair jobs) and flags the pro_only safety dimension. That covers the essentials for a read-only lookup; only fine-grained output details like ordering or minimum sample size are 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?

Schema coverage is 67%, and the description meaningfully extends it: it enumerates the accepted brands (samsung, lg, whirlpool, ge, frigidaire, maytag, kenmore, hisense) that the schema only illustrates with one example, and explains that problem takes the customer's own phrasing and scopes results to that complaint.

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 returns what technicians actually found when diagnosing specific appliances, expressed as a share of diagnosed repair jobs from real repair records. It names the exact appliance set and brand set, and explicitly disclaims what it is not ("It is not a reliability ranking"), which separates it from the pros-oriented siblings.

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 triggering questions ("what usually goes wrong with my Samsung fridge?") and shows the alternative invocation shape when the problem parameter is supplied ("my Samsung fridge is not making ice, what is it usually?"). It also states a clear usage boundary: pro_only findings are gas/240V/sealed-refrigerant jobs and must not be offered as DIY.

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