Ourway – Camino de Santiago

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the safety profile is covered. The description adds valuable behavioral context: it explains that the tool returns proposals with total changes, that accepted ones must be applied via swap_camino_hotel, and that proposals are chained to the new offer. This goes beyond the annotations but could still be more specific about limits (e.g., max proposals, pagination), hence 4.

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: the first sentence states the core function and goals. It then uses semicolons and short clauses to cover usage, fallback, and chaining. It is slightly long but every sentence carries operational information; the Spanish hint is a minor extra. 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 proposal-generation tool with an output schema, this description is exceptionally complete. It covers the trigger conditions, the goals, the optional parameter, the return contents (change in total and total if all applied), the subsequent action (apply via swap_camino_hotel), and the fallback. An agent can invoke it correctly without further research.

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 0%, so the description must compensate. It does: it lists the allowed values for `objetivo` (bajar_precio | subir_categoria | mas_centrico | con_desayuno) and explains `noche_num` as an optional limiter to one night. The third parameter, `oferta_paquete_firmada`, is not explained explicitly but its name is self-descriptive ('signed package offer'). Overall it adds meaning beyond the bare 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 clearly states a specific verb-resource pair: 'Propose per-night hotel swaps on a quoted Camino de Santiago package.' It enumerates the four distinct goals (bajar_precio, subir_categoria, mas_centrico, con_desayuno) and explicitly differentiates from siblings like swap_camino_hotel (which applies changes) and quote_camino_package (which re-quotes). The purpose is unmistakable.

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 states when to use the tool ('when the client asks to LOWER THE PRICE, UPGRADE, sleep MORE CENTRAL or ADD BREAKFAST') and gives a direct exclusion ('do not re-quote'). It also routes to the sibling swap_camino_hotel for applying accepted proposals and suggests re-quoting as a fallback. This fully covers when/where/when-not.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavior beyond that: it is “cheap and instant (no availability check)” and returns answers from a specialist team. 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 purpose is front-loaded and the content is information-dense, which helps an agent match queries. However, the entire English block is effectively duplicated in Spanish, roughly doubling the length, and it ends with a stray fragment “(es: info_camino)”. For an agent reader, the bilingual repetition is not essential.

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 only 2 parameters, an output schema present, and safety annotations covering behavior, the description supplies what is missing: parameter meanings, usage scope, and the non-booking use case. Nothing an agent needs to invoke it correctly is omitted, though the redundancy makes it longer than necessary.

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 0%, so the description must carry the full burden, and it does: it documents `question` as free text in any language and `idioma` as es | en with auto-detection when omitted. This fully compensates for the empty schema and mirrors the parameter names exactly.

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 purpose: practical, up-to-date Camino answers from a specialist team, explicitly framed as an info/FAQ Q&A tool for ANY Camino question even without booking. This cleanly separates it from the 11 sibling tools, which are booking, planning, and route-query tools. The exhaustive topic list further pins down the exact resource it addresses.

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

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

Explicitly says to use it for “ANY Camino question even when the user is not booking” and repeats this in Spanish (“aunque el usuario no quiera reservar”), which is clear guidance on when to reach for it. It gives the language-parameter behavior (auto-detected if omitted), though it does not name specific sibling alternatives to route away from.

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, destructiveHint=false, and idempotentHint=true. The description adds meaningful behavioral details: no unit prices are provided, preseleccionado marks defaults based on nationality, IDs are not shown (from the Spanish 'sin mostrar IDs'), and these are the only allowed extras. This goes well beyond the annotations without contradicting them.

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 information-packed, covering the core purpose, content types, pricing behavior, preselection logic, and exclusivity. It includes both English and Spanish text, but this is not redundant given the tool's context. Every sentence adds value, and the key constraint (only extras allowed) is prominent, making it appropriately sized without excessive verbosity.

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

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

