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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds non-obvious behavioral context beyond that: prices are all-inclusive with no customer fee, every business of a kind exposes the same option catalog, and results come with the next open times. It stops short of explaining result limits or pagination.

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 exclusion and sibling alternative are front-loaded, and the dense option enumeration earns its space because the schema does not describe the options object at all. The phrasing is telegraphic and occasionally run-on ("options are the same at every business of that kind: read catalog on any of them"), but no sentence is 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 12-parameter, nested-object tool with no output schema, the description does explain the shape of the answer (providers, firm price, next open times) and the booking handoff, which is the essential missing piece. However, roughly two-thirds of the parameters remain undocumented in both places, and filtering semantics for date/days/sort/finish_by/start_after are left for the agent to infer.

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 only 33% across 12 parameters, so the description carries real weight here. It does document the two most consequential ones well (the service tag's allowed values, and the per-service options taxonomy with concrete keys and values), but leaves fields, repeat, days, sort, finish_by, start_after and max_price unexplained in both schema and 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?

The description states the resource precisely (who serves a ZIP or city for a given service, with prices and next open times) and explicitly bounds scope to house_cleaning, plumbing and hvac, routing everything else to find_businesses. The action verb is implied rather than stated ("Who serves..."), which keeps it just short of a 5, but an agent can distinguish it from siblings without opening the 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 names the eligible service categories up front, names the correct alternative (find_businesses) for anything else, and describes the follow-on path to book with the returned item_id. This is explicit when-to-use, when-not-to-use, and what-to-do-next guidance in one place.

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