Voya Homes public vacation-home search

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

With annotations already marking readOnly and idempotent, the description adds valuable context: the catalog is static, does not check availability, and does not return a fixed price. This goes beyond the annotations to warn agents against using this tool for real-time pricing or availability. It does not mention pagination behavior, but the output schema covers the response.

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 with no wasted words. The first sentence front-loads the exact purpose and attribute list; the second adds the critical limitation and points to the correct alternative. Every clause earns its place.

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 read-only catalog discovery tool with an output schema, annotations, and a clear pointer to search_homes, this is quite complete. It could add a note about pagination or default result set, but nothing essential is missing for correct invocation.

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 11%, so the description must compensate. It does clarify several filters (name, public code, condominium, neighborhood, city, bedrooms, amenities) that map to query, neighborhood, city, minBedrooms, and amenities. However, it leaves maxGuests, language, page, and pageSize unexplained, and the 'query' parameter semantics are already in the schema.

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: 'Read-only static catalog discovery' of Voya Homes properties, listing concrete search attributes (property name, public code, condominium, neighborhood, city, bedrooms, amenities). It also distinguishes itself from the sibling search_homes by explicitly stating it does not check date availability or return a fixed price.

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 an explicit when-not and alternative: 'use search_homes after selecting travel dates' for availability/pricing, implying this tool is for pre-selection catalog discovery. The condition is clear, and even though get_home/list_destinations are not mentioned, the main ambiguity is resolved.

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, idempotentHint, and destructiveHint. The description adds value by explicitly stating 'It never reserves, charges, creates an intention or modifies data' and by describing the conditional availability/checkout URL behavior. This goes beyond the annotations and clarifies what the tool does and does not do during execution.

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, no wasted words. The first sentence fronts the core purpose; the second adds a conditional behavior and a strict safety statement. Every phrase earns its place with high information density.

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 has an output schema (not detailed here), the description need not explain return format. It covers the read-only nature, optional parameters, and safety profile. It could mention the language parameter or explicitly note that a houseCode is required, but the core usage is adequately described for an agent to call it correctly.

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 17% (only houseCode has a description). The description mentions 'dates and guests' but does not map these to specific parameters (checkIn, checkOut, adults, children) or explain the language enum. It adds some context—that supplying these values triggers availability—but does not sufficiently compensate for the low schema coverage.

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 (Get) and resource (property details) with an optional 'date-bound price,' clearly distinguishing it from list_destinations and search_homes. It centers on a single property (houseCode) and adds conditional pricing behavior, leaving no ambiguity about the tool's core purpose.

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 gives a clear condition—'When dates and guests are supplied, returns a server-side availability result plus a direct checkout URL'—but does not explicitly exclude alternatives or say 'use this when you already have a houseCode.' Context implies it is for a specific property, but explicit sibling differentiation is missing.

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, idempotentHint, and destructiveHint false, but the description adds explicit assurance that it never creates a booking, intention, payment, hold, or customer record. This goes beyond the annotations by naming the specific side effects that are absent.

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 with no filler. The 'Read-only' safety qualifier is front-loaded, and the rest of the description adds concrete behavioral detail without redundancy.

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-parameter list tool with an output schema and annotations covering side-effect safety, the description is complete. It tells the agent what the tool returns conceptually and that no mutation occurs; the output schema covers the return shape.

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?

The tool has zero parameters and schema coverage is 100%, so the schema fully documents the empty input. The description needs no parameter-level details, and the baseline of 4 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 uses a specific verb ('Lists') and a clear resource ('destinations currently exposed by Voya Homes'). It also distinguishes the tool from its siblings, get_home and search_homes, which focus on homes rather than destinations.

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 implies when to use this tool: when you need the current list of Voya Homes destinations. However, it does not explicitly mention alternatives or state when not to use it, leaving the choice 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 already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds important context beyond that: it explicitly states the tool never reserves, charges, creates an intention, or sends a payment request, which is critical for an agent deciding whether to use this in a booking flow.

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-loaded: it states the operation, then the return value, then the safety guarantee. Every sentence adds value and there is no repetition of schema details.

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?

The description covers the core search behavior and safety profile well, and an output schema exists to describe return values. However, with many optional filter parameters and no mention of pagination or how to discover valid destinations (e.g., list_destinations), the description is not fully complete for a complex search 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?

Schema description coverage is low at 38%, so the description must compensate for undocumented parameters. It only mentions destination, dates, and guests, but leaves page, pageSize, bedrooms, language, price bounds, amenities, and categories unexplained. This is insufficient for a 13-parameter tool.

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 uses a specific verb and resource: 'search of vacation homes' for availability and prices. It clearly distinguishes from siblings by indicating it is a multi-result search, versus get_home (single property) and list_destinations (destinations only).

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 gives clear context: use this when you need current availability, prices, and booking links for vacation homes by destination, dates, and guests. It does not explicitly name alternatives or exclusions, but the intended use case is evident.

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