With an output schema present, the description need not enumerate return fields. It fully covers the catalog's scope, the absence of unit prices and IDs, the preselection semantics tied to nationality, and the exclusivity of these extras. An agent has sufficient information to invoke the tool correctly and interpret its output in context.

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's 'nacionalidad' parameter has no description (0% coverage). The description indirectly explains its influence by stating 'preseleccionado marks the defaults (credential + insurance by nationality)', implying the parameter filters which extras are preselected. However, it doesn't explicitly state that the parameter is optional or how it affects the result set, leaving room for interpretation.

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 this is the official catalog of pilgrim extras for the Camino de Santiago, enumerates the categories (credential, insurance, luggage transfer, etc.), and explicitly notes it is the ONLY extras that may be offered. This fully distinguishes its purpose from any sibling tool such as list_camino_routes or quote_camino_package.

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 implies usage by stating that pricing is folded into quote_camino_package and that no unit prices are shown here, which hints that pricing-related queries belong elsewhere. However, it does not explicitly state when to use this catalog versus alternatives, nor does it provide when-not-to-use rules. The 'only extras' clause is helpful but lacks direct 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 already declare readOnlyHint and idempotentHint, so safety is covered. The description adds useful behavioral context: it returns up to 3 alternatives, does not provide per-night prices ('nunca precios por noche'), and relies on already-queried availability. This goes beyond annotations without contradicting them.

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 content is concise and front-loaded with the purpose and usage. However, the English and Spanish versions duplicate the same information, adding length without new value. Still, it remains readable and not bloated.

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 description covers purpose, usage, and some behavior, and the output schema explains return structure. But the lack of parameter documentation (given 0% schema coverage) is a significant gap that forces the agent to guess about inputs. For a simple read-only lookup, this is moderately complete but not fully self-sufficient.

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 has 0% description coverage and the description does not explain the two parameters (oferta_paquete_firmada and noche_num). It mentions 'ONE night' but does not map it to noche_num, nor does it clarify what the package identifier should be. With no schema descriptions, the description fails to compensate, leaving the agent to infer 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?

The description clearly states the tool returns up to 3 alternative hotels for a specific night of a quoted Camino package, listing the fields (variation, room, meal plan, distance). It explicitly differentiates from re-quoting the whole trip and points to the swap tool for applying a choice, so it is easy to distinguish 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?

It provides explicit usage context: 'Use it when the client wants a different hotel in a town — do NOT re-quote the whole trip' and then instructs to apply with swap_camino_hotel. This clearly indicates when to use it and what not to do, making the intended workflow unambiguous.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows this is a safe read operation. The description adds valuable context by listing the possible statuses (active/confirmed/expired) and mentioning the link and deadline in the response, which the agent would not know otherwise. It does not describe error handling or edge cases, but given the annotations, this is sufficient.

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 concise sentences, front-loading the core purpose and result, followed by a clear usage trigger. The bilingual addition is a minor redundancy but not wasteful. Every sentence earns its place, and there is no fluff 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 that an output schema exists, the description needn't explain return values, yet it still mentions the key fields (status, link, deadline). The usage context is clear, and the example code clarifies the expected input. The only gap is the lack of explicit parameter documentation, but this is largely covered by the example and usage trigger. Overall, it is complete enough for an agent to call this tool correctly.

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

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

