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

The annotations already cover safety (readOnly, idempotent, non-destructive, openWorld), so the description earns credit by adding the operational details those hints can't: the 14:00–23:50 Iran-time window, that last_second prices are undated, and that city-supplied calls silently drop that list. It stops short of describing result shape or any rate/refresh 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?

Three tight sentences, front-loaded with what the tool returns, then the per-list caveats, then the sibling handoff. Dense but every clause carries information; only mild redundancy in the opening 'Current discounts:' framing.

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 the return-value burden and largely does: two named lists, their membership rules, ordering, and the date-dependence of prices. Minor gaps remain, e.g. that `limit` applies per list and whether results can be empty for a city with no discounted inventory.

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 goes beyond it by explaining what `city` actually does to the result set (excludes last_second) and how dates change pricing (prices are for that stay vs undated), which the schema alone does not 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 description names a concrete resource and its two constituent lists ('last_second' deals and 'most_discounted' stays), plus the sort order (biggest percent first). An agent can tell exactly what comes back without opening any schema, and it distinguishes itself from ot_search_rooms/ot_search_filters by being a discounts view.

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 real conditional guidance — last_second is omitted when `city` is supplied, and dated queries change the price semantics — and routes the agent forward to ot_price_quote for totals. What's missing is when NOT to use this tool versus ot_search_rooms or ot_search_filters for a general availability search; usage is implied rather than contrasted.

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/openWorld/idempotent/non-destructive, so the safety profile is covered. The description adds a genuine behavioral nuance beyond the schema: when `collection` is supplied, the response also lists the cities that collection covers (as city slugs), which changes what the caller should expect back.

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 clause; the core purpose is front-loaded and every sentence carries actionable information (examples, trigger condition, sibling linkage). 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?

There is no output schema, so the description carries the burden of hinting at returns; it does this by noting the city-slug listing behavior. For a zero-required-param read tool this is nearly complete, though it could say more about the shape of the default (no-argument) response.

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 the schema already documents `collection` with an example ('beach'), so baseline is 3. The description goes further by explaining the semantic effect of passing the parameter (it switches the tool to listing covered cities and yields slugs), adding meaning beyond the schema text.

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 ('popular cities and collections') and clarifies what collections are with concrete examples ('themed landing pages: discounted, jungle villas, villas with pool'). It does not explicitly differentiate itself from sibling discovery tools like ot_deals, ot_travel_guide, or ot_find_place, so it stops short of a 5.

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 triggering condition ('use when the user has no destination yet') and names the downstream consumer ('to find collection codes for ot_search_rooms `collection`'). It lacks an explicit when-not clause (e.g., what to use once a destination is known), which keeps it from a 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 declare readOnly, idempotent, non-destructive and openWorld, so the safety profile is covered. The description adds real behavioral context beyond them: cities carry an undated listing count, a province listings number is not a search count, and room names are not queryable here.

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 and no wasted sentences; the caveats each carry distinct meaning. It is telegraphic and slightly dense, but nothing is redundant.

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 describe what comes back (city with listing count, province listings, room from a code) and flags the two input modes. Complete enough for a single-param resolver, though return structure could be spelled out a touch more.

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 the single query param is fully documented with format and examples, so the baseline is 3. The description adds the dual-mode meaning (place name vs room code) and what each resolves to, going slightly beyond 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: resolving a place name into city/province slugs, or a room code into its room. It distinguishes itself from siblings by naming ot_search_rooms and ot_room as the tools that consume its output.

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?

