passagens-api

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

With no annotations, the description carries full responsibility for disclosing behavior. It usefully reveals that booking links include a Travelpayouts referral code and that prices are identical with or without it. However, it does not explain what the response contains, how results are ordered, or other operational side effects.

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

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

The description is compact and front-loaded with the core purpose, followed by the important referral-code disclosure. The PT/EN duplication is somewhat redundant but justifiable for bilingual users and does not bloat the 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 parameters are well documented by the schema, and the description implies the tool returns booking links. Still, with no output schema, it would be helpful to state what fields are returned, whether results are sorted by price, and how optional return_date affects the search. Some operational details remain implicit.

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 already covers 100% of parameters, so the baseline is 3. The description only restates the existing 'place name in Portuguese' behavior for origin and destination, adding no new semantic 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?

The description clearly states the tool's function: finding the lowest known price between two points with flexible dates. It also adds distinguishing context by noting it accepts Portuguese place names, though it does not explicitly contrast itself with the sibling tools.

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

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

There is no guidance on when to use this tool versus search_flights or price_calendar. The phrase 'flexible dates' hints at a use case, but no explicit conditions, exclusions, or alternative tool recommendations are given.

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 disclosure burden. It usefully discloses that booking links contain a Travelpayouts referral code, that the operator earns a commission, and that prices are identical with or without the code. However, it does not explicitly state whether the tool is read-only or describe any side effects beyond generating links.

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-loaded with its purpose, which is good. However, the English sentence 'Price-per-day matrix for a month' is a near-duplicate of the opening Portuguese phrase, and the Portuguese city-name acceptance is already documented in the schema, adding mild 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 simple and all parameters are documented, but there is no output schema. The phrase 'matriz de preço por dia' gives a general sense of the return format but does not specify the structure, how missing flights are represented, or whether booking links appear directly in the output. The referral/commission context does add completeness.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds little beyond the schema: it repeats the Portuguese city-name behavior already present in the origin/destination parameter descriptions and does not explain month/currency formats 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?

The description clearly identifies a price-per-day matrix for a full month between two points, explicitly answering 'quando é mais barato voar'. It lacks an explicit action verb like 'generate' or 'show', but the resource and question being answered are specific enough to distinguish it from generic flight search tools.

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

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

The description gives a concrete use case: answering 'when is the cheapest time to fly'. This is clear contextual guidance for when to invoke it, though it does not explicitly name alternatives like cheapest_route or search_flights, nor state when not to use them.

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 explains the core behavior (place name → IATA codes) and mentions language flexibility, but does not disclose whether the operation is read-only (implied but not stated), how errors or ambiguous inputs are handled, or any rate limits. For a lookup tool this is serviceable but not exhaustive.

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 efficient, with the core purpose front-loaded and a practical example embedded. The Portuguese/English duplication adds length but both versions carry parallel content, so it's not wasteful. Every sentence serves a purpose; no fluff.

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 3-parameter tool without an output schema, the description provides enough context: purpose, input format, example, and usage timing. It does not explicitly detail response structure (e.g., list of IATA codes with city vs airport labels), but the example implies this. Given the simplicity, it's adequately 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 100% with each parameter described. The description adds critical value by giving a concrete example of the q parameter mapping to multiple IATA codes (city and airports), and clarifies that q accepts names in any language. This goes beyond the schema's basic description and helps the agent understand expected output.

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

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

Description states a clear verb-resource mapping: resolves place names to IATA codes, with concrete examples ('São Paulo' → SAO, GRU, CGH). It clearly distinguishes from sibling flight/search tools by focusing on location disambiguation, leaving no ambiguity about what it does.

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

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

Explicitly states when to use it: 'Use quando precisar desambiguar a origem/destino antes de buscar' (use when needing to disambiguate origin/destination before searching). It implies it's a preparatory step, but does not explicitly mention alternatives or when not to use. That's sufficient given the clear sibling separation.

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 load and does well: it names the data source, the collection cadence ('várias vezes ao dia'), the coverage (round trip 5–15 days plus one-way), the computed aggregates, and that page_url should be cited. It omits any statement about read-only safety, rate limits, or response shape, keeping it short of 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?

The tool's core identity is front-loaded, but the text mixes Portuguese with a trailing English fragment ('Daily price history of a whole route from Brazil') and spends a sentence on example phrasings already implied by the metrics list. Some redundancy for the length.

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?