The input schema has zero description coverage for the only parameter 'codigo' (string). The description compensates somewhat by referencing 'code PET-123' and mentioning 'gives a PET code', implying the parameter is the proposal code. However, it does not explicitly state that the 'codigo' parameter should be the PET-format code, nor does it specify the exact format beyond the example. Given the 0% schema coverage, the description could have been more explicit about the parameter's meaning and acceptable 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 clearly states the tool checks the status of a booking proposal, listing the possible statuses (active/confirmed/expired) and additional data (link, deadline). It provides a concrete example code 'PET-123' and distinguishes itself from sibling tools like create_camino_booking_proposal or adjust_camino_package by focusing on status retrieval. This is a specific verb-resource pairing with clear scope.

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 states when to use the tool: when the customer returns asking about 'my proposal', 'my booking', or provides a PET code. It gives concrete trigger phrases. However, it does not explicitly mention when not to use it or name direct alternatives, but the context clearly separates it from other operations like creation or adjustment.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds trail-order semantics and field meaning, but no additional behavioral caveats such as rate limits, authentication, or output edge cases. This is useful but modest context beyond 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 core definition and usage are front-loaded in the English text, followed by a Spanish translation and a clarifying note about plan_camino_itinerary. Slightly longer than strictly necessary due to bilingual repetition and the trailing `(es: poblaciones_ruta)` tag, but each substantive clause 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-parameter read-only tool with an output schema, the description covers core purpose and usage well. However, it does not tell the agent how to find or validate a `camino_slug` value, e.g., via list_camino_rutes, which is necessary to invoke 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?

The input schema has zero description coverage for `camino_slug`, and the description never explains what a slug is, where it comes from, or how valid values are obtained. The parameter name and title are suggestive, but the description does not compensate for the missing schema guidance.

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: towns along a Camino route in trail order, with id, name, cumulative km, and GPS coordinates. Differentiates from related tooling by noting it provides the ordered town list while plan_camino_itinerary constructs bookable stages.

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 enumerates three use cases: picking the starting town (`poblacion_inicio_id` for plan_camino_itinerary), locating the 100 km Compostela threshold, and validating overnight stops. Also names plan_camino_itinerary as the tool that builds reservable stages, indicating what this tool does not do.

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 carry the read-only, idempotent, non-destructive safety profile. The description adds real behavioral context: this is a conversational intake contract rather than an API mutation, should happen first in planning, and downstream quoting/booking have missing-data pitfalls. It does not spell out the call's return behavior, but the output schema covers that.

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 content is front-loaded with the purpose and field list, followed by actionable call timing and warnings. It is slightly heavy with bilingual duplication and a long parenthetical list, but every element adds information; it could be tightened without losing value.

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

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

For a zero-parameter start-of-flow tool with informative annotations and an output schema, the description covers what to do, when to do it, and what not to do with siblings. No critical decision information 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 input schema has zero parameters, so the description is the only source of semantic meaning. It enumerates the complete conversational field list, including nuanced items like children's ages, budget per person, and luggage transfer, and flags the fields required downstream. This fully compensates for the empty 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 identifies a specific action-resource pair: starting the tailor-made Camino intake form and collecting its fields conversationally before quoting. It enumerates the exact fields, immediately distinguishing it from quote and booking tools, which are named as later steps.

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

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

Explicit timing is given ('Call it at the start of any planning request' and 'BEFORE quoting anything'), and it names two sibling tools with the conditions that must be true before they are allowed (presupuesto for quote_camino_package, contact data for create_camino_booking_proposal). This gives an agent clear routing rules.

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

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

Adds useful context beyond annotations: the returned link is valid 7 days, the customer reviews day-by-day and pays securely, and this is 'única llamada a la acción' (single call to action). Annotations already flag non-read-only and non-idempotent behavior, so the added side-effect details genuinely help.

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 action is front-loaded and the restrictions are clear. However, the bilingual repetition ('Crea la petición en Ourway...') and the trailing '(es: crear_propuesta)' add redundancy without much new value. Trimming to the English content would improve conciseness.

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?

