Escape the Week

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

With no annotations, the description does the heavy lifting by disclosing the return structure (ordered steps, reserve_days, book_by date, fallback, alternatives array) and the booking semantics around alternatives. It does not explicitly state that the tool itself performs no bookings or describe auth/rate behavior, but the 'links and checklist' framing plus the ordering rules give strong behavioral context.

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 purpose and ordering rule, then alternatives, then sibling routing. It is dense but every clause carries information; the alternatives sentence is slightly long but earns its place by preventing double-booking.

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 explain return content — it does so in detail (step ordering, reserve_days, book_by, fallback, alternatives). With all seven params schema-documented, nothing an agent needs to call this correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so every parameter (city slug, friday, persona, tier, travellers, origin, lang) is already documented. The description adds no parameter-level guidance beyond what the schema provides, so the baseline of 3 applies.

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

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

States a specific verb+resource: returns booking links and a checklist for a weekend, ordered by scarcity. It also names the sibling it is not (booking_manifest) and the exact ordering/contents (reserve_days, book_by, fallback, alternatives). An agent can distinguish it from booking_manifest 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 says to book in list order, to compare alternatives and book one not both, and routes the agent to booking_manifest when an executable plan is needed. The when-to-use-this vs when-to-use-alternative condition is stated, not inferred.

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 no annotations provided, the description carries the full burden and does so thoroughly: it discloses affiliate-tracked links, that Escape the Week never takes payment, that a human must approve every payment on the partner site, that prices are estimates not quotes, and that alternatives should be compared but never booked together.

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 front-loaded with purpose and is dense rather than padded; most details earn their place because there is no output schema. However, it is a single long paragraph that could be more scannable, which slightly reduces structure quality.

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 the lack of output schema and annotations, the description is complete enough: it explains the return structure, ordering, affiliate disclosure, payment approval flow, cost estimate semantics, and booking alternatives. An agent has what it needs to call and interpret the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the input schema already documents all eight parameters including required fields and enums. The description adds context about party-size pricing and weekend dates in the output, but does not add meaningfully to the parameter definitions beyond what the schema provides.

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 that this tool returns everything needed to book one weekend, in booking order, with bookable items and associated metadata. It is specific about the resource and output, but it does not explicitly differentiate itself from siblings like booking_checklist or estimate_itinerary.

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

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

Usage is implied by phrases like 'Everything an agent needs to book one weekend' and 'in the order to book it', but the description never states when to use this tool versus alternatives or any exclusions. An agent can infer the context, but explicit routing guidance is absent.

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 no annotations, the description carries the load and does well: it discloses integer-cent units, that results are estimates with no fare lookups, that caching lasts one minute per parameter set, that friday is echoed rather than priced, and that each estimate carries party_shapes. No permission or auth notes, but the behavioral picture is unusually rich.

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

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

A single dense sentence that front-loads the output shape and then adds qualifiers. Every clause carries information (units, caching, no fare lookups), though the run-on construction is harder to parse than a short structured list.

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 and no annotations, so the description must explain returns, and it largely does: totals, per-person, per-city/persona flights, cheapest persona, party_shapes, cents. Caching is covered. Minor gaps remain around error behavior or result size, but nothing essential is missing 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 coverage is 100%, so each parameter is already documented in the schema. The description restates them (tier, month or year average, group, optional origin) but adds little new syntax or edge-case meaning beyond what the enum and property descriptions already say.

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

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

States a specific action and scope: pricing every published itinerary at once, with the returned breakdown (total, per person, flights per city/persona, cheapest persona per city). The word 'Every' implicitly contrasts it with the single-itinerary sibling estimate_itinerary, though it never names that 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?

Usage is implied by the parameter context (bulk estimates for a tier/month/group/origin) and by the note 'Estimates only, no fare lookups', which steers the agent away from get_fare. But it never explicitly says when to choose this over estimate_itinerary or get_fare.

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?

