Jagir

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

Annotations already declare readOnlyHint, and the description reinforces it with 'Read-only: nothing is booked'. It then adds context the annotations cannot: that fees/extra-guest charges appear only 'where the platform reports them' and that Otaghak quotes are calendar-derived estimates (estimated: true). That provenance caveat is genuinely useful behavioral disclosure.

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 tight sentences, front-loaded with the purpose and price semantics, followed by the read-only guarantee and the estimate caveat. No filler; every clause carries information.

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 does the work of describing the return qualitatively — exact price in Toman, inclusion of extra-guest charges and fees, and an estimated flag — which is close to complete for a read-only quote tool. It could go further on how unpriced or unavailable platforms are surfaced, but the core is covered.

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 100%, so id, guests, checkIn and checkOut (including the Jalali/Gregorian date flexibility) are fully documented in the schema. The description adds no syntax or constraint detail beyond that, so the baseline of 3 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?

States a specific verb+resource: exact price (in Toman) for one stay, scoped to dates and guest count. The currency, the inclusion of extra-guest charges and fees, and the 'one stay' scope make it distinguishable from get_stay and search_stays without opening schemas.

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?

Usage is implied — compute a price for a given stay and date range — and the 'nothing is booked' note clarifies it isn't a booking step. However, no sibling is named and no when-not condition is given, so an agent must infer the boundary versus get_stay itself.

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 and openWorldHint, so the safety profile is covered. The description adds genuinely useful behavioral context: ordering, inclusion of host replies, per-platform positive/negative points, recommendation flag, and the aggregate rating breakdown and star distribution. It does not mention pagination or handling of stays with no reviews, so it is not fully complete.

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?

Front-loads the core purpose and ordering before enumerating returned fields. The long field list and the stray '(Otaghak)' parenthetical add minor noise, but every clause is informative and nothing is 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 full burden of describing return values, and it does so thoroughly (full text, rating, host reply, breakdown, star distribution). For a simple two-param read tool this is close to complete, though pagination and empty-result behavior remain unspecified.

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 100%, documenting both 'id' (format and example values) and 'limit' (range and default 50). The description adds nothing about parameter syntax or behavior, so the baseline 3 applies since the schema already carries this burden.

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 ('Guest reviews of one stay') and immediately distinguishes itself from the sibling tools, which all deal with stays, locations or quotes rather than review content. Ordering ('newest first') and the fields returned are named, so an agent can tell exactly what it will get.

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 a concrete motivating use case ('Use it to judge cleanliness, noise, view or host behaviour from real guests'), which tells the agent when this tool is valuable. It stops short of naming exclusions or alternatives (e.g. that get_stay does not return reviews), so it is clear context but not full when/when-not guidance.

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 openWorldHint=true, so safety is covered. The description goes further by disclosing the breadth of the response payload, including surprising items like missing amenities and host response time, which helps an agent gauge cost and result size. It does not mention auth or rate limits, but for a read tool this is a strong addition.

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?

A single front-loaded sentence that immediately states the core purpose before the enumeration. The long field list is dense but defensible because no output schema exists to carry that information.

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 must describe what comes back, and it does so thoroughly across description, amenities, rules, pricing, ratings, photos and extras. Output-schema absence makes this the right place for that detail, though it never states the return format (object vs. text) or error behavior for an invalid id.

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% and there is a single parameter whose format ('<platform>:<id>') is fully documented in the schema. The description adds nothing about the id, so the baseline of 3 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?

States a specific verb and resource ('Full details of one stay') and enumerates the exact content returned, so an agent knows it is the single-record detail fetch. It does not name a sibling to contrast with (e.g. search_stays, get_quote), so differentiation is inferred rather than explicit.

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 implicit usage is clear — fetch details for a known stay id — but no when-to-use or when-not-to-use guidance is given, and the closer alternatives (search_stays for listings, get_quote for pricing) are not mentioned. Adequate but leaves routing 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 establish readOnlyHint and openWorldHint, so the safety profile is covered. The description adds the default and maximum date ranges, which is useful behavioral context not in the annotations, but says nothing about pagination, truncation at the 120-day limit, or missing-price 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?

Two short sentences, front-loaded with what the tool returns and followed by the operative date-range bounds. No filler whatsoever.

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 tool with a fully described three-parameter schema and no output schema, the definition is nearly sufficient: an agent knows the resource, the unit, the currency, and the date-range limits. It is only slightly thin on the relationship to get_stay, which matters for sibling routing.

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 the baseline would be 3, but the description adds the default window (today + 30 days) and the 120-day cap that the schema does not express. Those are genuine constraints on from/to that help the agent construct valid calls.

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 names the specific resource (per-night availability and price for one stay) and even specifies the currency (Toman), which is meaningful detail. It does not, however, differentiate itself from the sibling get_stay, leaving the agent to infer the distinction between a stay summary and its calendar.

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 supplies a default window (today + 30 days) and a maximum span (120 days), which implicitly tells the agent the expected usage scope. It never states when to prefer this over get_stay or get_quote, so routing among siblings remains inference-based 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 and openWorldHint=true, so the safety profile is covered. The description adds genuine context that this resolves against three named external platforms, but says nothing about the returned shape, unresolved-name behavior, or normalization rules, so it remains thin beyond structured fields.

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 the core action, then the purpose, then the routing note. Every sentence earns its place with no hedging or repetition.

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 single-param, no-output-schema lookup tool, the description covers what it does, why to use it, and the sibling overlap. Only the return semantics ('how a name is known' on three platforms) are left implicit, which a naming lookup call can reasonably tolerate.

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?

One parameter with 100% schema description coverage, so the baseline is 3. The description's Persian/English examples mirror what the schema already states ('City or region name, Persian or English'), adding no syntax or validation detail beyond it.

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 (look up / resolve) plus a precise resource (a city/region name's canonical mapping) and explicit scope (Jabama, Jajiga, Otaghak). The parenthetical examples with Persian and English forms make the resource unambiguous, and the sibling set (search_stays, get_stay, etc.) is clearly distinguished.

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?

States the use case ('check a destination exists before searching') and explicitly names the alternative path ('search_stays resolves locations itself'), telling the agent when NOT to bother calling this. This is exactly the when/when-not/alternative structure the dimension rewards.

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 and openWorldHint, so safety is covered. The description goes beyond that, disclosing the multi-platform fan-out, the Toman (IRT) currency, that price.total is populated only when dates are supplied, and that per-platform failures surface in an 'errors' field while other results still return. That partial-failure behavior is genuinely non-obvious and valuable.

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, all front-loaded and information-dense: scope, currency, pricing semantics, error handling. Nothing is repeated from the schema and 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?

With no output schema, the description must carry return-value context, and it does disclose the price.total/perNight duality and the 'errors' array for failed platforms. It stops short of describing result item shape or ordering/pagination, but covers the quirks an agent most needs.

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 the baseline is 3. The description only lightly reinforces parameter meaning, clarifying that min/max price are per-night and that dates switch pricing from perNight to total, but adds no syntax beyond the schema's own date-format and enum documentation.

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 (search short-term rentals) plus the aggregation scope across Jabama, Jajiga and Otaghak in Iranian cities. The 'at once' framing and the property-type examples make it unmistakable versus siblings like get_stay, which fetch a single listing.

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?

Usage is implied clearly (discovery/search across platforms before drilling into a specific stay), but no alternative is named and no when-not condition is given. There is no pointer to get_stay or get_quote for single-listing or pricing follow-ups.

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