Explicit routing is present: 'Room names are not searchable here: use ot_search_rooms with name' gives a clear when-not, and 'Next: ot_search_rooms, or ot_room for a room hit' names the alternatives and the condition selecting each.

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, non-destructive, and open-world, so the safety profile is covered. The description adds the genuinely useful behavioral detail that no-query returns all questions/section titles with previews while query returns matching items or paragraphs — a real difference in return shape the annotations do not convey.

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, zero filler. The domain list is front-loaded, the query behavior is explained next, and the sibling redirect closes with no wasted words.

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-parameter read-only content tool with no output schema and full schema coverage, the description is complete: it covers scope, both parameter modes, the enum topics, and the one ambiguous case (room-level policy) by naming the correct alternative.

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: it explains the query parameter's effect on result granularity (whole list vs. matching paragraphs) and names the topic domains in prose, reinforcing the enum. It adds semantic value beyond the schema's terse 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 verb (Read) and resource (Otaghak's help center), and enumerates the content domains (FAQ, guest terms, host rules, quality policy). It also explicitly distinguishes itself from ot_room for room-specific cancellation policies, which no other sibling covers.

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?

Explains the query/no-query branching clearly, telling the agent when to search versus when to list whole sections, and routes room-specific policy lookups to ot_room. It does not, however, say when to choose this over ot_travel_guide or ot_reviews, which are plausible adjacent content 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 cover the safety profile (readOnly, idempotent, non-destructive), and the description adds genuinely non-obvious behavior: holiday flags are only populated ~7 weeks ahead, and blank days mean 'unknown, not working days'. It also discloses the return content (Jalali dates, weekdays) with no output schema present.

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 tight sentences, front-loaded with what the tool returns, then the critical data-freshness caveat, then the usage/pricing hook. No filler 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 two-parameter read-only lookup with no output schema, the description supplies everything needed: what comes back, the reliability limit on the holiday flags, and where to go for the pricing consequence. Nothing an agent needs to call 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 description coverage is 100%, so both date parameters, their formats, and the one-year maximum span are already documented in the schema. The description adds no format or constraint detail beyond that, 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 scope ('in a date range') and output content ('with Jalali dates and weekdays'). It distinguishes itself from the sibling ot_room_calendar by cross-referencing it for pricing context rather than duplicating it.

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 'Use to plan around long weekends' and points to ot_room_calendar for the price implication of weekend nights and holidays. No explicit when-not-to-use or exclusion of other date tools, so it stops short of a 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, open-world and non-destructive semantics, so the burden is lighter. The description nonetheless adds real behavioral context beyond them: prices are 'undated starting prices,' reviews are the 'newest across all their rooms,' and long text is clipped unless requested. Auth/rate-limit behavior is not discussed, keeping it out of 5 territory.

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: the return payload is front-loaded, then the invocation modes and intended use. No filler, no repetition of the title.

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?

There is no output schema, so the description must characterize the return, and it does so explicitly by listing the profile fields. Combined with the input-mode guidance and the clipping caveat, an agent has everything needed 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 100%, so the schema already documents all five parameters. The description clarifies the host_id/room_id input-mode choice, but adds nothing for full_text, rooms_limit or reviews_limit. 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 specific verb ('Check') and resource ('a host') and enumerates exactly what the profile contains: response time, response/acceptance rates, member since, active rooms, newest reviews. An agent can distinguish this from ot_room or ot_reviews 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?

Explicitly tells the agent how to invoke it ('Pass host_id, or room_id to find the room's host') and names the intent ('judge whether a host is reliable or to see their other places'). It does not, however, explicitly name a sibling alternative such as ot_reviews for pure review retrieval, so it falls just short of a 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 the safety profile (readOnly, idempotent, non-destructive, openWorld), so the bar is lower; the description still adds real behavioral context: the price unit is Toman and explicitly flagged as unverified, and it warns that offered rooms are often closed for late checkout on a given day. That quirk is genuinely useful and not derivable from 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 usage. The second sentence is a bit clause-heavy ('with check_out whether it can be booked on that departure day') but every element carries information and nothing is redundant 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 does the work of describing the return surface (offered or not, hours, price, bookability), which is what an agent needs. Minor gaps remain, such as how an 'unavailable' result is signaled, but it is nearly complete for a 2-parameter read 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 100%, so the baseline is 3. The description goes beyond the schema by explaining what check_out actually does behaviorally (determines whether late checkout can be booked on that departure day) rather than merely restating 'departure day to check'.

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 whether a room offers late checkout) and enumerates the exact facets returned: availability, number of hours, price, and bookability on a given departure day. This is clearly distinguished from siblings like ot_price_quote, which it explicitly frames as a complementary tool.

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 triggering condition ('Use when the user wants to leave later than the check-out time') and names the related tool plus the parameter that connects them ('ot_price_quote adds it to a total with late_checkout_hours'). An agent knows both when to call this and how it chains.

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?

With annotations already covering readOnly/idempotent/non-destructive, the description adds substantial behavior: nightly rounding to 1,000, price_before_discount omitted when no discount, available=false plus reason on failed checks, and a partial-success path where unbookable late checkout keeps the quote with late_checkout.available=false.

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 payoff (what amount is returned and its parts) then covers edge cases; every sentence carries information. It is dense with parentheticals and slightly long, keeping it just shy of a 5.

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, so the description must explain return values, and it does so thoroughly (field names, rounding behavior, absent fields, failure shapes). For a 5-parameter quote tool this is complete enough to invoke 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%, so the baseline is 3, but the description adds semantics the schema lacks: nights_total is for the base guests, and late_checkout_hours is treated as optional and may silently return available=false. It does not add format or boundary detail beyond 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 the amount to pay (Toman) for a room, dates and guests', and enumerates the returned components (nights_total, extra-guest charge, late checkout, total). Its combined pricing-plus-availability scope functionally distinguishes it from siblings like ot_room_calendar and ot_search_rooms.

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 usage trigger: 'Use before the user books on otaghak.com', establishing it as a pre-booking validation/quote step. It does not, however, name alternatives (e.g. why not ot_room or ot_search_rooms) or state when-not to use it.

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, and non-destructive, so the safety profile is covered. The description adds genuinely new behavioral context: ordering (newest first), inclusion of host replies, and the edge case where rating is null and reviews are empty for new rooms — a detail not in 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 sentences, front-loaded with the returned payload and followed by the caveat and routing guidance. 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?

There is no output schema, so the description must convey the return shape — and it does, listing rating, histogram, category scores, recommendation percent, and reviews. Combined with the edge-case note, an agent has everything needed to call and interpret this 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 100%, so page, limit, room_id, and full_text are all documented in the schema itself (including clipping behavior tied to full_text). The description adds no parameter-level syntax or format detail, 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 — retrieves a room's rating, star histogram, category scores, recommendation percent, and written reviews — and implicitly distinguishes itself from ot_host, which covers reviews across all of a host's rooms.

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 timing ('Use after ot_room or ot_search_rooms to judge quality') and names the alternative sibling (ot_host) with the condition that selects it. An agent can route correctly without opening either schema.

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/non-destructive/openWorld, so safety is covered. The description adds non-obvious behavior the schema does not: the nightly price is an average for the given dates even when those dates are booked, and instant_on_some_nights is only a room-level flag whose per-night truth lives in ot_price_quote/ot_room_calendar. That is real disclosure 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?

Field list is front-loaded and each sentence carries information, but the middle paragraph is long and parenthetically dense, requiring a careful read. Slightly more compact phrasing would preserve all the value.

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 return contents by enumerating the returned fields, which is strong. It leaves minor gaps such as how clipping interacts with full_text and how approximate location is expressed, but an agent can 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 coverage is 100%, so the baseline is 3, but the description goes further by explaining what check_in/check_out actually change (date-specific average price vs. undated starting price) and that they do not indicate availability. That is meaning beyond the schema's format hints.

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 one room') plus the resource and enumerates the exact payload it returns (description, capacity, beds, amenities, house rules, price, etc.). That is far more than a restatement of the title and lets an agent know precisely what a single-room fetch yields.

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 prerequisites ('Use after ot_search_rooms or ot_find_place') and names the correct follow-on tools for each intent (ot_price_quote for exact total, ot_room_calendar for free nights, ot_reviews, ot_host, ot_similar_rooms). Both when-to-use and what-to-use-next 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 readOnly/idempotent/non-destructive/openWorld, so the safety profile is covered. The description adds real behavioral semantics beyond them: pricing is anchored to the arrival day, and absent keys have defined defaults (no discount, instant/weekend/holiday/late_checkout = no), which is exactly the kind of context an agent needs to interpret 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?

Front-loads the core purpose and then compresses the return fields into a dense list; each clause (absent-key defaults, next step) carries information. The telegraphic style is slightly terse but not padded, so every sentence 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?

With no output schema, the description does the work of describing the return payload field by field and explains how missing keys should be read, which is essential for a calendar-dump tool. Coverage is strong, though the encoding of 'free or booked' and the min/max nights fields could be spelled out a bit more.

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 start/end/room_id defaults are already documented in the schema, establishing a baseline of 3. The description's 'A night is priced on its arrival day' helps interpret the day-keyed response, but adds no syntax or format detail for the individual parameters themselves.

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+granularity ('Get a room's calendar day by day') and enumerates exactly what each day contains (price before/after discount, free/booked, instant booking, min/max nights, weekend, holiday, late checkout). This is clearly distinguishable from siblings like ot_room or ot_price_quote, which are routed to 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 concrete use cases ('find free dates, cheap nights or allowed stay lengths') and names the natural follow-up tool ('Next: ot_price_quote for a stay'), which routes the agent well. It does not state when NOT to use this tool or contrast it with ot_room, so it stops short of explicit exclusion 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 destructiveHint=false, so safety is covered. The description adds real behavioral value by enumerating what is returned (price range in Toman, room type ids, filter codes, districts/landmarks), which is important since no output schema exists. It does not mention auth or rate limits, keeping it short of a 5.

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 that are front-loaded with the core action and scope, then the return contents and usage trigger. Slightly dense, but every clause carries information an agent needs; nothing is 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 no output schema, the description correctly compensates by describing the return payload. Combined with annotations that cover the read-only/idempotent profile and a fully documented schema, the definition is complete enough to call correctly, though it omits response shape/pagination detail.

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 each of the three optional params is already documented with slug examples and the extra data it returns. The description mostly restates that scope without adding syntax or format detail beyond the schema, 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?

The description gives a specific verb ('List') and resource ('search filters'), states the scope (city, province, collection, or whole site), and explicitly frames the tool as the code-lookup companion to ot_search_rooms. An agent can distinguish it from ot_search_rooms and ot_destinations without opening any 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 asks for an amenity, a rule, a room type or a place near a landmark' gives concrete triggering contexts, and naming ot_search_rooms as the consumer of these codes implies the workflow. There is no explicit when-not-to-use statement or exclusion, but the intended usage is unambiguous.

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 non-destructive, so safety is covered. The description adds real behavioral context beyond that: with dates every room is available and priced (price_per_night as average after discount, stay_total including extra-guest charges), and it honestly caveats that the total is an estimate that 'can be a few Toman off'. It does not describe pagination behavior, hence not a 5.

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 paragraphs, front-loaded with what the tool does, then the pricing semantics, then the cross-tool routing. No filler sentences; every clause carries either scope, behavior, or navigation 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?

For a 22-parameter, zero-required search tool with no output schema, the description covers the essential ambiguities: date-dependent pricing, guest-based filtering, and which sibling to call for detail or exact totals. It stops short of describing the returned result shape (list vs. envelopes, pagination signals), which a first-time caller would still have to infer.

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 baseline is 3. The description goes beyond the schema by explaining where parameter values come from (city slugs via ot_find_place, filters/room_types/district_id via ot_search_filters, collection via ot_destinations) and by explaining how dates change the meaning of returned prices for the guests parameter.

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 names a specific verb and resource ('Search Otaghak stays') and enumerates the scope (villas, cottages, apartments, eco-lodges) across city, province or collection. It is immediately distinguishable from sibling tools like ot_room (details) and 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?

Explicit prerequisites are given ('Get slugs from ot_find_place, filter codes from ot_search_filters') and explicit follow-ups are routed ('Next: ot_room for details, ot_price_quote for the exact total, ot_room_calendar for other dates'). It also states the condition that changes behavior: providing check_in/check_out vs. omitting them.

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?

Adds behavior well beyond the annotations: the upstream-empty fallback (search up to 1.5x price, flagged in `note`), the pricing semantics (undated starting prices without dates, re-priced with dates), and the not_available handling for booked/too-small rooms. Annotations only cover the safety profile, so this is genuinely additive.

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 and scoped follow-ups (pricing, availability, usage) in a tight four-sentence block. The first sentence's nested parenthetical is slightly dense but not wasteful.

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 return-format burden and does name key fields (not_available, `note`). The structure of the primary alternatives list itself is left implicit, a minor gap for a no-output-schema 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 coverage is 100%, so baseline is 3, but the description adds real semantics: `guests` determines which rooms land in not_available rather than merely filtering, and check_in/check_out change pricing versus the undated starting prices. It doesn't clarify date-range limits beyond what the schema already says.

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: 'Get 4-5 alternatives to a room (same city and type)', plus the fallback scope while the upstream list is empty. An agent can distinguish this anchored-to-a-room lookup from the broader ot_search_rooms from the text alone.

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 trigger ('Use when the user's room is full or too expensive') and names follow-on tools ('Next: ot_room, ot_price_quote'). It stops short of an explicit when-not or a contrast against ot_search_rooms, so it falls just below 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 useful composition context (what data areas the guide aggregates) but doesn't disclose clipping behavior or defaults, which full_text and max_chars imply but don't explain.

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 verb and the enumeration of return content, then a clear when-to-use block. The parenthetical examples (beach, cottage, apartment) and blog subtopics add length but are informative rather than 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?

A read-only aggregation tool with a fully documented schema; the description covers purpose, trigger, contents, and one cross-tool chaining case. Return format details are appropriately left to the schema/annotations, though the clipping behavior when full_text is false could be spelled out.

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 every parameter is already documented, including what place/kind mean and the max_chars clipping behavior via full_text. The description adds the cross-tool hint that related_pages slugs map to ot_search_rooms `city_tag`, but no additional parameter syntax or format detail beyond 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 (get) and resource (travel guide for a destination) and enumerates the return contents (guide text, FAQ, related search pages, blog articles). This distinguishes it from siblings like ot_destinations or ot_find_place, which locate destinations rather than describe them.

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 gives the trigger condition ('when the user asks what a place is like or what to do there') and a concrete chaining instruction routing theme slugs to ot_search_rooms `city_tag`. No exclusion guidance for other guide-like siblings, but the when-to-use is clear.

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