Covers prerequisites, offer source, and the 7-day proposal link, which is enough for tool selection. But with 7 parameters, 5 required, and 0% schema coverage, the description omits guidance for several required arguments, especially camino_slug, idioma_codigo, and formulario. The output schema helps but does not fully replace missing parameter orientation.

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 0%, so the description must compensate. It clarifies that oferta_paquete_firmada means the signed offer from quote_camino_package / swap_camino_hotel and that cliente requires full name, email, phone, and nationality. However, idioma_codigo, camino_slug, poblacion_inicio fields, and formulario are not explained, leaving partial coverage.

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: 'Create the Ourway booking request for a quoted Camino de Santiago package' and returns a concrete artifact, the customer's personal proposal link. It also differentiates from siblings by requiring a signed offer from quote_camino_package / swap_camino_hotel and by being the post-approval booking-proposal step.

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 when to call it: 'ONLY call it after the customer explicitly approves the itinerary and the package total and gives real contact details.' It also states what it does not accept, 'no prices: only the signed offer,' which effectively routes the agent away from quote-level tools.

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 communicate readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds useful behavioral context beyond that: the returned routes are restricted to those Ourway sells, the list includes slug/name/total km, and it is the required starting point for itinerary construction. No contradictions with annotations are present.

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

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

The description is front-loaded with the main purpose and well structured, but it is bilingual and repeats much of the same content in Spanish, which adds length without new information for an English-reading agent. The usage guidance and parameter documentation are valuable, yet the redundancy prevents a higher conciseness 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?

The tool has a rich annotation set, an output schema, and only one optional parameter, so the description does not need to explain return structures in depth. It adequately covers what the tool lists, why to use it, what the parameter values mean, and how it relates to plan_camino_itinerary. An agent has enough context to decide when to call it and what to pass.

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 0% and the schema itself only shows a default without explaining the parameter. The description compensates by documenting `tipo` values with human-readable meanings: a_pie (walking), en_bicicleta (cycling), a_caballo. It does not explicitly state that `tipo` filters the returned routes or that a_pie is the default, but it provides the essential semantic coverage the schema lacks.

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: 'List the Camino de Santiago routes Ourway sells and can book.' It enumerates concrete route examples and expected output fields (slug, name, total km), and distinguishes itself from the sibling plan_camino_itinerary by stating that the bookable itinerary is built there. This makes the tool's role immediately identifiable.

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 says 'Start here for any Camino de Santiago trip question' with sample queries, establishing when to reach for this tool. It also names the alternative for the next step ('El itinerario reservable lo construye plan_camino_itinerary') and clarifies that only the listed routes are reservable, which tells the agent when this tool is the authoritative source.

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 annotations (readOnly, idempotent, non-destructive), the description adds highly relevant behavioral context: the itinerary follows the OFFICIAL stages adapted to pace, an omitted `fecha_inicio` produces 'to be confirmed' dates, `mapa_url` is a real PNG that should be rendered immediately after the stage table, and the Spanish section requires asking for confirmation before quoting. This is exactly the kind of runtime behavior and interaction protocol an agent needs.

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 the core purpose, then systematically covers usage scope, parameter semantics, output behavior, and the confirmation workflow. There is no filler; the Spanish section earns its place by adding the pre-quote confirmation instruction rather than merely repeating the English text.

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 description is nearly complete for a 7-parameter tool with an output schema: it explains optionality, date behavior, output rendering, and the client-confirmation workflow. The main missing piece is guidance on how to obtain valid `camino_slug` and `poblacion_inicio_id` values, which would make first-time invocation fully unambiguous.

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 0% schema description coverage, the description carries the burden and does it well for most parameters: it defines `ritmo` with exact km/day ranges, explains `km_max_etapa` as an explicit cap or cycling (~2x), specifies `fecha_inicio` format and the consequence of omitting it, and scopes `num_noches` to fixed-night requests. However, the required `camino_slug` and `poblacion_inicio_id` plus the optional `poblacion_destino_id` are left only to their names, with no guidance on where valid values come from.

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: 'Build a day-by-day Camino de Santiago itinerary' and enumerates the concrete outputs (walking stages, km per day, overnight towns, dates, route map image). It also defines the exact scope of questions it answers, such as 'any Camino itinerary, stage plan or "how many days from Sarria/Tui/Porto/Roncesvalles" question', which distinguishes it from the quoting/packaging siblings in this tool set.

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 when to use the tool ('Use it for any Camino itinerary, stage plan...'), when to call it even without a confirmed date ('call it anyway'), and gives conditional parameter guidance (use `km_max_etapa` instead of `ritmo` for a cap or cycling; pass `num_noches` only when the client fixes the number of nights). It lacks explicit alternatives or 'when not to use' statements naming sibling tools, so it does not earn a 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description does not contradict them — a quote is a read operation, and booking creation belongs to a sibling tool. The description adds substantial behavioral context beyond annotations: auto-selecting accommodation by quality filters, falling back to an alternative category when a night has no availability (surfaced via `avisos`), expected latency of 20-45 s, and a cache/retry behavior on timeout. No contradiction found.

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 well-organized, front-loading purpose and usage before parameter semantics, then performance and retry notes. Most sentences earn their place. However, the trailing Spanish block largely duplicates the English content, adding length without new information for English-dominant agents, which slightly reduces efficiency.

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 10-parameter tool with 3 required args and an output schema, the description is quite complete: it explains when to call, how parameters map to business semantics, performance expectations, retry behavior, and the handoff to create_camino_booking_proposal. The main shortfall is the lack of guidance on how to structure etapas and habitaciones, which are required complex inputs; the reference to plan_camino_itinerary partially mitigates this.

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 schema description coverage at 0%, the description carries the full burden and compensates well: it enumerates the presupuesto enum values (sin_preferencia | lt_500 | 500_1000 | 1000_1500 | gt_1500) and marks it REQUIRED, lists meal_plan and categoria_alojamiento enums, explains extras_ids sourcing from camino_extras_catalog and its defaults, and clarifies nacionalidad/residente_espana semantics (sets insurance) and mascotas. The gap is that the required complex objects etapas and habitaciones are never structurally explained in the description.

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 operation on a specific resource: quoting a complete Camino de Santiago trip as ONE all-in package price, and explicitly marks it as the source of the official Ourway price. It differentiates itself from siblings by asserting it NEVER returns per-hotel/per-night/per-extra prices and by naming plan_camino_itinerary and create_camino_booking_proposal as adjacent tools, so the agent can tell it apart 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?

