Fly Travel Albania

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

Annotations already declare readOnlyHint and idempotentHint, and the description adds that the tool is a 'Pure URL builder (no data)' and clarifies child age behavior at departure. This goes beyond the annotations by explicitly defining the output as a URL and the no-side-effect nature.

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 is concise and front-loaded with the core purpose. All sentences are relevant, though the child-age sentence partly duplicates the schema's own parameter description, which keeps it from a perfect score.

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 clearly states the return is a URL. Combined with full schema coverage and readOnly/idempotent annotations, the tool is sufficiently described for an agent to invoke 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 adds the 'children ages 0-14 at departure' rule and 'optional trip length' phrasing, but these largely mirror the schema's existing property descriptions, providing limited additional value.

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 clearly states the tool builds a deep link into live charter search results for a destination, date, party, and optional trip length, and that the output is a URL to hand to the user. It differentiates itself from data-returning sibling tools with 'Pure URL builder (no 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?

The description gives clear context for when to use the tool: when the user wants to see live availability and book by receiving a URL. It does not explicitly name alternatives or exclusions, but the intended use case 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 declare readOnly, idempotent, non-destructive. The description adds valuable behavioral nuance beyond that: cached data with cached_at/age_minutes, package totals not per person, party_match=false semantics, and the strict rule that a price belongs only to its own date. These are critical to correct use and not present in 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?

Dense but every sentence earns its place. The main function is front-loaded, followed by usage routing, then three essential caveats about cache, pricing units, and date-attachment. Despite length, 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 read-only, single-parameter, no-output-schema tool, the description covers purpose, when to use it, data provenance, unit semantics, and the most dangerous misuse (misattributing a price to a different date). Nothing critical 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?

Input schema covers the single 'destination' parameter 100%, including the note that omitting it returns every destination. The description does not add meaning beyond the schema; the main value is in interpreting returned rows, not in parameter syntax.

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?

Description opens with a specific verb and resource: 'Cheapest flight+hotel charter packages from Tirana (Albania) per destination, from the live booking-engine cache.' It further clarifies it returns the 5 cheapest per destination, each on its own date. This clearly distinguishes it from siblings like charter_offers.

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 when to use: 'Use for "what is the cheapest…" only; for advice or filtering use charter_offers.' It also warns that prices are cached and not live queries, setting correct expectations about freshness.

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, and non-destructive behavior. The description adds valuable operational context beyond that: the calendar is cached, nights are actually on sale, and total_count/has_more warn that the response may be a capped subset, so the agent must not present it as the full calendar. This is meaningful behavioral guidance.

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 is three dense sentences with no filler. The primary purpose is front-loaded, the cap/pagination caveat and filter guidance follow, and the alternative tool is named last. 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?

Even though there is no output schema, the description names the key result contents (nights_available, booking-search link, total_count/has_more) and the critical pagination caveat. Combined with the fully described schema and read-only annotations, an agent has enough information to call the tool correctly and interpret the 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?

The input schema already describes all 8 parameters with 100% coverage, so the baseline is 3. The description mostly restates filtering options and references an output field (nights_available) rather than adding new parameter semantics, but it does not need to compensate for missing schema documentation.

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

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

The description states exactly what the tool provides: real upcoming charter departure dates from Tirana for a destination, including trip lengths actually on sale and a booking-search link. It also distinguishes itself from charter_flexible_dates by explicitly naming that alternative for cheapest-date queries.

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 concrete filter guidance (date_from/date_to or month) and an explicit routing rule: use charter_flexible_dates when the user wants the cheapest date. This clearly tells an agent when to choose this tool over the most relevant sibling.

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 mark it read-only/idempotent/non-destructive, so the description adds non-obvious behavioral detail: no_cached_data is not 'no offers', prices are package totals in EUR not per person, party_match=false means the 2-adult reference, and a price belongs only to its own date. These caveats are far beyond what the annotations 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?

Every sentence carries a distinct warning or clarification; there is no filler. The core purpose is front-loaded and the caveats are ordered logically from cache semantics to pricing units to date ownership.

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

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

