open-meteo-mcp-server

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

Annotations already declare readOnlyHint and idempotentHint, and the description adds meaningful operational context: the tool only applies to DataCanvas objects staged by specific openmeteo_get_* calls. The 'List' wording is consistent with the read-only and idempotent behavior declared by the annotations.

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 contains two focused sentences: the first states what the tool does, and the second states the recommended call order. It is concise, front-loaded, and contains no filler or 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?

For a one-parameter tool with an output schema and read-only/idempotent annotations, the description provides the necessary workflow context: how the DataCanvas is staged, what the tool returns, and how it relates to openmeteo_dataframe_query. Nothing essential is 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 100%, and the input schema already explains that canvas_id must come from a truncated-result run of the openmeteo_get_* tools. The tool description adds no new parameter-level semantics, but none are needed because the schema fully covers the single parameter.

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 concrete verb-resource pair ('List the tables and their columns on a DataCanvas') and names exactly which staging tools produce the relevant data. It also differentiates the tool from openmeteo_dataframe_query, 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?

The description gives an explicit workflow instruction: 'Call this first to discover table names before querying with openmeteo_dataframe_query.' This clearly tells the agent when to use this tool and which sibling tool to use afterward.

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 description reinforces the read-only nature (matching the readOnlyHint annotation) and adds useful context about the spill/truncation mechanism and the requirement to reference the exact table names. This goes beyond the annotation alone, clarifying that the tool operates on staged data and is safe to call without 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?

