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?

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.