verify_vacation_rental_node

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

The annotations already declare readOnlyHint=true and destructiveHint=false, and the description reinforces this with 'Read-only trust check' and 'no availability, pricing, booking, or payment.' It goes further by disclosing that it reads the domain's .well-known/vacation-rental.json and JWKS, that verification fails when the passed domain differs from the declared canonical_domain, that IPs/ports/local/private hostnames are refused, and that the result is only as trustworthy as the exact domain passed. This fully discloses behavior beyond the 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 dense but every sentence earns its place. It front-loads the core purpose, then alternates between usage rules, parameter constraints, and behavioral caveats. There is no redundant phrasing; each clause adds distinct, operationally relevant information. Despite its length, it is a model of purposeful prose.

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?

Given the tool's complexity (trust verification, canonical domain nuance, read-only contract, and follow-up action), the description covers all necessary context: when to apply, how to call, what to expect on success, and what failure conditions look like. The presence of an output schema further reduces the need to describe return values, and nothing an agent needs to call this tool correctly is missing.

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?

Although the schema already describes the domain parameter with a pattern and example, the description adds crucial semantics: it must be a bare hostname (no scheme/path), public domains only, and the canonical domain must be passed exactly (www vs apex are distinct). It even warns about the failure condition for canonical domain mismatch, which is not in the schema. This materially improves agent correct invocation.

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 opens with a precise verb and object: 'Verify that a vacation-rental host domain is a valid Vacation Rental Protocol (VRP) node before trusting it.' It explicitly differentiates from siblings by stating that domains from hemmabo_search_properties do not need this verification and can go straight to get_verified_stay_offer, which clearly distinguishes its role.

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 when-to-use and when-not-to-use guidance: use when a host domain arrives from outside search (user-typed or third-party), and do NOT use it for availability, pricing, booking, or payment. It also names the alternative (hemmabo_search_properties) and instructs the exact follow-up call (get_verified_stay_offer) on success, leaving no ambiguity about its place in the workflow.

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