StayForWork - Housing and Hotels for Travel Workers

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

Annotations already cover read-only/open-world safety, and the description adds real context beyond them: the propertyRef must be signed, and search results carry name, position, and propertyRef. It omits error behavior for an expired/invalid ref and any pagination or size limits on the returned photos/amenities.

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 short sentences, front-loaded with what is returned, then the blocking precondition. No filler or restatement of the tool name.

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 two-param read tool with no output schema, the description covers the return contents and the critical prerequisite. The only real gap is the undocumented currency parameter, which an agent would have to infer from the schema's name and default.

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 0%, so the description must compensate. It explains propertyRef well (signed, sourced from search results, not a name), but says nothing about the currency parameter or its USD default, leaving one of two params undocumented everywhere.

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?

Specific verb+resource: returns photos, amenities, and property facts for a furnished home. It also scopes the input to a home 'selected from search results,' which implicitly chains it after search_stays, but it never names get_home_offers or get_hotel_details to sharpen the distinction among siblings.

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 states the precondition clearly (must come from search results, must have the signed propertyRef, a name alone is insufficient) and says where to get the ref. It stops short of naming alternatives or saying when-not to use it versus the offers/hotel siblings.

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=true and destructiveHint=false, yet the description still adds real value: the signed propertyRef requirement, the fallback semantics when dates/guests are omitted, and the crucial caveat that the returned price is an estimate subject to host confirmation rather than a bookable offer. That caveat is exactly the kind of behavioral context annotations cannot carry.

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 action and resource, then the prerequisite, then fallback semantics, then the estimate caveat. Every sentence carries information the agent cannot get from the schema or annotations.

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 six-parameter pricing lookup with no output schema, the description covers the prerequisite, the omitted-parameter fallback, and characterizes the return as an estimate pending host confirmation. Missing only coverage of currency and the childrenAges array semantics.

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 0%, so the description must compensate and it does so partially: it explains propertyRef (must be the signed ref from search), and the semantics of checkinDate/checkoutDate/adults in one sentence about retaining the original search stay. currency and childrenAges receive no explanation anywhere, leaving the agent to guess at currency behavior and child-age sensitivity.

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?

States a specific verb (refresh) and precise resource (availability and estimated full-stay price for a furnished home from search results). It partially separates itself from the hotel siblings by clarifying this is not a hotel room offer, but it never names get_hotel_offers/get_home_details as alternatives.

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?

"selected from search results" establishes the prerequisite that the item must come from a prior search, and "Omitted dates or guests retain the original search stay" tells the agent it can call without re-specifying the stay. No sibling is named for the contrasting case (full hotel offers, property details), so routing is implied rather than explicit.

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=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description usefully adds that results are 'undated' (no availability/pricing) and that home lookups require a reference from search results. It does not say what happens with an ambiguous hotelName or a name that fails to match.

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 core behavior and no padding. The 'propertyRef' vs 'propertyId' terminology drift is the one spot where wording costs clarity rather than saving space.

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?

No output schema exists, and the description only gestures at the return payload ('facts, photos, and amenities') without indicating structure or currency handling. Combined with the unexplained currency parameter and the propertyRef ambiguity, an agent has enough to attempt the call but not enough to predict 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 0%, so the description must carry the load. It explains hotelName, propertyId, and destination semantics well, but currency is never mentioned, and the description references a 'propertyRef' that does not exist in the input schema (the parameter is propertyId), which risks confusing the agent about which field to send.

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?

States a specific verb and resource: 'Return undated hotel or motel facts, photos, and amenities.' The word 'undated' plus the fact/photo/amenity scope implicitly separates it from get_hotel_offers, and the closing sentence about furnished homes separates it from get_home_details, though neither sibling is named explicitly.

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?

Gives clear lookup-mode guidance: use propertyId from a search result, or hotelName directly, with optional destination to narrow a name match. It also states a hard constraint (furnished homes cannot be queried by name alone). It stops short of explicitly routing to get_hotel_offers for pricing or to search_stays for discovery.

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 cover the safety profile (readOnlyHint, destructiveHint=false, openWorldHint), so the bar is lower, and the description adds genuinely non-obvious behavior: confidence-threshold name resolution, candidate results on ambiguity, and private member prices masked until sign-in. It also notes multi-week work-stay coverage. Missing are failure modes (no availability, invalid propertyId) and rate/limit behavior.

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 sentences, each front-loaded with a distinct fact — purpose and scope, input modes, ambiguity handling, price masking. No restatement of the title and no 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?

With 9 parameters at 0% schema coverage and no output schema, the description should explain the remaining inputs and at least the shape of an offer (rooms, rates, taxes, cancellation terms). It covers the core call path and the sign-in caveat but leaves enough undefined that an agent must guess at currency/room-count semantics and return structure.

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 0% across 9 parameters, so the description carries the burden and only partly discharges it: it explains the propertyId vs hotelName+destination split and confirms checkin/checkout dates and guest count are required. currency, hotelRooms, and childrenAges go entirely unmentioned, and no date format or currency constraints are restated.

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?

States a specific verb and resource ("Return live room offers for a hotel or motel") plus the scoping dimensions (explicit dates and guests). It is readily separable from get_hotel_details (property attributes) and search_stays (property discovery), so an agent can route without opening a 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?

The description gives the decision rule between the two input modes: a propertyId from search results, or a hotelName with optional destination. It also flags the ambiguous-name outcome (candidates returned via a confidence threshold), which shapes follow-up behavior. It does not say when to prefer get_hotel_details or search_stays instead, so no explicit alternatives or exclusions.

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?

Beyond the read-only and open-world annotations, the description explains that the destination is resolved internally, coordinates are optional, results are one ordered page, and returns include prices, distances, IDs, and signed propertyRef values. It also clarifies that propertyRef can identify a home for later reference, which is important behavioral context.

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 purpose and key constraints are front-loaded and easy to scan. There is minor redundancy around propertyRef and the audience sentence is helpful but not strictly invocation-critical, keeping it just below maximally concise.

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, open-world search with no output schema, the description covers the main requirements, filters, and return shape well. It still leaves some parameter behavior, especially pagination details and child/price/currency semantics, to the schema alone.

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 description adds useful meaning for required dates/adults, optional coordinates, housingType, sort, and propertyRef. However, with 16 parameters and only 31% schema description coverage, several parameters such as page, size, currency, childrenAges, and nightly price bounds remain unclarified beyond their names and types.

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, "Search," and names the resources: extended-stay hotels, motels, and furnished housing. It also distinguishes the scope from detail/offer siblings by focusing on discovery near a destination for work-travel assignments.

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 clearly states the intended context: work-travel lodging for travel nurses, construction crews, outage workers, and similar assignments. It does not explicitly name when to use this versus get_hotel_details, get_hotel_offers, or get_home_offers, so alternatives are left implicit.

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