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

Annotations already declare readOnly/idempotent/non-destructive/openWorld, so safety is covered; the description adds real behavioral detail beyond that — the 14:00–23:50 Iran-time display window, undated prices for last-second rooms, and the fact that city filters out last_second entirely. It stops short of describing result shape or pagination, which is acceptable given the output schema.

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 ('Current discounts: ...') then details each list, with zero filler sentences. The backtick-heavy, oddly line-wrapped formatting is slightly noisy but not verbose.

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 an output schema present, return values need not be described; the description instead covers the two list modes, their scoping rules, the time window, and the natural next call. Nothing an agent needs to invoke this 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?

Schema coverage is 100% so the baseline is 3, but the description adds interaction semantics the schema cannot express: `city` suppresses the last_second list, and supplying dates makes most_discounted prices stay-specific. That is genuine meaning beyond the per-field descriptions.

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 resource (current discounts / deals) and explicitly splits it into two named lists, 'last_second' and 'most_discounted', each with its own scope and sort order. An agent can tell this apart from ot_search_rooms or ot_price_quote without opening the 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?

Gives concrete selection conditions: last_second is site-wide and excluded when `city` is supplied, while most_discounted is scoped to the 'discounted' collection and honors city/dates. It also routes the agent forward ('Next: ot_price_quote for the exact total'), though it does not contrast itself against the other room-search 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 the read-only, idempotent, non-destructive profile, so the bar is low. The description adds a genuine behavioral detail beyond them: when `collection` is supplied the result set changes to also include the cities that collection covers, expressed as city slugs. It does not discuss limits or pagination, but with an output schema present that is not required.

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 resource and the concrete examples, followed by the routing rule and the parameter behavior. No filler or repetition; every sentence carries a distinct instruction.

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 an output schema present, return values need not be spelled out, and the description covers the zero-required/one-optional parameter surface plus the cross-tool handoff to ot_search_rooms. The only small gap is what the tool returns when `collection` is omitted, which is left to the schema.

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 baseline is 3, but the description earns a bump: it explains that `collection` is a code shared with ot_search_rooms and demonstrates the accepted values ('beach', 'jungle', 'lastsecond'), which is meaning beyond the raw slug pattern. It also clarifies the optional param's effect on the response.

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?

Names the specific resource (popular cities and themed collection landing pages) and illustrates it with concrete examples ('discounted', 'jungle villas', 'villas with pool'). It is distinguishable from list-style siblings but never uses an explicit verb like 'list', leaving the action slightly implied by the noun phrase.

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 an explicit trigger ('Use when the user has no destination yet') and a second, distinct trigger (to obtain collection codes for the ot_search_rooms `collection` parameter), naming the sibling that consumes the output. Nothing is left to inference about when to reach for this tool.

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, openWorldHint, and destructiveHint=false, so safety is covered. The description adds output-interpretation context the annotations cannot: cities return an undated listing count and a province `listings` value is not a search count, warning the agent about a plausible misuse.

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 transformation and stays compact, with the reverse-mapping note and the 'Next:' routing fragment kept brief. It is slightly dense with backtick-quoted field references and the trailing routing clause is a touch clipped, but no sentence is wasted.

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?

An output schema exists, so return structure needn't be described, and the description still adds what matters: what the input maps to, the interpretation caveat on counts, and where to go next. Nothing an agent needs to call this 1-parameter lookup 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?

Schema description coverage is 100% and the single `query` parameter already documents accepted forms (Persian name, English slug, numeric room code) with examples. The description restates the same duality without adding format, length, or validation detail beyond the schema, so 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?

States a concrete transformation: a place name becomes city/province slugs for ot_search_rooms, or a room code becomes its room. It names the exact input/output resources and clearly separates this from sibling lookups, so an agent can identify the tool without opening the 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?

