BudgetAtlas

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

Annotations already cover read-only/idempotent/closed-world, and the description adds substantive context beyond them: assumptions and formulas are surfaced, plus sample sizes, source coverage, freshness, observed ranges, and explicitly excluded categories. That is unusually rich disclosure of what the response will and won't tell you.

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?

Dense, front-loaded sentences; the mode statement comes first and the exclusion plus output inventory follow with no filler. Every clause carries information the agent would otherwise have to infer.

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 13 optional parameters, an output schema present, and only 54% schema description coverage, the description does well on output expectations and scope but leaves several input parameters unexplained. Slightly short of fully complete, but well beyond minimum viability.

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 54% and the description only reinforces a couple of fields (days vs exact-date mode, and the components fallback semantics are already in the schema). Many parameters — rooms, people, min_review_count, min_rating_fraction, lodging_types — receive no added meaning from the description, so compensation for the coverage gap is partial.

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?

Specific verb and resource ('Compare covered cities for a stay of N days, or for exact dates') with explicit scope negation ('This is not a cost-of-living total'). It distinguishes itself from a general cost-of-living style tool, though it never names compare_lodging_months or summarize_costs directly.

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 two pricing modes (N days vs exact dates) tell the agent which inputs select which behavior, and the schema points to get_dataset_coverage for valid cities. But it gives no guidance on when to pick this over compare_lodging_months or summarize_costs, so usage is implied rather than delineated.

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 read-only/idempotent annotations, the description explains important behavioral traits: results are based on observed sampled check-in dates, not monthly averages; it returns each month's distribution, a like-for-like subset of properties present in every month, and a cheapest month derived only from that subset. These details materially affect interpretation of the output.

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 three focused sentences: purpose first, then return composition, then the key sampling caveat. Every sentence adds useful information and there is no redundant 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 six-parameter comparison tool with an output schema and read-only annotations, the description covers the main purpose, output composition, and the critical 'sampled check-in date, not monthly average' caveat. It leaves out explicit sibling routing and does not discuss freshness_days, but the structured schema and output schema carry much of the remaining detail.

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 67%, with descriptions present for city, months, nights, and freshness_days. The description adds useful meaning around 'single stay length and occupancy' and clarifies that months are sampled check-in dates, but it does not compensate for the undocumented rooms/adults parameters or explain freshness_days.

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 verb and resource: compare observed nightly lodging rates for one city across check-in months, with a single stay length and occupancy. That scope is clearly distinct from a generic lodging search or city-cost comparison, so an agent can identify the tool's role 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?

The description implies when this tool is appropriate: cross-month comparison of lodging rates using collected check-in months. However, it does not explicitly say when to use it instead of search_lodging, nor does it name any alternative or exclusion condition.

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 cover safety (readOnlyHint, idempotentHint, closed-world), but the description adds context annotations cannot express: the call is free, coverage figures are read live from the database rather than cached, and failures are classified by blocker type with the prerequisite that would lift it. It also implies a cost asymmetry with the other tools, which shapes agent planning.

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?

Three sentences with no filler, and the two most decision-relevant facts — it is free and it should be called first — sit at the start and end where they will be read. The middle sentence is long but every clause (examples, blockers, prerequisites) is a distinct piece of 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?

With an output schema present, the description need not describe return values, and it instead explains what those values mean (answerable classes, runnable examples, blocked classes with lifting prerequisites). The one gap is the boundary against get_dataset_coverage and get_data_freshness, which share the introspection role.

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 tool takes zero parameters and the description correctly says nothing about arguments, so there is nothing to misinterpret. Baseline 4 applies for a 0-param schema; no value is added or lost.

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?

A specific verb+resource: it lists the question classes the dataset can answer (with a runnable example argument per tool) and the questions it cannot, with named blockers. That is plainly a different kind of operation from every sibling (search_*, compare_*, summarize_costs), so an agent can classify 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?

