Finder: find local tradespeople

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

Annotations only declare the flags (readOnlyHint=false, destructiveHint=false, non-idempotent); the description adds substantive behavior: answers/description are persisted briefly server-side behind the link, the consumer validates then submits on the town page, and contact details are never to be included. This explains why the operation is not read-only in a way the annotations cannot. It does not state permissions or the exact lifetime/scope of persistence.

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 short sentences with no filler, and the return values are front-loaded in the first sentence. The phrasing is choppy in places, notably the standalone fragment 'Never contact details', which takes effort to parse, but the overall length is proportional to the tool's complexity.

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 list the four returned items, plus privacy handling for the transient inputs. It leaves 'connected' and the exact composition of prefill_link undefined, but an agent has enough to invoke the tool and interpret the result.

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 baseline is 3, but the description adds real meaning: it explains that answers and description feed prefill_link, that the description is held only briefly and never embedded in the link, and reinforces the 'no contact details' constraint. It also clarifies that 'city' may be a slug or a name as the consumer wrote it.

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 the resource (a town's local providers) and enumerates what is returned: the town page, whether companies are connected, their names, and prefill_link. It positions itself against siblings by citing list_sites for the domain and get_service_info for option ids. It stops short of stating the core act in a single crisp verb+resource phrase, since it describes outputs rather than 'find providers for a town'.

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?

Uses of the optional inputs are explained ('Pass answers and a short description to get prefill_link filled in'), and the sibling references imply a workflow from list_sites to get_service_info to this tool. However, there is no explicit statement of when to call this tool versus the alternatives, nor any exclusion or prerequisite condition.

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?

With readOnlyHint, idempotentHint, and openWorldHint=false already provided, the description adds useful behavioral detail: it enumerates the information returned and clarifies that contact details are entered separately by the consumer on the town page, so the agent knows not to expect them. It does not contradict 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-loads the main returned data before the contact-details note. It is a single dense sentence plus a clarification, with little wasted wording, though it could be slightly easier to parse if split.

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 low-complexity, read-only tool with full parameter schema coverage and annotations covering safety, the description is largely complete. It explains the main data fields and the relationship to find_providers, though it could more explicitly state the retrieval purpose or usage trigger.

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 one parameter with 100% schema description coverage, and the schema already explains that 'site' is a domain from list_sites. The description does not add any syntax, format, or meaning beyond what the schema provides, 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 the concrete data returned: site offerings, request form questions with option IDs, and whether assistant requests are open. This distinguishes it from find_providers, which consumes those option IDs. It lacks an explicit action verb like 'retrieve', but the resource and scope are clear.

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 implicitly links the tool to find_providers by noting its request-form option IDs are 'for find_providers', giving some usage context. It also notes that contact details are entered on the town page, implying they are not returned here. However, it never explicitly says when to call this tool versus alternatives or names a sibling as an alternative.

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 readOnly, idempotent, non-destructive and closed-world behaviour, so the safety profile is covered. The description adds genuinely non-obvious behaviour beyond that: results are grouped by country, one site per trade/country, the trade label is rendered in English unless a country is supplied, in which case the local trade word is returned.

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 compact sentences, front-loaded with what is listed and how it is grouped, followed by parameter behaviour. No filler; the only slightly cryptic phrase is 'Use the site in the other tools', which is terse rather than wasteful.

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 describing returns and does so (grouping, site names, trade language). Combined with the fully covered input schema and read-only annotations, an agent has enough to invoke it correctly; only the relationship to the sibling tools stays underspecified.

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 already documents both parameters and their example values, so the baseline is 3. The description goes further by explaining the distinct result shape each parameter produces (single-country view vs. trade search), which the schema 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 description states a specific verb and resource ('Lists the sites'), plus a precise scope: one site per trade and country, grouped by country. It does not explicitly differentiate itself by name from siblings such as find_providers or get_service_info, but the resource and grouping behaviour are clear enough to select it correctly.

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 tells the agent how each optional parameter changes the result (country -> single country view with local trade word; trade -> search by trade), which implies usage but never states when this tool should be preferred over find_providers or get_service_info. 'Use the site in the other tools' hints at a downstream relationship without naming alternatives.

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