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

Annotations already declare this a safe, idempotent, open-world read, so the safety profile is covered. Beyond that, the description discloses a meaningful behavioral trait: the result shape depends on mode, and the `attraction_id` mode returns text, coordinates, and type. It leaves the list-mode return shape and any truncation/paging behavior unaddressed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, front-loaded with the primary list behavior before the detail mode, and no filler or marketing language. There is mild redundancy, since "read the description of one" and "you get its text, coordinates and type" describe the same mode twice.

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 five parameters, no output schema, and rich annotations, the description does enough: it explains both invocation modes, the key parameter that switches modes, and the cross-tool workflow. The remaining gaps, pagination/`limit` behavior and the exact list-mode payload, are modest given 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 description coverage is 80% and the schema already explains `city`, `type`, `query`, and `attraction_id`. The description mostly restates the `attraction_id` mode rather than adding new meaning, and it says nothing about `limit` (default 20, cap 60) or how `query` interacts with `type`. Baseline 3 is appropriate when the schema carries the parameter load.

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 specific verb and resource and describes its dual mode, listing ('sights, shrines, malls and other places of a city') or reading a single attraction's detail. An agent can immediately tell this is the POI-lookup tool rather than a hotel or search tool. It does not, however, explicitly state what it is not relative to closer siblings like eg_cities or eg_photos.

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 two concrete scenarios: acting as a city guide ("what to see in Mashhad") and sourcing an attraction `id` to pass to eg_search as `attraction_id`. That is actionable routing guidance between tools with a clear handoff. It stops short of stating when to prefer a different tool or what happens if the city is unknown or empty.

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

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

Beyond the read-only, non-destructive annotations, it discloses that results are ordered biggest-first and that counts are Eghamat24's own totals rather than result-count estimates. The exact metric behind "biggest" remains unspecified, but the added ordering and provenance context are useful.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description front-loads the core listing behavior, then gives the downstream use and finally ordering and count provenance. All three short paragraphs contribute distinct, actionable information without 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?

For a simple three-parameter discovery tool, the description and schema together cover selection, invocation, output content, ordering, and the format expected by downstream tools. Although there is no output schema, the description supplies the important return semantics without needing a full response-shape specification.

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?

With 67% schema coverage, the schema already explains `kind` and `query`, while the description mainly clarifies the downstream city output with slug examples. "Biggest destinations first" indirectly helps interpret `limit` as taking a top-ranked subset, but it never explicitly explains that otherwise undocumented 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 description uses a specific verb and resource—listing Eghamat24 destinations with hotel and stay counts—and then clarifies its role as a city-slug discovery step. Naming eg_search and eg_deals as consumers distinguishes it from those 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?