With no output schema, the description carries the full burden of explaining response semantics, and it covers the critical fields (availability_status, cached_at/age_minutes, party_match, best_value_date) and their pitfalls. An agent can interpret rows safely without further 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 the parameters are already documented; the description adds relevant context about party-level totals and window length but does not add per-parameter syntax beyond the schema. The baseline of 3 is appropriate because the schema carries the parameter burden.

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

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

States a precise operation: return the lowest cached package total for each departure date in a window, plus best_value_date, for a destination and party. The 'CACHED' and 'window' qualifiers distinguish it from siblings like charter_cheapest and charter_dates without needing their schemas.

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

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

'For flexible travellers' gives a clear when-to-use signal, and the explanation that this is cached rather than live tells the agent when it is not appropriate. It stops short of naming a sibling as the live alternative, but the context is strong enough for routing.

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 indicate read-only and idempotent behavior, but the description adds major behavioral nuance: the data is cached, not live; party_match semantics; exact_date_matches vs other_cached_offers; that prices are package totals in EUR, not per-person; and that a price belongs only to its own date. This far exceeds what the annotations reveal and prevents common misinterpretations.

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 is dense and packed with necessary caveats, all of which earn their place. It could be better organized with bullet points, and there is minor repetition of the not-live/cached concept, but it remains well-structured with front-loaded scope and clear separators between key ideas.

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 supplies the crucial output semantics: exact_date_matches, other_cached_offers, availability_status=reference_other_date, party_match flags, cached_at/age_minutes, and the hotel_page fallback. It also covers edge cases (no cached date, wrong party, wrong date) so an agent can correctly interpret and present results in every scenario.

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 value by instructing the agent to always pass the date and party given by the user, explaining that the exact party's cache is read first, and clarifying the 2-adult reference fallback. This behavioral mapping goes beyond the schema's per-field descriptions, though it is somewhat redundant with them.

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 scope: it returns cached prices for ONE named hotel, and gives an example hotel name. It explicitly distinguishes itself from the siblings charter_offers (filters), compare_hotels (2-6 named hotels), and hotel_details (amenities), so an agent can immediately differentiate 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?

The description gives explicit when-to-use guidance: call it when the user names one specific hotel, and do NOT call it repeatedly for browsing — instead use charter_offers or compare_hotels. It also prescribes a specific fallback behavior when nothing is cached: say so and provide hotel_page, which leaves no ambiguity.

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?

The description is rich with behavioral caveats beyond the read-only annotations: prices are cached, not live; prices are package totals in EUR, not per person; party_match=false means the price is a 2-adult reference; and a price belongs only to its own date. It also explains excluded_unknown_features. This is essential for the agent not to misrepresent results.

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 is long but every sentence earns its place: it front-loads the core purpose, then adds a concrete example, then the output structure, then essential caveats about cache, pricing, and date-bounding. There is no filler or restating of 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 takes on the burden of explaining what the tool returns: price range, three quality tiers, a shortlist, excluded_unknown_features, and party_match semantics. It covers the necessary context for an agent to call and interpret results correctly, even for a complex 19-parameter 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 input schema already documents all 19 parameters well. The description adds some context about party-exact cache usage and not presenting prices across dates, but these are largely behavioral rather than new parameter-level semantics. 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+resource: it filters the whole cached charter inventory in one call by multiple criteria. It clearly differentiates itself from siblings by positioning itself as the discovery tool with an illustrative natural-language query, and by mentioning the one-call nature.

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

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

The description gives clear context on when to use the tool: for open-ended 'what do you suggest' queries, and instructs to pass the date and real party when available. It does not explicitly mention alternatives or exclusions, 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 mark the tool as read-only and idempotent, and the description adds substantial behavioral context: prices are cached, not live; not_found does not mean unavailable; party_match=false means the price is the 2-adult reference; and prices are package totals, not per-person. No contradiction with annotations exists.

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 is long but every sentence earns its place: it front-loads the core comparison purpose and then layers essential caveats about cache behavior, not_found handling, package totals, party matching, and date scoping. The structure supports both initial selection and correct result interpretation.

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 compensates by listing key output elements: cached price, party_match, cached_at, stars, zone, board, room, features, and booking link. It also covers edge behaviors like not_found and the date-price association, making the tool safe to invoke and interpret 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?