No annotations exist, so the description carries the full burden. It does add valuable behavior beyond the schema: the result is an integer number of cents, and prices cover the whole group. It does not state that this is a non-mutating lookup, that omitting origin drops the flight line, or how invalid inputs (non-Friday date, unknown slug) are handled.

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

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

A single dense sentence that front-loads the output unit and then enumerates what is priced. No filler, though the colon-and-comma list runs long enough that a second sentence splitting inputs from outputs would read better.

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 an 8-parameter computation tool with no output schema and no annotations, the description covers the output unit and cost categories but leaves gaps: it never says what the returned object looks like beyond a number in cents, whether the flight cost is conditional, or what happens on invalid input. Adequate, not 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 description coverage is 100% — every one of the 8 parameters has a description, enums, and defaults — so the baseline is 3. The description merely restates the axes (tier, month/year mean, group) the schema already documents in richer detail; the '$' unit and 'integer cents' phrasing is the only real addition.

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: a budget estimate in integer cents for a published itinerary, enumerating the cost lines (activities, lodging, transport, flights) it aggregates. This distinguishes it from get_fare and estimate_all in substance, but never names those siblings, so the agent must infer the boundary.

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 phrase 'for a published itinerary' implies usage context, and 'for a tier, a month or the year average, and a group' hints at the parameter combinations that drive the result. However, there is no explicit when-to-use vs estimate_all or get_fare, and no statement of prerequisites (that city/persona slugs must come from list_cities/list_personas) or exclusions (e.g., flights require an origin).

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 no annotations, the description carries the burden, and 'Fetch' plus the field listing establishes a read-only detail lookup. It discloses the returned data shape, which matters since there is no output schema. It does not mention what happens for an unknown slug, null fields, or caching, so a 4 rather than 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?

One sentence, front-loaded with the verb and the identifying parameter, then the return payload. No filler or redundancy.

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?

The tool is low-complexity with only two parameters, and since no output schema exists, the description usefully enumerates the returned fields including the twelve monthly season factors. Combined with schema coverage of both parameters, 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 coverage is 100%, so the baseline is 3, but the description adds real meaning by tying the required 'slug' parameter to its source (list_cities), which the schema does not. It says nothing about the optional 'lang' parameter, but the schema documents that fully.

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 ('Fetch one city by its slug') and immediately enumerates the returned attributes, so the agent knows exactly what it gets. The parenthetical '(from list_cities)' explicitly separates it from the list_cities sibling, which returns many cities.

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 '(from list_cities)' note establishes the workflow: use list_cities to discover slugs, then call this for detail on a single city. It never states an explicit exclusion or error condition (e.g., behavior for an unknown slug), so it falls short of a full when/when-not statement.

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 no annotations, the description carries the full burden, and it does disclose real traits: data is cached from Travelpayouts, is per person, is return, and is constrained to Friday-to-Monday weekends. It does not say how stale the cache may be, what currency/format is returned, or what an empty result means — meaningful gaps for a data-lookup tool.

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

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

A single dense sentence with zero filler; the core resource ('cheapest known return fare') is front-loaded and the constraints follow. Nothing to trim.

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 are no annotations and no output schema, so the description is the only source of behavioral detail, and it omits return-value characteristics (currency, price field, empty-result behavior) that an agent cannot learn elsewhere. The weekend and caching constraints are covered, but the result side is not.

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 all three parameters are already documented in the schema. The description adds the useful framing that 'friday' anchors a Friday-to-Monday weekend (implying the Monday return leg), but adds no format, validation, or code-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 resource and qualifier: the cheapest *known* (cached) return fare per person for a Friday-to-Monday weekend between two IATA codes. The 'known/cached' framing implicitly separates it from the estimate_* siblings, but no sibling is named explicitly, so the differentiation is inferred rather than stated.

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 wording 'cheapest known ... (cached from Travelpayouts)' implies this is a lookup of an observed fare rather than a computed estimate, which points an agent away from estimate_all/estimate_itinerary. However, there is no explicit when-to-use/when-not guidance and no mention of what to do if no cached fare exists.

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?