Three sentences with no waste. The core action is stated first, followed by the necessary context on origin and discovery, and the alternative tool. Every sentence earns its place, and the description is appropriately front-loaded.

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 has an output schema (so return format is already captured), the description covers all operational essentials: when to use, what inputs to supply, and how to discover table names. An agent has everything needed to invoke it correctly without further research.

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 100% schema description coverage, both parameters are already well-documented. The description adds value by clarifying the provenance of canvas_id (returned by specific tools when truncated) and how sql should reference table names discovered via describe, enriching the schema definitions and reducing ambiguity for an agent.

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 ('Run a read-only SQL SELECT') and resource ('tables staged on a DataCanvas'), and explicitly names the sibling tools that stage those tables. It clearly distinguishes itself from the describe tool by focusing on querying rather than listing, leaving no ambiguity about its 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 explicit usage context: it should be called when any of the listed openmeteo_get_* tools return truncated: true, and it references the canvas_id and table_name from those tools. It also directs the agent to openmeteo_dataframe_describe when table discovery is needed, effectively outlining both when to use this tool and when to use its sibling.

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 description adds significant context beyond annotations: it explains the modeled vs measured distinction, the data spill behavior to DataCanvas for large windows, and the 7-day forecast limit with past days up to 92. The 'real CAMS values back to at least 2022-10-01' and 'earlier dates return nulls' notes are particularly valuable. Since readOnlyHint and idempotentHint are already set, the description doesn't need to repeat those; it focuses on data characteristics. Minor deduction: it doesn't explicitly state that results are bounded previews with truncated: true when canvas is disabled, but mentions it in passing.

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 dense but front-loaded: it starts with the core purpose, then adds usage rules, then details edge cases. Every sentence adds information, but it's a bit long (around 200 words). The structure is logical, but some points could be tightened (e.g., the spill behavior). Still, it's well-organized and not redundant.

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 complex tool with 9 parameters and an output schema, the description covers the essential decision points: which time window to use, the exclusivity rules, data type caveats, and spill behavior. The output schema exists, so return values are documented elsewhere. The only missing piece might be a note on coordinate resolution (but that's in the schema) and potential API limits beyond what's mentioned. Given the tool's complexity, this is quite 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%, so baseline is 3. The description adds value by summarizing common variables, explaining the mutual exclusivity of date parameters, and clarifying the 'at least one required' for hourly_variables. It also explains canvas_id's role in handling large results, which goes beyond the schema. However, some details like the exact maximum row count are left to the schema, and the description doesn't map every parameter explicitly, but it compensates well.

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 retrieves modeled CAMS air quality data with specific variables (PM2.5, PM10, etc.) and distinguishes it from measured station data by explicitly naming the alternative (openaq-mcp-server). It differentiates from siblings like openmeteo_get_forecast or openmeteo_get_historical by specifying the air quality domain, making its purpose unambiguous.

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 explicit guidance: when to use forecast_days, past_days, or start_date/end_date for archive ranges, and the exclusivity rules. It also advises against using this for measured data, pointing to openaq-mcp-server. This is clear, actionable routing guidance that prevents common misuse.

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 readOnlyHint and idempotentHint already declared, the description goes further: it discloses that unknown model names are sent upstream rather than rejected, error messages name the offending model individually, variable naming depends on model count, missing model-variable combos return null, and large results spill to DataCanvas with a truncated flag. These are valuable behavioral facts beyond the annotations.

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 long but front-loaded with the core purpose and structured logically: scope, contrast, resolution, model list, edge cases, and output behavior. Every sentence adds value; it's dense but not redundant. A slight trim could improve readability, but it's efficient.

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 11 parameters, output schema, and sibling tools, the description covers essential operational details: model validation behavior, variable naming, missing data handling, and canvas spill with truncation. It leaves little an agent needs to infer, making it complete for correct invocation.

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 baseline is 3. The description adds some contextual notes (e.g., daily resolution requires daily_variables, model suffix behavior) that are also largely present in the schema itself. It doesn't add significant new parameter-level meaning beyond the schema, so a 3 is appropriate.

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, resource, and scope: 'Long-range climate projections from bias-corrected daily CMIP6 models... at any coordinate.' It explicitly distinguishes from openmeteo_get_historical as the future-projection counterpart, making it clear what this tool does and how it differs from siblings.

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 clearly positions the tool as the future counterpart to openmeteo_get_historical, giving a strong when-to-use cue. It also mentions 'Daily resolution only' as a constraint. However, it doesn't explicitly mention when not to use other siblings like get_forecast or get_ensemble, leaving some ambiguity; still, the primary usage context is well covered.

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 idempotentHint=true, covering the safety and idempotency profile. The description adds the resolution (~90m) and the data source (Copernicus DEM), which is useful context. However, it doesn't disclose potential error behavior (e.g., invalid coordinates, server limitations) or response structure, but the output schema likely covers the latter. Given annotations cover the main behavioral traits, a 3 is appropriate.

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 concise and well-structured: it states the core function, the resolution, the input format, a capacity limit, and practical use cases in two sentences. No wasted words, and key constraints (100 pairs) are front-loaded.

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 tool with a clear output schema (not shown but indicated), the description covers all necessary aspects: what it does, input constraints, capacity, and use cases. Minor gap: it doesn't mention what the output looks like (e.g., elevation values in meters), but the output schema likely covers that. Also, it doesn't mention coordinate validation or error cases, but these are less critical given the annotations.

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 each parameter is already documented with ranges, constraints, and their relationship (must be same length). The description adds the semantic context of 'coordinate pairs' and the limit of 100 pairs, but doesn't add much beyond the schema's constraints. Baseline 3 is correct since the schema does the heavy lifting.

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 purpose: retrieving terrain elevation from a specific model (Copernicus DEM) at ~90m resolution. It specifies the input (coordinate pairs) and distinguishes it from weather-focused siblings like openmeteo_get_forecast. The verb 'Get Elevation' is specific and resource-oriented.

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 a clear 'when to use' context: 'useful for geographic context, elevation-adjusted weather interpretation, or route planning.' It doesn't explicitly state when NOT to use it or list alternatives, but given the distinct purpose (elevation vs weather), the guidance is adequate. A slight gap is not mentioning that for weather queries, siblings like openmeteo_get_forecast should be used instead.

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 declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds valuable behavioral context: regional models return input errors for out-of-coverage areas (not transient failures), unknown model names are passed upstream, and large queries spill to DataCanvas with truncated: true when canvas is not enabled. This goes beyond the annotations and helps the agent anticipate failure modes and data volume issues.

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 dense but well-organized, front-loading the core purpose and member naming, then covering models, failure modes, and data volume. It is long but every sentence carries information an agent needs. The model list is repeated in the schema, which is redundant, but the description's version adds member counts and coverage details that are useful for selection.

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 (12 parameters, 19 model options, ensemble output), the description is remarkably complete. It covers model selection, coverage limitations, output naming, data volume spill behavior, and the variable requirement. The output schema exists, so return values are documented elsewhere. An agent has everything needed to call this tool correctly and interpret results.

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 the schema already documents all parameters thoroughly. The description adds value by explaining the member-suffix naming convention for output columns, clarifying the distinction between hourly and daily variable names (including the temperature_2m_max/min exception), and emphasizing the requirement for at least one variable array. It also explains the canvas_id spill behavior in more detail than 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 provides probabilistic ensemble weather forecasts with up to 64 members and up to 16 days ahead, and explains the member-suffix column naming. It distinguishes this from sibling tools like openmeteo_get_forecast (deterministic) by emphasizing the ensemble nature and uncertainty quantification use cases.

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 explicitly explains when to use this tool (for probabilistic forecasts, exceedance probabilities, uncertainty quantification) and provides critical guidance on model selection, including regional model coverage limitations and the instruction to pick a global model or move coordinates rather than retrying. It also notes the requirement for at least one of hourly_variables or daily_variables, and explains the DataCanvas spill behavior for large queries.

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 and idempotent hints in annotations, the description discloses several important behaviors: it returns null for coordinates far from any river or without GloFAS coverage, it spills to DataCanvas for large reanalysis queries with a bounded preview and truncated flag, and it enforces mutual exclusivity of modes. It also explains the snapping behavior to the nearest stream. These details go well beyond annotations and give an agent predictable expectations about output and side-effects, with no contradiction.

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 comprehensive yet tightly packed. It leads with the core purpose, then the mode selection, then the variable list, and finally edge-case behaviors. Every sentence contributes new information; there is no fluff or repetition. The structure is logical and front-loaded, allowing a quick scan for the most critical information. Despite its length, it is efficient and earns its place.

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 complex tool with 8 parameters, a output schema, and multiple interactive behaviors, the description covers all necessary aspects: input coordinates, mode usage, supported variables, output limitations (null return), scaling behavior (spill to DataCanvas), and the existence of output schema means return values need not be restated. The agent has enough to call it correctly and anticipate outcomes in both normal and edge cases.

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 all 8 parameters at 100% coverage, so a baseline of 3 applies. The description adds meaningful semantic context beyond the schema: it explains why canvas_id is relevant (spill for large results), details the mutual exclusivity of forecast_days vs. start_date/end_date, lists example daily_variables, and clarifies that a date range requires both endpoints. This extra explanation helps the agent reason about parameter combinations and values, justifying a score above baseline.

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 opens with a precise resource and action: 'GloFAS (Global Flood Awareness System) river discharge forecast and historical reanalysis.' It further clarifies it returns daily ensemble river discharge for the nearest river to given coordinates, immediately distinguishing it from weather, climate, marine, or other Open-Meteo tools. The wording is specific and not a tautology, and the mention of 'no river ID needed' adds a differentiating nuance.

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 clearly states the tool's purpose and the two mutually exclusive modes (forecast vs. historical reanalysis), which is strong context for usage. It does not explicitly name alternatives like openmeteo_get_forecast or openmeteo_get_historical, nor does it say 'do not use for X.' However, the specificity of 'river discharge' and 'GloFAS' makes the intended use clear, so the lack of explicit exclusion clauses is a minor gap. This aligns with the 'clear context, no exclusions' anchor.

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 readOnlyHint and idempotentHint already declared, the description adds meaningful behavior: it discloses that large results 'spill to DataCanvas for SQL querying' and that truncated: true may appear, and it clarifies temporal window semantics (past_days before today, forecast_days ahead). It slightly overlaps with the schema's past_days note about ERA5 lag, but this is complementary reinforcement rather than redundancy. No contradiction with annotations.

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 long but highly information-dense)Skip; every paragraph adds unique value: tool differentiation, variable categories, output format, spillover behavior. It is front-loaded with the core purpose ('hourly and/or daily variables for coordinates') and avoids fluff, though the variable lists could be trimmed since they echo the schema examples.

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 tool, the description covers all decision-relevant context: temporal window (past_days + forecast_days), variable categorization rules with concrete examples, unit options, response structure per entry, spillover behavior for large queries, and the requirement for at least one variable array. The schema itself is rich, but the description adds the 'when to use' guidance and boundary conditions (e.g., hourly names rejected in daily_variables) that the schema alone cannot convey.

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%, but the description adds significant value: it lists common variables per category (e.g., weather_code, wind_gusts_10m for hourly; temperature_2m_max for daily), explains why an hourly variable like cloud_cover must use the 'published aggregate' (cloud_cover_max) for daily requests, and clarifies the past_days vs. historical tool tradeoff. This goes beyond the schema's terse field docs.

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 ('Get Forecast') and immediately elaborates: 'hourly and/or daily variables for up to 16 days ahead, with optional past_days (up to 92) for recent history.' It clearly differentiates from the sibling openmeteo_get_historical by explicitly saying when to prefer this tool for recent data. The output format is described in detail (per-entry 'time' field and one key per variable), making the tool's purpose unmistakable.

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 explicitly tells the agent when to use this tool over openmeteo_get_historical ('Use past_days... since ERA5 has a variable lag'), explains the hourly vs. daily variable split with rejections, and notes DataCanvas spillover for large queries. It also states the requirement that at least one of hourly_variables or daily_variables must be provided, giving clear invocation 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 and idempotentHint=true, so the safety profile is covered. The description adds valuable behavioral context: the ERA5 variable lag of ~5 days, the spill-to-canvas behavior for large results with truncated: true when canvas is disabled, and the bounded preview behavior. This goes beyond the annotations, though it doesn't detail the exact return structure (but an output schema exists).

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 a single, dense paragraph that front-loads the core purpose and date range, then covers the lag caveat, variable compatibility, and large-result behavior. Every sentence adds new information with no redundancy, and it's appropriately sized for an 11-parameter 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?