Usage conditions are explicit and front-loaded: 'Use it whenever the user asks how much a Camino costs, wants a quote, or approves an itinerary from plan_camino_itinerary.' It also gives a negative usage rule ('NEVER returns per-hotel... prices') and ties downstream behavior to create_camino_booking_proposal, which routes the agent away from this tool for booking creation.

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 it is a mutation (readOnlyHint false). The description adds that a NEW signed offer is generated with the new total, and that the most recent offer should be used for booking. It does not disclose side effects like invalidation of the old offer or reversibility, which given the non-destructive annotation is a partial 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?

The description is two sentences (plus a Spanish translation) and front-loads the action. The English part is efficient and includes the key workflow. The bilingual duplication is redundant but not excessively lengthy.

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 tool with an output schema, the description covers the essential workflow: applying an alternative, receiving a new offer, and using it for booking. It lacks explicit steps (e.g., needing to fetch alternatives first) but the output schema and sibling names help fill context. It is fairly 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 0%, so the description must explain parameters. It implies that 'alternativa_id' comes from the named sources, and 'oferta_paquete_firmada' is the current signed offer. 'noche_num' is implied by 'swap the hotel of one night' but not explicitly described. It adds moderate meaning but not full parameter-level detail.

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 action: swap the hotel of one night by applying an alternative from specific sources (camino_hotel_alternatives or adjust_camino_package) and produces a new signed offer. It clearly distinguishes itself from siblings by specifying the input source and the output, even mentioning the exact field name for the new offer.

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 context: it requires an alternative from named tools and advises using the most recent offer for create_camino_booking_proposal. However, it does not explicitly state when to use this tool versus adjust_camino_package or other alternatives, nor does it say when not to use it.

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