Although the input schema covers all parameters, the description adds critical meaning beyond the schema: it defines the 'party' concept, explains party_match=false, clarifies that prices are not per-person, and insists that a price belongs only to its own date. This directly improves correct interpretation of date, adults, and children_ages.

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 'Side-by-side comparison of 2-6 named hotels for a date and party' and then enumerates the exact output fields, so the tool's purpose is immediate and specific. It also explicitly distinguishes itself from 'several charter_hotel calls', which separates it from its siblings.

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

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

The description explicitly names charter_hotel as the alternative and frames compare_hotels as the one-call replacement for comparing multiple hotels. It also gives clear cautions about cached vs. live data, not_found semantics, and the instruction to never present one date's price as another date's price.

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 provide readOnlyHint, idempotentHint, and destructiveHint, and the description adds valuable behavior beyond that: it is cached/validated data with no live call, the price is INDICATIVE and must never be presented as a bookable quote, and the exact price is computed live on the package page. 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?

The description is compact and front-loaded with scope ('NON-charter holiday packages from Tirana'), then moves through destinations, dates, pricing caveat, charter routing, and cached nature. The destination list is slightly long but serves disambiguation. Every sentence contributes, so only minor verbosity keeps it from 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?

For a read-only, cached listing tool with no output schema, the description fully conveys what will be returned: on-sale destinations, validated departure dates, indicative price, and booking link. It also communicates the critical price caveat and the no-live-call behavior. Combined with annotations and full schema coverage, an agent has what it needs to invoke and interpret 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?

The input-schema covers all parameters with descriptions (100% coverage), including the YYYY-MM-DD pattern for date_to. The description reinforces 'departure dates' and 'validated upcoming departures,' but it does not add new parameter syntax or semantics beyond what the schema already provides. This was the correct baseline.

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 clearly states the verb+resource: it lists NON-charter holiday packages from Tirana (flight+hotel or bus+hotel), including on-sale destinations, validated departure dates, indicative price, and booking link. The word NON-charter and the explicit charter_* mention distinguish it from its main sibling group, making the purpose unambiguous.

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

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

The description explicitly redirects: 'For Turkey/Egypt beach charters (Antalya, Bodrum…) use the charter_* tools instead.' It also frames the scope as NON-charter packages, and the cached/no-live-call statement sets expectations for when it is appropriate. The primary alternative tool group is named directly, so an agent can route correctly.

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. The description adds meaningful behavioral context beyond that: it is a cache/DB read with no live call, features are tri-state with null meaning unknown, distances are not available and must not be estimated, and features must not be claimed when null/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?

The description is compact but information-dense, starting with the core facts, then the feature semantics, then the key limitations and the alternative tool. Every sentence earns its place, and the most important constraints 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?

There is no output schema, but the description enumerates the return content (stars, zone, categories, features, facility list, description) and clarifies edge-case semantics like null features and unavailable distances. For a simple two-parameter read tool, this is complete enough for correct invocation.

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 both the hotel and destination parameters. The description does not add parameter-level meaning beyond confirming the single-hotel scope, so the 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 uses a specific verb and resource: it holds static facts about one charter hotel, enumerating exactly what facts (stars, zone, categories, features, facility list, description). It also differentiates itself from siblings by explicitly stating 'No prices here (use charter_hotel)'.

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

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