It explicitly says to use the tool to obtain the English `city` value for eg_search and eg_deals, providing a clear workflow. It does not add exclusions or explain when province mode is preferable, so the guidance is strong but not exhaustive.

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, openWorld), so the description correctly spends its words elsewhere: it defines what a 'discount' means (the site's own percent off list price) and states the bookable-only filter, both non-obvious behavioral facts. It does not mention result ordering explicitly or what happens when no deal meets the threshold.

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 the core behavior, then the example, then the definition and follow-up. No filler; the only marginal sentence is the eg_rooms pointer, which still earns its place as routing guidance.

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 7 parameters, 57% schema coverage and no output schema, the description should say what a deal record contains and what the 'stay' kind changes. It conveys the ranking concept but leaves the return shape and one enum ambiguous, so it is adequate rather than complete.

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 57%, and the description adds meaning mainly for the discount concept, which underpins min_discount. The 'kind' enum (hotel vs stay) is left completely unexplained in both schema and description, and limit/min_stars/nights get no elaboration, so the description does not compensate for the coverage gap.

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 opens with a specific verb and resource plus three scoping constraints: 'List the hotels of a city', 'with the biggest discounts for the given dates', 'bookable ones only'. That is enough to tell it apart from the generic eg_search/eg_hotel siblings 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?

It supplies a concrete trigger phrase ('any good offers in Esfahan this weekend') and an explicit follow-up path to eg_rooms for room-level detail. It stops short of naming when NOT to use it — e.g. versus eg_search or eg_specials — so an agent must still infer the boundary.

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 safety is covered. The description adds genuinely new semantics — that scores are out of 10 and that `rating` is the same value rescaled to 5 points — which prevents misreading the returned numbers. It does not discuss rate limits, caching, or failure modes for an unknown hotel slug, leaving a small 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?

Front-loaded with the payload contents, then routing guidance, then a data-semantics footnote about the rating scale. Three tight sentences with 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?

With no output schema, the description carries the burden of telling the agent what comes back, and it does so by listing the profile sections and clarifying the two score scales. For a one-parameter read tool, nothing an agent needs to call and interpret it 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% and the schema description already documents all three accepted identifier forms with an example, so the single parameter is fully specified in structured data. The tool description adds nothing about the `hotel` argument, 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 ('Get one hotel's profile') and then enumerates the exact contents: address, stars, check-in times, description, facilities, rules, guest scores, extras, nearby places. This is clearly distinguishable from siblings like eg_rooms or eg_reviews, which target subsets of that data.

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 situates the tool in a workflow ('Use it after eg_search to compare hotels on amenities') and names two alternatives with the condition that selects them: eg_rooms for dated prices, eg_reviews for guest comments. Both when-to-use and when-not-to-use 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, open-world, non-destructive, so the safety profile is covered. The description adds genuinely new behavioral context: the results are full-size JPEG URLs hosted on eghamat24.com and are organized into main picture, gallery, and per-room-type groups, which no structured field discloses. It omits any note on how limit truncates or whether ordering is stable.

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 with zero padding, and the core scope statement (what photos are returned) is front-loaded ahead of the usage hint. Nothing could be removed without losing 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 two-parameter, read-only listing tool with no output schema, the description covers what is returned (main, gallery, room-type photos) and in what form (full-size JPEG URLs), which is exactly what the agent needs since no output schema exists. Only truncation behavior for the limit is 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 both parameters are already fully documented in the schema, including the three accepted hotel identifier formats. The description adds only the implicit hint that photos are grouped per room type; it says nothing extra about the hotel or limit parameters. 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 the photo URLs of a hotel') and breaks the scope into three concrete parts: main picture, hotel gallery, and per-room-type photos. This distinguishes it well from eg_hotel (hotel detail) and eg_rooms (room data), though it never names those siblings 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?

'Use it to show or describe how a hotel and its rooms look' gives a usage context but no explicit when-not conditions or pointers to alternative tools such as eg_hotel or eg_rooms. An agent can infer the intent, but routing between photo retrieval and hotel/room detail retrieval is left to inference.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so safety is covered. The description adds useful behavioral context: one row per night, lowest price in Toman, the qualifying room, or sold out. It omits caching, rate limits, or how 'sold out' nights are represented internally, which are minor gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Four short sentences, front-loaded with the core purpose, then an example query, then the row shape, then the sibling pointer. 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?

Given a read-only tool with full annotation coverage, complete parameter documentation, and no output schema, the description supplies what is needed: the per-night row shape, currency, and the sold-out case. Nothing material needed 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%, and the schema already documents the hotel identifier formats, the 1–31 night range, and the date default. The description only implies date-range filtering and does not add 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?

States a specific verb and resource: 'Show the cheapest bookable room price for each night over a date range, to find the cheapest days to stay.' It also explicitly differentiates from the sibling eg_rooms, which returns the full room list for one stay.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives a concrete use case ('when is Parsis cheapest this month') and names an alternative, eg_rooms, for full room lists. It does not address potentially overlapping siblings like eg_deals or eg_specials, so routing guidance is strong but not exhaustive.

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, open-world behavior, so the safety profile is covered. The description adds genuinely useful context — that answers may be absent and that the content is untrusted user text — but says nothing about result size, ordering, or what happens when the hotel cannot be resolved.

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 with the core action front-loaded, then usage, then a safety caveat. Nothing is redundant; the injection warning earns its place because it changes how an agent handles the output.

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?

Since there is no output schema, the description should hint at the shape of results (question, answer, dates, ordering), and it only says answers may be absent. The hotel-identifier formats and the undocumented `limit` are the remaining gaps for a simple two-parameter lookup.

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 only 50%: the `hotel` parameter is well documented in the schema (three accepted formats), but `limit` has no description at all and the description text does not compensate by explaining paging or result caps. With low coverage the description should have filled this gap and does not.

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: reading public guest questions plus their answers for a given hotel. This is clearly distinct from review-style siblings like eg_reviews, though the description never names that sibling to make the distinction explicit.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives concrete when-to-use guidance with examples (transfers, parking, family rules) and contrasts with the facility list, implicitly routing agents away from eg_hotel for these practical details. There is no explicit when-not clause or named alternative, but the context is clear.

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 behavior, so the bar is lower. The description adds real value beyond them: newest-first ordering, the 10-per-page paging implication, the score breakdown appearing only on page one, and an explicit safety note that reviews are user content rather than instructions — a useful prompt-injection guard.

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 compact paragraphs, front-loaded with what the tool returns and ordered by importance. The enumeration of review fields earns its place by telling the agent what data to expect, though the trip-type parenthetical is slightly 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 no output schema, the description carries the return-value burden and does so: it explains the per-review fields, ordering, page size behavior, and where the score breakdown lives. For a two-parameter read-only tool with annotations covering the safety profile, nothing essential 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 both parameters are already documented, including the accepted hotel identifier forms and page size. The description only nudges page semantics by noting the score breakdown is tied to the first page, which the schema does not say; otherwise it adds no new parameter meaning.

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?

"Read guest reviews of a hotel, newest first, with the overall guest scores and who travelled" states a specific verb (read) and resource (guest reviews) plus scope details like ordering. It is clearly distinct from eg_hotel, eg_photos, and eg_questions by naming the review resource, though it never explicitly contrasts itself with a sibling.

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 it to judge quality" gives an implied context for use, which is better than nothing. However, no alternative is named (e.g., eg_hotel for aggregate scores or eg_questions for guest Q&A), and there is no guidance on when this tool is the wrong choice.

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, so the description's job is to add context — and it does: result ordering, what each field means (total, avg_night, list_total, rooms_left, free_cancel), and that non-bookable offers are surfaced in `not_bookable` with a reason. It adds no auth, rate-limit, or pagination-truncation behavior, which keeps it from 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?

Purpose and ordering are front-loaded in the first sentence, then the example, then return semantics — a sensible structure. The backtick field inventory is long but justified because there is no output schema; only the repeated date example is mildly 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 correctly takes on explaining the response shape and the not_bookable bucket, which is the main completeness risk here. The remaining gap is what `limit` (default 25, max 60) does to results — whether truncation is silent — which matters for an open-world listing 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 80%, so the schema already documents hotel formats, guests, nights, and check_in. The description adds no new meaning for `limit`, `guests`, or `nights`, and its only parameter-relevant contribution is the Jalali date example that echoes the schema's own note. 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 and resource ('List a hotel's bookable rooms with the price for the stay') plus the ordering guarantee ('cheapest first'), and the per-stay rate-plan framing distinguishes it from date-level price tools like eg_price_calendar. An agent can tell exactly what comes back 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?

The worked example ('how much is a double room at Parsis on 1405-08-19 for 2 nights') plus the closing 'This tool only reads prices; it cannot reserve' give clear use context and one explicit exclusion. It stops short of naming when to prefer eg_price_calendar, eg_deals, or eg_hotel instead, so the sibling routing is left to inference.

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

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

With readOnlyHint/idempotentHint already supplied by annotations, the description still adds substantive behavior: price_from is the lowest room price per night and often a single-bed room, stay_total applies when nights > 1, and status distinguishes available / min_stay / sold_out. The note that guests only adds price_for_guests for the first 12 cards is a genuine partial-result caveat an agent could not infer elsewhere.

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 sentence, followed by examples, then field semantics, then sibling routing - a sensible order. It is dense but nearly every clause carries information; only the parenthetical about the site showing the same figure is slightly 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?

For a 19-parameter search with no output schema, the description covers the essentials: what a result card contains (hotel, price_from, stay_total, status) and how to chain into the detail tools. It does not address the limit/pagination cap (max 60) or the kind=stay path, which are the remaining gaps.

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 84%, so the baseline is 3; the description earns more by explaining the price fields that the schema leaves ambiguous (price_from vs stay_total vs price_for_guests, Toman, per night) and by illustrating sort, min_stars, facilities and area with real values. Some parameters (kind, beds, board, name, max_price) are left entirely to the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The opening sentence names a specific verb (search), resource (hotels), scope (a city, given dates) and the return shape (cards with the lowest price). It is clearly separable from eg_rooms, eg_hotel and eg_reviews, which are named later in the text.

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 maps concrete user questions to parameter combinations ("cheapest 4-star in Kish" -> sort=price_asc, min_stars=4; "with a pool near the shrine" -> facilities, area), which tells the agent exactly when this tool fits. It also explicitly routes follow-ups: eg_rooms for room prices, eg_hotel for facilities/rules, eg_reviews for opinions.

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 genuinely useful behavior beyond that: it warns that `price_from` is an *undated* starting price rather than a real quote for specific dates, which prevents a classic misreading. It does not mention result count behavior beyond the schema default, which keeps it from 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 sentences: the purpose first, then the trigger condition plus the clarifying caveat about price semantics. No filler, and the most decision-relevant facts (what it returns, when to call it, what the price means) are 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?

For a two-parameter read-only tool with no output schema, the description covers what the agent most needs: what comes back (a list of alternatives plus a starting price) and the semantics of that price. The only omission is the behavior of `limit` and what a returned alternative entry contains, both minor given the tool's simplicity.

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 50%: the `hotel` parameter is well documented in the schema (path form, full URL, or city/hotel slug), but the description only clarifies `price_from`, which is a returned field rather than an input. The `limit` parameter (default 8, max 10) is undocumented in both schema and description, so the description does not compensate for the coverage gap.

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 the hotels the site suggests as alternatives to one hotel, with a starting price') and scopes it to a single input hotel, which separates it from the sibling search tools (eg_search, eg_hotels listings) without ambiguity. An agent can tell at a glance that this is a recommendations endpoint, not a search.

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 it when a hotel is sold out or too dear' gives an explicit trigger condition, and the second sentence names concrete alternatives ('get real prices for dates with eg_rooms or eg_search'), which also implies the negative case (do not use this for dated pricing). Both when-to-use and when-not-to-use are inferable from named 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 read-only/idempotent/open-world, and the description adds genuinely new behavioral context: these pages carry no dates, price_from can change, and it is null when the site lists no price (derived from tomorrow's search when free rooms exist). That is real snapshot semantics the agent could not infer from 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 resource and the three variants, then the caveats. Compact overall; the parenthetical about tomorrow's search is dense but earns its place by explaining the null case.

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 3-parameter read tool with no output schema, this covers the important gaps: no dates on these pages, price_from semantics and null behavior, and the handoff to eg_rooms. Only the limit/pagination behavior is absent.

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 67% and the kind enum is already self-documented, so the description mainly restates the city/kind dependency. It does add meaning for the returned price_from field, which is useful given no output schema, but leaves the limit parameter entirely undiscussed.

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 hotels on one of the site's offer pages') and enumerates the three offer kinds, which maps directly to the kind enum. It does not, however, distinguish itself from the sibling eg_deals, which an agent could easily confuse with this 'latest discounts' page.

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-case phrasings ('hotels with free cancellation in Shiraz', 'any one-night offers') and an explicit next step ('Follow up with eg_rooms for dates'), so the agent knows this is a discovery step, not a booking/availability call. No explicit exclusion versus eg_deals or eg_search.

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 a safe, idempotent read, so the description doesn't need to cover safety. It adds genuine behavioral context beyond them: a missing day means no package exists because flights are full, and prices are aggregated across all adults in Toman. It doesn't address result ordering or whether availability reflects live inventory, but the key failure mode (empty day) is explained.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Four short sentences, each carrying a distinct piece of information: purpose and output shape, use case, missing-day semantics, and price units plus an alternative tool. The purpose is front-loaded and nothing is repeated from 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 no output schema, the description appropriately explains what comes back (a per-day cheapest package price, Toman, aggregated across adults) and what absence means. It stops short of describing the date format of returned entries or ordering, which would help an agent parse the list without a 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 the baseline is 3. The description adds meaning beyond the schema by clarifying that the quoted price covers all `adults` together and that the list is keyed on departure days, which tells the agent how `adults` and `from_date` affect the returned values rather than just their input format.

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 and resource: 'Show the cheapest flight-plus-hotel package price for each departure day.' The package (flight+hotel) framing distinguishes it from hotel-only tools, and it explicitly routes hotel-only lookups to eg_tours. However, it never mentions the closely named sibling eg_price_calendar, which an agent could easily confuse with this 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?