Explicitly states the exclusion ('Room names are not searchable here') and redirects to the correct alternative with the parameter to use ('use ot_search_rooms with `name`'). It also routes downstream consumers ('Next: ot_search_rooms, or ot_room for a room hit'), leaving no ambiguity about when this tool applies.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: without `query` you get every FAQ question with short answers or section titles with a preview, and with `query` you get matching FAQ items or page paragraphs. It does not mention truncation limits or result caps, which is the only remaining gap.

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?

Purpose is front-loaded in the first clause, and the parenthetical enumerations of covered content are informative rather than padding. The second paragraph carries the usage/behavioral load efficiently, though the topic list is somewhat duplicated between the body and the schema.

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 an output schema present, return values need not be explained, and annotations cover safety. All parameters are documented, both optional, and the sibling routing is stated. The definition is complete enough to invoke correctly; only edge-case behavior (result limits, empty-query fallback on non-FAQ topics) is unstated.

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, but the description goes further by explaining the query/no-query behavioral split and clarifying that `topic` selects the content set (FAQ vs. terms vs. host rules vs. quality policy). The per-parameter hints (Persian keywords, length limit) live in the schema rather than the description, so it does not fully supersede 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?

States a specific verb and resource ('Read Otaghak's help center') and enumerates exactly what lives inside: FAQ, guest terms with booking/cancellation/refund/wallet rules, host rules, and quality policy. It also explicitly separates itself from the sibling ot_room by noting where a room-specific cancellation policy lives, so an agent can route correctly without opening either 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?

Provides an explicit when-not/alternative: 'A room's own cancellation policy is in ot_room.' Combined with the enumerated topic scopes, the agent knows what this tool covers and where the one obvious overlapping case goes instead.

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 this is a safe, idempotent read. The description adds the critical non-obvious caveat that holiday flags are only populated ~7 weeks ahead, so blank later days mean 'unknown', not 'working day'. That is exactly the kind of data-quality disclosure 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 short sentences, front-loaded with the core purpose and immediately followed by the freshness caveat. The parentheticals earn their place, though the line-break layout is slightly awkward.

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?

Output schema exists, so return values need no explanation. Between the freshness limitation, the holiday/weekend definition, and the cross-reference to ot_room_calendar, an agent has everything needed to call and interpret this 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 coverage is 100% and both parameters are documented there, including the 'at most a year after start' constraint. The description adds no syntax or format detail beyond the schema, so the baseline 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 ('List Iranian public holidays') with explicit scope (date range, Fridays included) and enrichment fields (Jalali dates, weekdays). An agent can immediately distinguish this from sibling date/availability tools like ot_room_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?

Gives a clear use case ('plan around long weekends') and routes the agent to ot_room_calendar for pricing implications. It stops short of stating when-not to use it or what alternative exists for non-Iranian holidays, but the context is concrete.

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, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds real value beyond that: it discloses data caveats such as 'undated starting prices' and 'newest reviews across all their rooms', which warn the agent about freshness/scope of the returned figures. It does not discuss auth or rate limits, but those are less critical for a read-only lookup.

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 plus a guidance sentence, with the core purpose front-loaded and the input paths second. Every clause carries information (returned fields, entry options, use case) with 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 an output schema present, return-value formatting need not be explained, and the description still names the main returned fields. Annotations cover the safety profile and all four parameters are schema-documented, so an agent has everything needed to select and call this tool 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 100%, so host_id, room_id, rooms_limit and reviews_limit are all documented in the schema itself, including the 'or a room id' alternative. The description restates the host_id/room_id either-or but adds no syntax, format, or limit semantics beyond the schema, so baseline 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 ('Check a host') and enumerates exactly what the profile contains: response time, response/acceptance rates, member since, active rooms with starting prices, and newest guest reviews. The host-level aggregation is clearly distinguishable from siblings like ot_room (single room) and ot_reviews (reviews only), and the 'judge whether a host is reliable' framing pins down intent.

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 the two entry paths ('Pass host_id, or room_id to find the room's host') and a clear purpose statement ('use to judge whether a host is reliable or to see their other places'). It stops short of explicit when-not-to-use or naming a sibling to prefer instead, so it is clear context rather than full routing 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 readOnly, idempotent, open-world, non-destructive, which fits a lookup. Beyond that the description discloses two behavioral traits the structured fields do not: results are date-dependent and non-deterministic across departure days ("often closed for it on a given day"), and the currency unit is uncertain. No contradiction with 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?

Front-loaded with the outcome and keeps the routing sentence short. The parenthetical "(Toman, a unit not confirmed on the site)" is slightly clunky but carries real information, so it earns its place; overall there is little waste.

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 an output schema present, return values needn't be spelled out, and annotations carry the safety profile. The description covers purpose, trigger, key caveats, and the sibling relationship, leaving only minor gaps such as what happens when check_out is omitted (default null).

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 room_id and check_out are already documented; the description still adds meaning by explaining that check_out is not just a date but the switch that determines bookability on that departure day (rooms are often closed for a given day). It also flags that the price unit (Toman) is unconfirmed, which the schema does not say.

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 (check a room's late checkout) and enumerates exactly what the answer contains: availability, hours, price, and bookability on a given departure day. It explicitly distinguishes itself from the sibling ot_price_quote, which only aggregates the cost, so an agent can route without opening either 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?

"Use when the user wants to leave later than the check-out time" gives a clear triggering condition, and it names ot_price_quote as the complementary tool for totaling cost. There is no explicit when-not guidance, but the use case is narrow and well bounded.

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 safety (readOnly, idempotent, non-destructive), and the description adds substantial behavior beyond them: availability validation with available=false plus reason, stay-length and guest-capacity checks, the rule that an unbookable late checkout still returns a quote with late_checkout.available=false, and the caveat that discounted nights are rounded to 1,000 so nightly can exceed nights_total. This is genuinely useful operational detail.

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-loaded with the core purpose in the first clause, then the breakdown, then the validation/exclusion rules. It is dense and slightly long, but nearly every sentence carries a distinct constraint (rounding, availability, late checkout, login exclusions).

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?

An output schema exists so return values need not be explained, yet the description usefully clarifies the non-obvious rounding relationship between nightly and nights_total, plus failure semantics for availability and late checkout. Combined with full schema coverage and clear annotations, an agent has everything needed to call and interpret it.

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, but the description adds real semantic meaning: 'guests' is interpreted as base occupancy with extra-guest charges applied above it, and late_checkout_hours is framed as optional and only valid for offered rooms. That clarifies how inputs map to pricing behavior rather than merely restating field docs.

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 (get) and resource (amount to pay in Toman for a room/dates/guests) and enumerates the returned components (nights_total, extra-guest charge, late checkout, total). This clearly separates it from siblings like ot_room (details) and ot_room_calendar (availability display).

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 explicit context: 'Use before the user books on otaghak.com,' and notes that coupons and wallet credit need login and are excluded. It does not name alternatives (e.g., ot_late_checkout or ot_room) or say when not to use it, so it falls short of full routing 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, idempotentHint and openWorldHint, so safety is covered. The description adds genuine behavioral context: 'rating is null and reviews empty when the room has no ratings yet (new rooms)' and that reviews are sorted 'newest first (with host replies).' It stops short of pagination/volume caveats, but the edge-case disclosure is 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?

Two tightly packed sentences: the return contract first, then the empty-state caveat and cross-tool routing. No filler and the most decision-relevant information is front-loaded.

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 an output schema present and rich annotations, the description only needs to add what structured fields cannot: the empty-room edge case, sort order, and sibling routing. All are present, and the required room_id plus pagination are schema-documented.

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% – room_id, page (zero-based), and limit are all documented in the schema. The description adds nothing about the parameters, so the baseline 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 precise verb+resource (get a room's rating) and enumerates the exact payload: 0-5 rating, star histogram, six category scores, recommend percentage, written reviews newest first with host replies. This is far more specific than the title and lets an agent distinguish it from sibling tools.

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?

Explicitly says to use it 'after ot_room or ot_search_rooms to judge quality' and routes the host-level variant to 'ot_host has reviews across all of a host's rooms.' Both the when-to-use condition and the alternative tool are named.

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 (readOnly, idempotent, non-destructive), but the description adds a genuinely non-obvious behavioral trait: with check_in/check_out the returned price is the average night even when the dates are booked, so price does not imply availability, and it points to ot_price_quote/ot_room_calendar to verify. That is real behavioral context 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?

Front-loads the purpose, then price semantics, then next steps in three tight sentences. Dense but every clause earns its place; the enumerated field list is slightly long but aids selection.

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?

Output schema exists, so return values need not be explained; combined with 100% schema coverage, the annotations, and the explicit routing, an agent has everything needed to call this correctly and interpret 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 the baseline is 3, and the description goes beyond it by explaining what check_in/check_out actually change (average nightly price vs undated starting price) rather than merely restating the date formats 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?

States a specific verb+resource ('Get one room') and enumerates precisely what the room record contains (capacity, beds, amenities, house rules, cancellation policy, host, photos, price). It clearly distinguishes itself from the sibling search tools by being the single-room detail lookup.

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?

Explicitly routes the agent: 'Use after ot_search_rooms or ot_find_place', and names five next-step tools with their distinct roles (ot_price_quote for exact total, ot_room_calendar for free nights, ot_reviews, ot_host, ot_similar_rooms). Both when-to-use and alternatives are covered.

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 read-only, idempotent, non-destructive, so the safety profile is covered. The description adds genuinely non-obvious behavior: the pricing rule ('a night is priced on its arrival day') and the calendar horizon limit ('open only to the end of next Jalali month'), which an agent cannot infer from annotations or schema.

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 paragraphs: the first front-loads the returned fields, the second carries the pricing rule, horizon limit, and usage/handoff. Every sentence earns its place with 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?

An output schema exists, so return structure need not be re-explained. Combined with annotations and 100% schema coverage, the description supplies the remaining operational context (pricing rule, horizon, usage, next step) an agent needs to call this 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 100%, so the baseline is 3. The description adds a semantic constraint relevant to the start/end parameters — the calendar only opens to the end of next Jalali month — which goes beyond the field-level docs and explains truncation behavior.

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 ('Get a room's calendar day by day') and enumerates the exact per-day fields returned (discounted/undiscounted nightly price, availability, instant booking, min/max nights, weekend, holiday, late checkout). It also distinguishes itself from siblings by routing to ot_price_quote for stay pricing.

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 usage contexts ('find free dates, the cheapest nights or allowed stay lengths') and names the natural next tool (ot_price_quote for a stay). It does not explicitly state when NOT to use it versus ot_room or ot_search_rooms, so it falls short of the top band.

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 readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds return-content context (Toman price range, filter codes, district/landmark ids), but since an output schema exists this is partly redundant and it says nothing about auth or rate limits.

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 sentence is front-loaded and the long parenthetical enumerating filter examples is the only mildly indulgent part. Overall it is tight and skimmable.

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 an output schema present, return values need not be re-explained, and the description still supplies the essential workflow link to ot_search_rooms plus scope semantics. It is complete enough to invoke correctly, missing only edge-case or auth guidance.

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 baseline is 3, but the description goes beyond the schema by explaining what each scope yields (a city returns its districts and landmarks; the codes feed ot_search_rooms' filters/room_types ids), which clarifies the otherwise opaque slug parameters.

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 (List) and resource (search filters) and scopes it precisely to city/province/collection/site. It also names the consuming sibling (ot_search_rooms), so an agent can place it in the workflow 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 final sentence gives an explicit trigger: 'Use when the user asks for an amenity, a rule, a room type or a place near a landmark.' It does not state when NOT to use it or name a competing alternative, but the trigger conditions are concrete.

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 the read-only, idempotent, open-world profile, so the description is free to add the non-obvious behavior: prices are undated starting prices without dates, and with dates they are estimates that 'can be a few Toman off' while including extra-guest charges. That estimate caveat is genuinely valuable context an agent cannot get from annotations or schema.

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 paragraphs: scope first, then date/pricing semantics, then the tool chain. For a 22-parameter tool this is efficiently front-loaded with no filler sentences.

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?

An output schema exists, so return values need not be explained, yet the description still clarifies the two price fields' meaning. Given the tool's complexity, the definition covers scope, pricing duality, dependencies and follow-ons adequately; only explicit when-not guidance 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?

Schema description coverage is 100%, so every parameter is already documented in structured form; baseline 3 applies. The description adds cross-parameter semantics (check_in/check_out together drive availability and pricing) but no per-parameter detail beyond what the schema already carries.

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?

Opens with a specific verb and resource ('Search Otaghak stays') and enumerates the property types and the three scoping axes (city, province, collection). It is clearly distinguishable from siblings like ot_room (single stay details) or ot_find_place (slug lookup).

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?

Explicitly routes to prerequisites ('Get slugs from ot_find_place, filter codes from ot_search_filters') and names the follow-on tools (ot_room, ot_price_quote, ot_room_calendar) with their conditions. It lacks any 'when not to use this' guidance relative to siblings like ot_deals or ot_similar_rooms, so not a full 5.

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 read-only/idempotent/safe, so the bar is lower. The description adds behavior the annotations cannot express: prices are undated starting prices without dates and re-priced for the stay with dates, and unavailable rooms are surfaced in a not_available list. That is genuine operational context 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?

Front-loaded with the core purpose, then the pricing/availability nuance, then the next-step tools. Every sentence adds information; there is no restatement of the title or padding.

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 an output schema present, return shape need not be explained, and the description instead covers the non-obvious parts: pricing mode depends on dates, booked/too-small rooms land in not_available, and the follow-on tools. Nothing an agent needs to invoke it 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?

Schema coverage is 100%, so the baseline is 3. The description goes further by explaining how check_in/check_out change price semantics and how guests filters out undersized rooms, adding interaction meaning that the per-parameter schema text does not fully convey.

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 first sentence states a specific verb (get), resource (alternatives to a room), scope (same city and type), and cardinality (4-5), and the phrase 'as the room page shows them' anchors it to a known surface. An agent can separate it from ot_search_rooms and ot_room 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?

It gives explicit trigger conditions ('Use when the user's room is full or too expensive') and names follow-on tools (ot_room, ot_price_quote). It does not contrast itself against sibling discovery tools like ot_search_rooms, so the 'when-not' side is thin, but the routing guidance is real.

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 readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds real behavioral value by disclosing the four content blocks returned and the cross-tool handoff pattern (related_pages slugs feed ot_search_rooms city_tag); only auth/rate-limit details 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?

Front-loaded with the returned content, followed by a short when-to-use sentence and one routing note. No filler sentences, though the parenthetical enumeration of examples is slightly dense.

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 an output schema present, the description need not define return values, yet it helpfully summarizes them. It covers purpose, trigger, and one downstream integration, leaving only edge-case behavior (pagination, empty results, locale of blog_query) unaddressed.

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 kind, place, max_chars and blog_query are already documented in the schema, including examples and defaults. The description adds little parameter-level detail beyond implying that related_pages slugs (themes) are usable identifiers, which is indirect. 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 and resource ('Get the site's travel guide for a destination') and then enumerates the concrete payload: guide text, FAQ, related search pages with listing counts, and blog articles. It is clearly distinguishable from siblings like ot_search_rooms or ot_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?

It gives an explicit trigger condition ('Use when the user asks what a place is like or what to do there') and even routes a downstream step to ot_search_rooms via city_tag. It stops short of naming when a sibling (e.g. ot_destinations) would be the better pick, so it is strong context without explicit exclusions.

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