"Call this before spending anything" gives an explicit trigger condition plus the cost rationale ("free"), which is stronger than most tools manage. It does not differentiate itself from the neighbouring introspection tools get_dataset_coverage and get_data_freshness, which likely overlap in scope, so routing between those three is left to inference.

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 readOnly, idempotent, closed-world, so the safety profile is covered. The description adds real behavioral detail beyond them: the four verdict buckets (fresh/aging/stale/empty), that a verdict reports the number behind it, and that the last collection run's status is included — useful context an agent would not infer from the schema.

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 core purpose, followed by a compact enumeration of what is reported and a closing usage directive. The middle clause is dense and list-like but every element identifies a distinct returned attribute; nothing is padding.

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 structure needn't be spelled out, and the description still summarizes the salient outputs and verdict semantics. For a zero-required-parameter read tool, an agent has everything needed to decide to call it and how to interpret the staleness threshold.

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 baseline is 3. The description earns above baseline by framing stale_after_days as 'a staleness line you choose' and connecting it causally to the verdict categories, which the schema does not state as a relationship.

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 ('Report how old the data is') and enumerates the exact outputs: newest/oldest observation, age in days, a named verdict, and last collection run status. It is clearly distinguishable from siblings like get_dataset_coverage, which is referenced only for obtaining the city list.

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?

'Call this before quoting a price as current' gives a concrete trigger condition tied to the agent's task. It does not name an alternative tool or a when-not-to-use case, but for a freshness check the positive trigger is the operationally relevant guidance.

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 openWorldHint=false, so the safety profile is covered. The description adds value by disclosing that output includes 'blocked collections' and 'known gaps' — behavioral substance an agent would not otherwise know. Return shape is covered by the output schema, so no penalty there.

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?

Two sentences, front-loaded with the core purpose, and the action directive is placed at the end where it is easily found. The enumerated list is dense but each item carries distinct meaning, so nothing is gratuitous.

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 strong annotations, an output schema, and zero required parameters, the description covers enough for correct invocation. The only gap is clarifying how the four optional filters scope the report, which the schema only partly addresses.

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 50%, and the description implies filtering dimensions via 'per-source counts' and 'numeric restaurant-price coverage' (mapping loosely to source/category). However, the countries parameter and the relationship between the city/source/category filters and the report are not clarified 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 uses a specific verb ("Report what BudgetAtlas actually holds") and enumerates exactly what resource is covered: cities, per-source counts, lodging date/occupancy cohorts, restaurant-price coverage, blocked collections, gaps. This clearly marks it as a metadata/coverage tool, easily separable from siblings like compare_city_costs or search_lodging.

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 an explicit sequencing directive, "Call this before any broad comparison," which tells the agent when to use it. It does not name the specific sibling (compare_city_costs, compare_lodging_months) or spell out when NOT to use it, keeping it just below 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?

Goes well beyond the readOnly/idempotent annotations: states fares are whole-trip totals for the whole party, that data is historical rather than live, that `provisional` rows have a high-biased minimum, and that only aggregates are published. This is exactly the kind of caveat an agent must know before presenting numbers to a user.

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 purpose, then return shape, then caveats — a logical order with no filler sentences. The sentence enumerating return fields is somewhat redundant given an output schema exists, which trims a point but not the practical 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?

Covers data provenance, aggregation level, and the provisional-data trap thoroughly, and the output schema handles return structure. The gap is the zero-required-parameter design: the description never says what happens when origin/destination/depart_month are omitted, nor how results are ordered or capped by `limit`.

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 58%, so roughly half the 12 parameters are documented structurally. The description adds real meaning for party sizing ('whole-trip totals for the whole party') and for the provisional flag ('minimum is biased high'), but says nothing about cabin, trip_type, stay_nights, limit, or max_price_usd 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?

Specific verb and resource with explicit bidirectional geography: 'Find observed round-trip fares from European hubs into Southeast Asian cities.' The scope constraint (Europe→SE Asia, fare aggregates only) plus the title cleanly separates it from the non-flight siblings (search_lodging, search_restaurants, compare_city_costs).

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?

