Price history

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

Annotations already establish read-only, idempotent, non-destructive, closed-world behavior, and the description adds genuinely new behavioral facts on top of that: the environment opt-in requirement, the no-conversion/no-forecast guarantees, the failure mode (unreadable log yields read_error with series null), and the crucial distinction that null means unknown rather than empty. That is exactly the kind of context annotations cannot carry.

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 identity and the opt-in constraint are front-loaded, and nearly every clause carries a distinct fact (scope, series shape, single-observation behavior, currency rule, null semantics). The telegraphic 'route is ORIGIN-DEST; date matches...' style is efficient, though the clipped phrasing costs a little 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?

An output schema exists, so return-field explanation is not strictly required, yet the description helpfully characterizes the series anyway and covers the failure/null semantics an agent needs for correct interpretation. The remaining hole is the undocumented kind/limit/query_key parameters, which is the one thing an agent could still get wrong.

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 whole burden, and it defines four of seven parameters: route as ORIGIN-DEST, date as matching a departure/return/check-in/check-out, location as a hotel stay, and currency via the never-merged/never-converted rule. It is silent on kind, limit, and query_key, leaving a substantial part of the surface undocumented in both places.

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 — a local read of price observations recorded on this machine — and scopes it precisely with the opt-in environment flag and the per-series shape (first_seen, last_seen, lowest, highest, change). It implicitly separates itself from search_flights/search_hotels (live search) and watch_price (forward-looking) by insisting nothing is forecast and nothing is merged or converted, though it never names those siblings explicitly.

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 discloses a real precondition (VIAJANTE_PRICE_HISTORY=1 must be set) and the interpretive rule that a single observation yields no trend, plus the note that it may run during a search. However there is no explicit routing advice — no statement of when to prefer this over watch_price or a fresh search, nor what to do when the log is disabled. 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.