Returned content is described thoroughly enough that an agent can judge relevance without an output schema, and the Brazil-only scope is flagged. Missing is any routing guidance versus the closely related trip_price_history and price_calendar siblings, which is the main ambiguity for selection.

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 origin/destination and dias are already documented, giving a 3 baseline. The description repeats the Portuguese city-name support already in the schema, and its reference to 'últimos 30 dias' alongside a separate dias parameter (1–365, default 90) risks confusing which window controls the statistics.

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 scope: historical daily minimum prices for a whole route, sourced from passagens.dev, with the metrics that come back (daily min, 30-day min/max/avg, today vs average). The phrase 'rota inteira' implicitly distinguishes it from trip_price_history and price_calendar, but no sibling is named outright.

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 conveyed only through example questions ('está barato agora?', 'é boa hora para comprar?', 'quando esteve mais barato?'), which implies the right context without stating when to prefer it over trip_price_history, price_calendar, or cheapest_route. No exclusions or prerequisites are given.

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 behavioral disclosure burden. It transparently discloses that prices are cached, not real-time, and that booking links contain a Travelpayouts referral code with the operator earning a commission while prices remain identical. It also mentions that results include agent_display markdown ready to pass to the user. This goes beyond a minimal description.

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 fairly concise but contains duplication: the Portuguese phrase 'Busca as passagens aéreas mais baratas conhecidas' is repeated in English as 'Search cheapest known fares.' The information is front-loaded with the primary purpose and then adds behavioral details. It is not overly long, though the repetition could be trimmed.

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 tool's complexity (9 params, no output schema), the description covers the main contextual points: it explains cached availability, the agent_display output format, and the referral mechanism. It does not explicitly state that it is a read-only operation, but that is implied. Missing guidance on error handling or pagination is minor since the schema covers parameters. Overall, it is reasonably complete for an agent 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 description coverage is 100%, so all 9 parameters are already documented in the schema. The description does not add additional parameter-level meaning beyond what the schema provides. The mention of accepting city names and resolving them automatically is already present in the origin/destination parameter descriptions, so the description adds no extra semantic value.

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

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

The description clearly states the tool's function—searching for the cheapest known airfares between two points, using cached prices from Aviasales/Travelpayouts rather than real-time availability. It also mentions that it accepts Portuguese city names. The purpose is specific and includes a verb and resource, but it does not explicitly differentiate itself from sibling tools like cheapest_route, which likely has a similar function.

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 provides context (cached fares, not real-time, returns agent_display markdown) but does not explicitly state when to use this tool versus alternatives like cheapest_route or price_calendar. The mention of 'preços em cache' hints that real-time queries should go elsewhere, but no explicit comparison or exclusion is made.

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 behavioral burden and does so well: it discloses daily data freshness, that travel date does not affect price, how active coupons are tested and returned, and which output fields appear under each parameter mode. It also instructs the agent to cite page_url, which is useful operational 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?

The description is front-loaded with the core purpose and then layers the parameter-specific behavior efficiently. It is somewhat long and dense, mixes Portuguese with a redundant English summary sentence, and would be easier to scan if structured, but most sentences add useful information.

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

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

Given there is no output schema and no annotations, the description is complete enough for correct invocation: it explains the main response shapes, coupon structure, page_url citation, and age/days behaviors. The remaining schema-covered details, such as region values and the limit default, are already in the schema.

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

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

Although schema description coverage is 100%, the description adds substantial meaning beyond the schema: no-days returns the minimum price per duration, days returns plans from cheapest to most expensive with coverages and comparison fields, and age filters to plans that accept that age. It explains the practical semantics of the main optional parameters rather than merely restating them.

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

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

The description states a specific resource and dimensions: travel insurance prices per person in BRL by destination region and trip length. It clearly distinguishes this tool from the flight/route/history siblings by domain, so an agent can identify it without opening the schema.

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

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

It gives explicit conditional usage for the optional parameters: without days it returns the cheapest price per duration from 1 to 90 days; with days it returns plans sorted by price; with age it filters to plans accepting that age. It also tells the agent to answer coupon questions with the returned coupon. It does not explicitly name alternatives or when-not-to-use cases, but the relevant sibling alternatives are in a different domain.

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 largely does so: it discloses the data's provenance (two one-way tickets observed daily), that statistics are scoped 'desde o início da observação', and that the real round-trip price only appears 'quando existe' – an important caveat. It also instructs the agent to cite page_url. Missing: currency and any note on data freshness/latency.

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

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

Front-loaded with the resource and its derivation, then a usage sentence and a citation instruction. Dense but every clause contributes; slightly long single sentence, but 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 no-annotation, no-output-schema tool, the description compensates well by enumerating the return fields (total, ida, volta, mínimo, média, preço real) and the daily-observation basis. The remaining gap is sibling disambiguation from route_price_history, which matters given how similar the names are.

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 date formats, IATA codes and automatic Portuguese city-name resolution are already documented in the schema. The description's only added parameter context is the Portuguese-name acceptance and the ida/volta pairing, which largely repeats the schema. 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?

The description uses a specific verb+resource framing: historical prices for a round trip on chosen dates, and it explains the mechanism ('montada com duas passagens só ida que o passagens.dev observa todo dia') plus the returned fields. It stops short of naming the near-identical sibling route_price_history, so an agent must infer the round-trip vs. one-way distinction from the text.

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

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

The line 'Use para quanto está ida dia X e volta dia Y e se está barato' gives a concrete usage scenario, which is better than nothing. However, there is no when-not guidance and no explicit routing against route_price_history or price_calendar, which are the obvious alternatives for the same question.

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