Provides a strong exclusion — 'historical observations, not live availability' and 'no itinerary-level fares or booking links' — which tells the agent not to treat results as bookable prices. However, it never names an alternative source for live fares or explains when to prefer this over a sibling tool, so no explicit routing guidance.

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, idempotentHint, and openWorldHint=false, so the low bar is met. The description adds meaningful context beyond that: 'historical snapshots, not live availability,' which is a genuine behavioral trait an agent must know (prices may be stale, not bookable). Return contents are also summarized.

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?

Three tight sentences, front-loaded with the core action, then return shape, then the critical caveat. Every sentence earns its place with no 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?

An output schema exists so return values need not be elaborated, but with 16 parameters and only 38% description coverage, the definition leaves a large filter surface under-explained. The mode guidance is present, but the many filter parameters lack any narrative meaning.

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?

At 38% schema description coverage the description should compensate, but it only addresses the date-vs-nights mode mapping. It says nothing about the 16 parameters' filters (sources, max_nightly_usd, required_signals, min_rating_fraction, freshness_days), leaving most of the surface documented only in the schema (or not at all).

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?

Specific verb (Search) plus resource (stored lodging price observations) and scope (a city). It clearly distinguishes a raw price-search from aggregation siblings implicitly via 'observations,' but never names compare_lodging_months or compare_city_costs, leaving the agent to infer which sibling handles comparison.

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 explains the two calling modes (exact dates via checkin/checkout vs stay length via nights), which is useful usage guidance. However, it gives no when-not-to-use or explicit routing to the many comparison siblings, so an agent still has to guess when search_lodging vs compare_lodging_months applies.

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 cover the safety profile (readOnly, idempotent, closed-world), yet the description still adds real value: FX conversion, provenance, per-source ratings, and the notable behavior that unobservable-price venues are reported as a coverage gap rather than silently dropped. That is a non-obvious behavioral trait worth the credit.

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?

Three sentences, front-loaded with the purpose, then return shape, then the edge case. Slightly over-invested in enumerating return fields that an output schema already documents, but nothing is padding.

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 return-value sentence is largely redundant, while the genuinely missing pieces — what the enum filters mean, how freshness_days defaults interact with coverage, and result limits — go unaddressed. Adequate, but the emphasis is misplaced for a 1-required/8-param tool.

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 only 38%, so the description needs to compensate, and it largely does not: price_kinds, venue_types, min_review_count, min_rating_fraction, and limit get no explanation anywhere. Only the price ceiling concept is echoed ('by observed numeric price'), and the enum values themselves are undocumented.

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 ('Find restaurant venues in a city by observed numeric price') plus the qualifying constraint, which cleanly separates it from search_lodging, search_flights, and the compare_* siblings. An agent can pick 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?

The price-filter framing implies when to use it, and the coverage-gap sentence hints at a limitation, but there is no explicit when-to-use/when-not guidance and no routing to alternatives such as summarize_costs or compare_city_costs. Usage must be inferred.

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 (readOnlyHint, openWorldHint=false, idempotentHint), the description adds meaningful reporting behavior: city distributions are always shown before country figures, and a country median never generalizes to unobserved cities. It does not detail behavior when coverage is insufficient, but the key caveats are disclosed.

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?

Two sentences, front-loaded with purpose and followed by the critical reporting-order caveat. Every clause contributes useful information without repetition or 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 read-only summary tool with an output schema and safety annotations, the description covers the key output behavior and country-level caveat well enough to call correctly. The main missing piece is routing guidance against similar comparison/search siblings.

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 57%, and the description only implicitly references the cities/countries parameters while adding nothing about rooms, adults, nights, category, or freshness_days. The schema still documents the most important parameters adequately, so this is minimally sufficient.

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 (Summarize) and resources (lodging nightly rates, restaurant meal prices) plus the aggregation scope (cities, then country median). It is clear what the tool produces, but it does not explicitly distinguish itself from the sibling compare_city_costs tool.

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 explains what the tool does but gives no explicit guidance on when to use it rather than a sibling such as compare_city_costs or search_lodging. There are no when-to-use, when-not-to-use, or prerequisite statements.

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