No annotations are provided, so the description carries the burden. It does disclose that the response includes the persona's audience, which is useful, but it says nothing about error behavior for a missing slug, localization fallback behavior for the lang parameter, or any auth/rate considerations.

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

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

A single tight sentence, front-loaded with the verb and resource, that also carries the sibling reference and return-content hint. Nothing is wasted.

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

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

For a simple two-parameter read tool with no output schema and no annotations, the description covers what it does, where the key input comes from, and roughly what comes back. Missing only edge-case behavior such as an invalid slug or untranslated lang fallback.

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 in the schema, setting the baseline at 3. The description adds a small amount by indicating the slug originates from list_personas, but says nothing about the lang parameter beyond what the schema already states.

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

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

Names a specific verb and resource (fetch one persona) plus scope (by its slug) and states what comes back (its audience). It also explicitly distinguishes itself from the list_personas sibling, so an agent can pick the right tool without opening a schema.

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

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

The parenthetical '(from list_personas)' routes the agent: list first, then fetch by slug. That's clear contextual guidance, but there's no explicit when-not or statement about what to do if the slug is unknown.

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?

No annotations are provided, so the description carries the full burden. It thoroughly describes the return data model (fields, semantics, cost_cents, reserve_days, fallback), which is valuable behavioral context. However, it does not explicitly state that this is a read-only operation with no side effects, nor does it mention authentication or error 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?

The description is a single, front-loaded sentence that efficiently lists the return fields. It could be made more readable with bullet points, but it does not waste 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?

Given the absence of an output schema, the description provides a detailed account of the returned itinerary structure, including days, steps, times, kinds, notes, costs, reserve_days, and venue details. It also clarifies that Day 0 is Friday. It could mention error cases or ordering, but it is largely complete for an agent to understand 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?

Schema coverage is 100%, so the schema already documents all three parameters (city, persona, lang). The description adds no additional meaning beyond mentioning (city, persona) in context; the lang parameter is not mentioned at all. Baseline 3.

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 a specific resource (published itinerary) and scope (one city, persona), and details its contents. It implicitly distinguishes from list_published_itineraries by specifying 'one', but does not explicitly name alternatives.

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?

No explicit guidance on when to use this tool versus alternatives such as list_published_itineraries or estimate_itinerary. Usage is only implied by the description of the return.

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 no annotations provided, the description carries the behavioral burden and does disclose key traits: the return is iCalendar text, there is one event per step, times are floating local times with no time zone, and Friday maps to day 0. It does not mention permissions or error behavior, but the core output semantics are unusually well specified for an unannotated tool.

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 two tight sentences with no filler. The output format and time-zone behavior are front-loaded, and the friday format note follows naturally.

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 four-parameter tool with no output schema and no annotations, the description gives enough detail about the returned iCalendar format and time semantics for an agent to call it correctly. It could mention whether a published itinerary must already exist, but the essential context is present.

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 schema already documents all four parameters. The description mainly reiterates that friday is a YYYY-MM-DD date and adds the Friday=day 0 semantic, which is useful but marginal beyond the schema 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 tool returns a published itinerary as iCalendar text for one weekend, which is a specific resource and output format. It does not explicitly distinguish itself from sibling tools such as get_published_itinerary, but the iCalendar framing is distinctive enough for an agent to understand the purpose.

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 phrase 'for one weekend' and the Friday=day 0 convention imply usage context, but the description gives no explicit when-to-use guidance or alternatives. It does not say when to choose this over get_published_itinerary or what prerequisites apply.

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 no annotations, the description carries the burden and does disclose the key data condition (only cities with published weekends), the field set returned, and that results are 'Paged.' It omits any note on result ordering or that the default status filter is 'published', though the schema covers the latter.

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-load the core purpose, then the discovery value, then paging. Every clause earns its place, though 'Paged.' as a fragment and the dense season-factor gloss slightly compress readability.

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, yet the description enumerates return fields and explains the season-factor scale, which is exactly what an agent cannot get from structured data. Paging is flagged; only result ordering and the interaction of the status filter with 'published weekends' are left unstated.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so lang, limit, offset and status are already fully documented; the description adds nothing about them. Its one semantic addition ('1.0 = shoulder season; higher is dearer') explains a returned value, not a parameter, so baseline 3 applies.

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

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