It gives an explicit use case ('when is a Tehran to Kish tour cheapest') and points to eg_tours for a single-day hotel list. What's missing is routing against the other price-oriented siblings (eg_price_calendar, eg_deals, eg_search), so an agent comparing calendars must infer the difference from the name alone.

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 only cover read-only/idempotent/open-world; the description adds currency (Toman), that flights are included in price, what `price_total` aggregates across adults, that only some cities sell tours, and the crucial interpretation of empty results (seats full) with a concrete recovery path. That is exactly the behavioral context annotations cannot provide.

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 compact paragraphs: purpose and mode behavior first, then the empty-result edge case. Every sentence carries information an agent could not get from the schema, and no sentence is filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 8 parameters and no output schema, the description compensates by describing both result shapes (hotel list with cheapest package, or one hotel's room/meal/flight packages), the pricing units, and the failure mode. Nothing needed to call this correctly appears to be 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 already 88%, so the baseline is 3, but the description adds real meaning: `hotel` changes the entire response shape, and `adults` is described as travelling together sharing one room, which explains why both total and per-person prices appear. Dates, sorting, and limits are left to the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The first sentence names the resource (flight-plus-hotel tour packages) and states the two distinct modes: city-level hotel listing vs. single-hotel package listing with flight times. This is a specific verb+resource statement that an agent can act on 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?

It gives a concrete natural-language example ('Tehran to Mashhad for 2 nights with the flight included') and explains the mode switch via the `hotel` parameter, plus a fallback to eg_tour_calendar when results are empty. It does not explicitly say when to prefer eg_hotel or eg_deals over this tool, which keeps it 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.