The description clearly states the scope is 'ONE charter hotel' and explicitly routes price lookups to charter_hotel. It doesn't contrast with compare_hotels or other siblings, but the single-hotel facts-only framing gives an agent clear enough context for when 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 readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds useful behavioral context beyond annotations: the digest is cached and rebuilt hourly, and it is overview-only rather than a detailed per-hotel source.

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 is a single dense sentence that front-loads the main purpose, then adds source, caching behavior, and routing guidance. Every clause earns its place; there is no filler or repetition of schema/annotation 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 zero-parameter, read-only, idempotent digest tool, the description is complete: it states content scope, freshness, source URL, and when not to use it. The return structure is not detailed, but the URL reference and 'machine-readable' characterization provide sufficient guidance for an agent to invoke and interpret the 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?

The tool has zero parameters and the schema fully covers that, so there is nothing for the description to add. The baseline of 4 applies because no parameter documentation burden exists.

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 purpose: returning today's full machine-readable price digest covering charter packages, tours, guides, and FAQ. It also explicitly distinguishes this overview tool from the charter_* tools, so an agent can separate it from siblings without opening schemas.

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

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

The description gives clear routing guidance: use this for an overall digest, and use charter_* tools for any specific hotel/date/party query. This explicit when-not-to-use instruction plus named alternatives is exactly what an agent needs.

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 are already strong (readOnly, idempotent, non-destructive), and the description adds significant behavioral detail: cache behavior, 'cached_for_date' vs 'list_from' pricing, the 'nearest departure' fallback, the per-date price rule, and the complete departure-date calendar. This gives an agent accurate expectations beyond what annotations 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?

The description is dense but every sentence earns its place: scope, matching, pricing semantics, date-calendar authority, availability caveat, and cache/no-live-call nature. It is front-loaded with the core purpose and progressively layers the caveats an agent needs to avoid errors.

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

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

For a read-only tool with no output schema, the description covers all critical operational details: what data is returned, how to identify the tour, how pricing behaves for specific dates, what not to do with dates, and where live pricing/availability live outside this tool. It is sufficient for correct invocation and response reasoning.

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%, but the description enriches several parameters: 'tour' matching semantics with examples, exact 'tour_id' from tours_list, and how 'date' plus party affects pricing ('cached_for_date' exact total vs 'list_from' nearest departure). It also explains a critical constraint: every departure date has its own price, adding real semantic value 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?

The description names a clear resource ('ONE organized group tour') and enumerates the exact content returned: departure-date calendar, day-by-day program, duration, transport, price. It also distinguishes itself from sibling categories by emphasizing 'organized group tour' and 'Cache/DB read, no live call', so an agent can tell it apart from list-like or charter 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?

The description gives practical invocation guidance: match by 'tour' fragment or exact 'tour_id' from tours_list, pass 'date' and party when available, and use 'tour_page' for live pricing of any date. It also states exclusions, such as 'Seats/availability are confirmed by staff', which prevents misuse. It does not explicitly enumerate every sibling alternative, but the context and exclusions are clear enough.

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 indicate read-only, idempotent, non-destructive behavior. The description adds valuable context beyond annotations by disclosing that the catalogue is cached, that IDs are stable, and that prices are per person rather than per package. This helps the agent set expectations about data freshness and price interpretation.

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 is dense but every clause carries useful information: scope, guide language, cache status, field list, pricing rule, and sibling routing. The most important identifying details are front-loaded, and the alternative tool is mentioned at the end without bloat.

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, read-only list tool with one optional parameter and no output schema, the description is complete. It enumerates the returned fields, clarifies sorting via the title, notes the cache behavior, and directs the agent to tour_details for deeper information. 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?

The schema covers the single optional limit parameter fully with a description including default and constraints. The tool description does not need to repeat this, so the baseline of 3 is appropriate. No additional parameter meaning is required.

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 clearly states the tool lists escorted group tours from Tirana with Albanian-speaking guides and specifies the exact fields returned. It further distinguishes itself from charter packages by noting per-person pricing, and points to tour_details for a single tour's full details. This leaves no ambiguity about what the tool does or how it differs from siblings.

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

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

The description explicitly tells the agent to use tour_details when a single tour's full calendar, program, or date-specific price is needed. It also contrasts tours_list with charter packages, clarifying that price semantics differ. This is strong routing guidance that helps the agent choose the correct tool.

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