Specific verb ('List') plus a precisely scoped resource ('cities that have published weekends') and an enumeration of the returned fields (slug, IATA, currency, twelve season factors). It is clearly separable from the sibling get_city, which fetches one city rather than listing discoverable slugs.

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?

'Start here to discover city slugs for every other tool' gives an explicit entry-point role, implying get_city and the itinerary/fare tools are the follow-ups. It stops short of naming any tool to avoid or a when-not-to-use condition, so it is clear but not fully 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?

With no annotations, the description carries the full behavior burden. It discloses that the result includes slug, name, and IATA code and that the response is unpaged, but it does not explicitly state read-only behavior, ordering, or permission assumptions.

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, front-loaded sentence plus a short pagination note. Every element adds useful information, and there is no 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 zero-parameter list tool with no output schema and no annotations, the description is nearly complete: it names the returned fields, says the result is unpaged, and explains how the slug is consumed. Minor gaps such as ordering are not addressed.

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 input parameters, so the baseline is 4. The description focuses on output fields rather than inputs, which is appropriate here.

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: it lists origins a trip can start from. It clearly defines the returned fields and their downstream use, though it does not explicitly distinguish itself from sibling list tools such as list_cities.

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 tells the agent to pass the returned slug as origin to the pricing and booking tools, which gives clear usage context. It does not state exclusions or name alternative tools for cases where this one should not be used.

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 no annotations, the description must carry the behavioral burden. 'List' plus 'Paged.' conveys read-only and paginated behavior, but nothing is said about permissions, what 'published' vs 'archived' rows mean, or what happens when a requested translation is missing.

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 core definition is front-loaded in one dense sentence, followed by the two most decision-relevant facts (slug usage, paging) briefly. No filler, though the field enumeration mid-sentence makes it slightly dense to parse.

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, and the description compensates by enumerating the returned fields (slug, audience, party_shapes, children, pace) with allowed values. Combined with a fully documented input schema, an agent has enough to call it correctly; only the list/get relationship remains unstated.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so lang, limit, offset and status are fully documented in the schema; the description adds only the word 'Paged.' Baseline 3 applies since the schema does the heavy lifting and the description adds no extra 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?

States a specific verb and resource ('List the personas') and defines the domain concept in parentheses with examples (foodie, collector), plus enumerates the fields returned. It does not explicitly distinguish itself from the sibling get_persona, which keeps it 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?

It gives downstream usage context ('Persona slugs are used with city slugs to name an itinerary'), which implies when a caller needs this data before composing an itinerary. However, it never states when to use this versus get_persona or how to handle the paging/status filters, so usage is implied rather than directed.

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?

No annotations exist, so the description carries the full burden. It discloses completeness ('every') and the record shape (tier, dimension, factor), which is genuinely useful, but it never states read-only-ness, ordering, or approximate result size for the six dimensions times all tiers.

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

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

A single sentence, front-loaded with the action, followed by the record shape and the enumerated dimensions. Nothing is wasted and no re-reading is required.

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 zero parameters and no output schema, the description supplies the essential return semantics itself by naming the (tier, dimension) key and the factor value. It stops short of tying the tool to its siblings or to the estimate_* tools that presumably consume these factors.

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 takes zero parameters, so the baseline is 4. The description confirms there is nothing to filter on, avoiding any expectation that a tier or dimension argument could be supplied.

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

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

Specific verb 'List' plus resource 'price multiplier', and it defines what a multiplier is (the factor applied to the modest-tier price) for each (tier, dimension) pair. This implicitly separates it from list_pricing_tiers, though no sibling is named.

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 phrase 'List every price multiplier' implies an unfiltered full enumeration, which is implicit guidance about scope. However, there is no explicit when-to-use, no mention of a when-not-to-use case, and no comparison against the closely related list_pricing_tiers 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?

