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

Beyond the annotations (readOnly, idempotent, non-destructive, closed-world), the description discloses the exact return payload shape, the extra material returned (contact details, visit window rules in words), and the failure mode where bookable is false with page_url as the redirect. This is rich context that annotations alone do not provide.

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 sentences, front-loaded with the primary return content before the conversational instruction and the fallback branch. Every sentence earns its place; the first sentence is information-dense but not padded.

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 what comes back, and it does so thoroughly: question fields, contact requirements, visit window rules, and the alternate page_url branch. An agent has everything needed to call and handle 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 coverage is 100%, so both town and trade are already documented in the schema. The description reinforces that trade and town jointly drive bookability but adds no format or slug guidance beyond what the schema already provides. Baseline 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 states a specific verb (return) and resource (project questions to ask the homeowner) along with the exact output fields (key, label, type, options, required, when applies). It also conditions the purpose on a sibling tool's result (get_coverage bookable), which helps distinguish it from get_coverage and start_booking, though the opening clause is slightly dense.

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 clear context: use this for a trade and town where get_coverage reports bookable, and it prescribes how to present the questions (conversationally, one or two at a time). It also handles the not-bookable branch by routing to page_url. It stops short of explicitly excluding or comparing against the other siblings.

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