experiences-oracle

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

With readOnlyHint=true and openWorldHint=true already declared, the description adds useful behavioral context: it compares across specific providers, returns a verdict and booking link, and explains how to interpret min_people, price_basis, and price_unit. It does not contradict the annotations, though it does not cover rate limits or provider availability limits.

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 and usage guidance are front-loaded, but the description is long and spends substantial space explaining result fields despite the tool having an output schema. It also includes an internal reference ('lo stesso testo delle azioni GPT, api/oracle_openapi') that does not help an external agent select or invoke the tool.

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

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

For a two-parameter read-only comparison tool with annotations covering safety and an existing output schema, the description supplies the missing pieces: exact purpose, when to use it, prerequisite data source, and parameter meanings. Nothing essential for correct invocation appears to be missing.

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

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

Schema description coverage is 0%, so the description carries the parameter burden and does so well. It defines experience_id with an example format and explains that query is optional, improves click attribution, and defaults to the experience title if absent.

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

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

The description names a specific verb and resource: compare the price of the SAME experience across providers and indicate the cheapest option. It also distinguishes the tool from siblings by making clear that search_experiences is the source of experience_id and that this tool specifically provides the best-price verdict.

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 explicit when-to-use guidance: 'USA QUESTO TOOL quando l'utente vuole il MIGLIOR PREZZO per un tour/attività specifico'. It also states the prerequisite of passing an experience_id obtained from search_experiences. However, it does not state when not to use the tool or name an alternative comparison path.

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, so safety is covered. The description adds useful interpretation rules for result fields (min_people, price_from vs price_basis/price_unit), but since an output schema exists much of this is redundant, and it never addresses auth, rate limits, or ordering guarantees.

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

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

Purpose and usage are front-loaded, but the middle block is a dense, deeply-nested set of output-formatting instructions that reads like prompt scaffolding rather than tool docs. The internal reference ('lo stesso testo delle azioni GPT, api/oracle_openapi') is noise to an MCP agent.

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

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

For a two-parameter read-only tool with annotations and an output schema, the description covers purpose, trigger, arg semantics and result interpretation, which is more than sufficient. The main gap is the absence of any sibling differentiation, which matters given the near-duplicate 'search_experiences'.

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 coverage is 0%, so the description must carry the load; it does so reasonably by defining 'place' with concrete examples ('Roma', 'Giappone') and bounding 'limit' ('max 30'). It still omits the default value and what happens with ambiguous or non-existent places, so it compensates well but not 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?

The description names a specific verb+resource ('Le migliori esperienze e cose da fare in una destinazione') and adds scope details (ordered by quality, booking links). It's clear what the tool returns, but it never distinguishes itself from the sibling 'search_experiences', which sounds strongly overlapping.

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 explicit positive guidance ('USA QUESTO TOOL quando l'utente pianifica un viaggio o chiede le TOP attività/esperienze di un posto'), which directly maps a trigger scenario to this tool. However, it names no alternatives and gives no exclusions, so the agent must infer when to prefer search_experiences or compare_experience.

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 annotations already establish readOnly, openWorld and non-destructive behavior. The description adds useful context beyond that: results are real, include city, price, rating and an affiliate booking redirect (PIQOD). It does not mention rate limits or pagination, but it goes meaningfully beyond the annotation profile.

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 usage, but it contains a long block explaining output fields such as min_people, price_basis and price_unit. Since an output schema exists, much of that return-value detail is likely redundant and makes the definition longer than necessary.

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 11-parameter search tool, the definition is nearly complete: it covers purpose, usage triggers, parameter meanings and intent mapping. The main gap is sibling differentiation, and the return-value explanation is arguably unnecessary given the output schema.

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

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

With 0% schema description coverage, the description fully compensates by explaining every one of the 11 arguments, including enum-like values for traveler_type, day_part and sort, the default and max for limit, and how keyword differs from query. The intent-to-filter mapping further clarifies how to populate filters from natural language.

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 clear verb and resource: search for tours, activities and experiences to book by location or travel intent, with examples. However, it never distinguishes this tool from its siblings compare_experience or get_destination_guide, so an agent must infer the boundary itself.

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

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

It explicitly says to use this tool when the user looks for things to do, tours, activities, tickets or experiences in a destination. It gives concrete intent-to-filter mapping, which is strong usage guidance, but it does not state when not to use it or name the alternative siblings.

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