With no annotations, the description carries the full behavioral burden. It usefully discloses the exact tier values and that they are returned in display order, but it does not clarify that this is a read-only, zero-input operation or describe the response shape beyond the enumerated names.

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 short and front-loads the useful enumeration of tiers. The second sentence does not earn its place because it references a parameter that does not exist and adds confusion rather than clarity.

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 zero-parameter list tool, the exact tier names and ordering are helpful and largely sufficient. Still, the description lacks usage context relative to list_pricing_multipliers and contains a misleading parameter instruction, so it is not fully 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?

The input schema has zero parameters, so there is no real parameter semantics to clarify. However, the description says 'Pass the name as tier,' which introduces a nonexistent parameter-like instruction and could mislead an agent into trying to pass an argument.

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 a specific verb and resource: listing budget tiers, and it enumerates the exact tiers in display order. It is distinguishable from list_pricing_multipliers by resource, though it does not explicitly name that sibling as an alternative.

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?

There is no guidance on when to use this tool versus list_pricing_multipliers or other related tools. The phrase 'Pass the name as tier' does not provide a clear usage condition and is confusing given the tool has no parameters.

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 no annotations the description must carry the load, and it does disclose the return shape in detail, including the notable currency rule (EUR unless overridden by the city) and integer-cents representation. It omits read-only/public nature, pagination, and volume expectations, which for an index tool is a real but bounded 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?

Two sentences, front-loaded with the resource identity, then usage. The first sentence is a long enumeration but every item is substantive; the parenthetical currency note 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?

For a one-optional-param listing tool with no output schema, the description covers what is returned and the currency convention, which is the main correctness trap. Missing pagination/ordering detail keeps it from 5.

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 single `lang` parameter has 100% schema description coverage, so the baseline is 3. The description's mention of 'names' hints at translation but never connects it to the lang tag, adding marginal 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?

It defines the resource precisely ('the public index: every published itinerary') and enumerates exactly what each entry carries (slugs, title, summary, step counts, cost sum, currency). This clearly separates it from the single-item sibling get_published_itinerary.

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 discover which (city, persona) weekends exist' gives an explicit selection rule for this tool over the getter siblings. It never names an alternative or an exclusion, 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?

With no annotations, the description carries the full burden and does real work: it discloses that submissions are public, that they are never auto-published but go to human editorial review, and that there is per-sender rate limiting. Not disclosed are auth requirements, what the call returns, or whether duplicate tips are accepted — gaps, but the moderation and rate-limit traits are exactly the kind of behavioral context an agent would otherwise have to guess.

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

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

Three short sentences, front-loaded with the verb and the four tip categories. Every clause carries information: what to send, when it applies, and the two operational facts (public, editor-reviewed, rate limited). 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?

For a 7-parameter mutation with no annotations and no output schema, the description covers the lifecycle an agent most needs (public, queued for review, rate limited) and the schema fully documents all parameters. The notable remaining gap is that the agent cannot tell what a successful call yields — a tip id, a confirmation, or nothing — nor whether authentication is required.

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 earns more by glossing the enum domain in prose ('a place to add' → add, 'a closed place' → closed, 'somewhere nearly impossible to book' → hard_to_book, 'a wrong fact' → wrong_info), making the kind choice clear without opening the schema. It adds nothing about city/persona/step_ref/locale, which the schema already documents.

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 (send) and resource (a tip about a city) and then enumerates the four substantive tip kinds, which map directly onto the 'kind' enum values. An agent can distinguish this write/submission tool from every sibling, all of which are read-only lookups (get_city, list_*, estimate_*).

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?

"a place to add, a closed place, somewhere nearly impossible to book, or a wrong fact" gives concrete situations that select this tool, and "never published; an editor reviews it first" frames it as a submission rather than a data edit. It stops short of explicit exclusions or prerequisites (e.g. don't submit what already exists in get_city output), and no sibling overlaps so no alternative needs naming.

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