Given the tool's complexity (11 params, 4 required, output schema present), the description is complete. It covers the data source, date constraints, the alternative tool for recent dates, variable naming conventions, the required parameter condition, and the large-result spill behavior. The output schema handles return values, so nothing critical is missing for an agent to call this 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 the schema already documents all 11 parameters thoroughly. The description adds value by explaining the relationship between hourly and daily variables (e.g., daily aggregates like temperature_2m_max belong in daily_variables, not hourly), and the spill-to-canvas behavior tied to canvas_id. This complements the schema rather than repeating it, earning a score above the baseline 3.

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 retrieves historical weather from the ERA5 reanalysis archive (1940–present), with a specific verb and resource. It distinguishes itself from siblings by explicitly naming openmeteo_get_forecast as the alternative for recent dates, and the variable-name compatibility with the forecast API further clarifies its role.

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 explicit when-to-use guidance: it requires start_date and end_date, and explicitly states that for dates within the last week, openmeteo_get_forecast with past_days should be used instead. It also notes the requirement of at least one of hourly_variables or daily_variables, and explains the spill-to-canvas behavior for large ranges, giving clear context for when this tool is appropriate.

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 declare readOnlyHint=true and idempotentHint=true, so the description's burden is to disclose behavior beyond that. It does so thoroughly: 'Returns per-timestamp records — each entry contains a "time" field plus one key per requested variable,' and it details the spill behavior ('spill to DataCanvas for SQL querying... return a bounded preview with truncated: true when it is not'). It also flags 'ocean_current_velocity is null for non-open-ocean coordinates.' These behavioral specifics add real value beyond the annotations.

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 lengthy (over 150 words), but each sentence conveys a distinct fact or constraint. It is well-structured with lists of variables and clearly marked warnings (mutual exclusivity, variable-name rejection, inland near-zero). No sentence is redundant; the information density is high. A small deduction for being longer than strictly necessary, though every part earns its place given the tool's complexity.

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 (10 parameters, multiple windows, variable types), the description is remarkably complete. It explains the forecasting horizon (up to 8 days), past_days (up to 92), archive ranges (back to 2022), the per-timestamp output format, the spill behavior, null conditions, and validation rules. With an output schema already present, there is no need to detail the return structure further. The description fully equips an agent to call the tool 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 coverage is 100%, so baseline is 3. The description adds meaningful semantics by explaining the mutual exclusivity between date-range and forecast/past_days, the requirement for both start_date and end_date together, and the distinction between hourly and daily variable names (e.g., 'wave_height' vs 'wave_height_max') with rejection warnings. It also enumerates common variables, which helps users pick correct values. While the schema already documents each parameter, the description enriches the semantics with usage nuances.

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 purpose: 'Marine wave and ocean conditions for a coastal or ocean coordinate' and enumerates the covered variables (wave height, period, direction, etc.). It clearly distinguishes itself from land-focused siblings like openmeteo_get_forecast or openmeteo_get_climate by emphasizing the marine domain. The verb and resource are explicit and unambiguous.

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 explicit when-to-use guidance: 'Best for open-ocean and coastal exposed points — sheltered inland waters return near-zero wave values.' It also clarifies when to choose between forecast_days and date-range windows, and describes the DataCanvas spill mechanism for large queries. It touches on when to use this tool versus avoiding it (inland points), and provides operational context for the archive range and recent history options.

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 indicate readOnlyHint and idempotentHint, so the baseline is lower. The description adds behavioral details like ranking by population/relevance, the localized index matching, and a retry mechanism for non-Latin scripts. This goes beyond the annotation and clarifies how the search behaves.

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, then provides usage guidance and parameter details. It is somewhat verbose, repeating schema descriptions, but remains well-structured and not excessive given the complexity of language handling and disambiguation.

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 description includes the purpose, usage context, parameter nuances, and return behavior (ranked coordinate matches, up to 10 results). Since an output schema exists, it doesn't need to detail the return structure, but it still gives sufficient context for an agent to decide when and how to call it.

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% and each parameter has a description, so baseline is 3. However, the description adds meaningful guidance beyond the schema, such as 'never fold a qualifier into the name' and the language retry logic for non-Latin scripts. This extra context helps the agent use parameters more effectively.

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 resolves a place name to ranked coordinate matches with specific fields (country, region, elevation, timezone, population). It explicitly positions itself as a prerequisite for name-based queries, distinguishing it from sibling weather tools that take coordinates.

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 this is a required prerequisite for name-based queries, and that all weather tools take latitude/longitude. It provides concrete usage rules: use a bare place name, never fold in qualifiers, and use the country parameter for disambiguation. This leaves no ambiguity about when and how to use the tool.

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