open-meteo-mcp-server

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

Annotations already declare readOnlyHint and idempotentHint, so the description adds value by specifying the prerequisite of a DataCanvas from certain tools and the expected workflow order, without contradicting 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 concise, front-loaded with the action, and includes only essential information in two sentences. No redundant content.

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 and only one simple parameter, the description covers the tool's purpose, the source of its input, and its role relative to the query tool, making it sufficiently complete for the agent.

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 captures all parameter details (canvas_id with explanation of its origin and truncation condition). The description reinforces the context but does not add additional parameter semantics beyond the schema, warranting the baseline score.

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 specifies the verb 'List' and the resource 'tables and their columns on a DataCanvas staged by' specific tools, making it clear what the tool does and distinguishing it from the sibling query 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?

It explicitly states when to call this tool ('Call this first to discover table names') and provides the alternative action ('before querying with openmeteo_dataframe_query'), offering clear usage 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 the description reinforces it with 'read-only SQL SELECT.' More importantly, it adds behavioral context not captured in annotations: the prerequisite that data must be spilled (truncated: true) and that exact table names from the staging tools must be used. It doesn't describe error handling or performance, but the output schema and annotations cover the core behavior, making this a strong but not perfect disclosure.

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 sentences long, front-loaded with the core purpose, and each sentence earns its place: purpose, usage prerequisite, and discovery alternative. There is zero fluff or redundancy with the schema. This is ideal conciseness.

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 tool with two parameters, an output schema, and clear annotations, the description covers all essential context: the data source, the exact condition for using this tool (spill), the requirement for exact table names, and a pointer to a sibling tool for discovery. It fully equips an agent to select and invoke the tool correctly without ambiguity.

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 both canvas_id and sql having detailed descriptions. The description adds complementary meaning by linking canvas_id to the spill event and emphasizing the need to reference the exact table_name from the tool returns, which is not fully explicit in the sql schema description. This is a meaningful enrichment beyond the structured 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 opens with a precise verb and resource: 'Run a read-only SQL SELECT against tables staged on a DataCanvas.' It explicitly names the sibling tools that stage the data and distinguishes itself from openmeteo_dataframe_describe by focusing on querying rather than discovery. This is a clear, specific purpose statement.

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: pass the canvas_id from a spill (truncated: true) and use the exact table_name returned. It also directs users to openmeteo_dataframe_describe as an alternative for discovering names, effectively telling when not to use this tool. This is textbook usage 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?

Beyond the readOnly/idempotent annotations, the description discloses key behaviors: data is modeled grid data (not station readings), archive returns real CAMS values back to at least 2022-10-01, lone start/end dates are rejected, and wide windows spill to DataCanvas or return a bounded preview with truncated: true. No contradictions 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 a single dense paragraph, but every sentence adds essential information for a complex tool. It could be structured more scannable (e.g., bullets), but the content is efficient and front-loaded with the core purpose.

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, multiple modes, spilling behavior), the description covers all critical aspects: data source, valid date windows, variable lists, and output size handling. An output schema exists, so return-value details are unnecessary. It is complete for an agent to invoke 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% with per-parameter descriptions, so baseline is 3. The description adds extra value by listing common variables for hourly_variables, explaining the window modes and mutual exclusivity, and clarifying the DataCanvas spilling behavior tied to canvas_id. It doesn't fully duplicate schema but enhances it with usage-level semantics.

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 the tool as providing modeled CAMS air quality data (PM2.5, PM10, etc.), which distinguishes it from measured-data tools. It explicitly mentions an alternative (openaq-mcp-server) for measured readings, further clarifying its specific purpose among 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?

The description gives explicit usage guidance: it contrasts modeled vs. measured data, explains the three modes (forecast, past_days, archive range), and states the mutual exclusivity and requirement for both dates in a range. It also mentions the alternative tool for measured data, satisfying the when/alternatives requirement.

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 provide readOnly and idempotent hints, and the description greatly enriches behavior: unknown model names are sent upstream, multi-model responses suffix variable names, missing model-variable combos return null, and large results spill to DataCanvas with a bounded preview and 'truncated: true' when not enabled. This goes well beyond the annotation baseline.

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 every sentence conveys essential behavior or constraints; there is no fluff or repetition. It front-loads the core purpose in the first sentence and then systematically covers models, naming, nulls, and spill behavior without waste.

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 with output schema present, the description covers the critical behavioral nuances—model handling, variable suffixing, null semantics, and large-result spill behavior—that are not inferable from schema or annotations. It is complete enough for an agent to select and invoke 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?

Even with 100% schema description coverage, the description adds significant parameter-level meaning: it explains the models parameter behavior (suffix rules, upstream pass-through, nulls), and the canvas_id spill behavior. This is additional context not fully captured in the schema's per-parameter descriptions.

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 that the tool provides long-range climate projections from bias-corrected daily CMIP6 models over 1950-2050, with an explicit purpose: answering 'what will conditions look like through 2050?'. It also distinguishes itself from openmeteo_get_historical as the 'future-projection counterpart', which disambiguates it from a key sibling.

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 when-to-use context (future projections through 2050) and names the alternative openmeteo_get_historical for past ERA5 data. It also specifies 'Daily resolution only', which is a clear constraint that guides the user away from expecting hourly data and toward forecast/ensemble tools for other resolutions.

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 provide safety profile; description adds useful context (model, resolution, max pairs) without contradicting 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?

Two efficient sentences, front-loaded with purpose, no unnecessary words.

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?

Adequately covers purpose, constraints, and use cases for a simple, idempotent lookup tool with output 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?

Schema coverage is 100%; description adds value by explaining coordinate pairs, max pairs, and matching requirement.

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?

Clear verb ('get') and resource ('elevation'), specifies model source and resolution, distinguishes from weather-focused 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?

Describes typical use cases (geographic context, elevation-adjusted interpretation, route planning) but lacks explicit when-not-to-use or comparison to alternatives.

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 reveals non-obvious behaviors such as regional model coverage gaps surfacing as input errors, unknown model names being forwarded upstream, and large results spilling to DataCanvas with a truncated preview. These traits go beyond the readOnlyHint and idempotentHint annotations, which already establish safety.

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 a clear summary but then lists all 20 available models verbatim, duplicating the same list in the schema. This makes it longer than necessary and reduces conciseness, though the behavioral notes are useful.

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, many model choices, and ensemble expansion — the description covers the key scenarios: when to use it, how output is structured, how coverage errors behave, and what happens on large pulls. The output schema covers return structure, so no additional return-value documentation is needed.

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 provides exhaustive descriptions for all 12 parameters, including member-suffix output naming and the hourly/daily requirement. The description repeats this information without adding new semantic detail, so it meets the baseline of 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 opens with 'Probabilistic ensemble weather forecast', immediately conveying a specific verb and resource. It further clarifies by giving member counts, forecast range, and member-suffixed columns, which distinguishes it from sibling forecast tools like openmeteo_get_forecast.

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 'Use the spread across members to compute exceedance probabilities, quantify forecast uncertainty, and build decision thresholds', which is a clear when-to-use directive. It also advises on model selection (global vs regional) but does not name alternative sibling tools for deterministic forecasting, so it lacks explicit exclusions.

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 readOnlyHint and idempotentHint annotations, the description discloses several important behavioral traits: automatic snapping to nearest river (no river ID needed), null returns for far coordinates, 210-day forecast horizon, reanalysis back to 1984, mutual exclusivity of modes with rejection of lone dates, and the canvas spill mechanism with truncated: true when canvas is not enabled. These details materially help an agent predict behavior.

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-structured. It opens with the core purpose, then sequentially addresses usage modes, variables, edge cases, and output spill behavior. Every sentence adds necessary information, and there is no redundant repetition of schema details. The length is justified by 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 (8 parameters, two usage modes, output spill threshold), the description is complete. It covers all essential context: mode selection, variable options, null handling, coordinate snapping, and behavior for large result sets. Since an output schema exists, the description does not need to explain return structure, so no gaps remain.

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?

Even though schema coverage is 100%, the description adds significant semantic value: it explains the mutual exclusivity between forecast_days and start_date/end_date, clarifies that a lone date is rejected, lists and describes the available daily variables, and explains the canvas_id behavior (spill threshold and inline truncation). This enriches the parameter meaning far beyond the schema's property descriptions.

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 specifies the tool's function: retrieving GloFAS river discharge forecasts and historical reanalysis for the nearest river to given coordinates. It explicitly distinguishes this from sibling tools by naming the resource (GloFAS, river discharge) and the unique snapping behavior. The verb 'Returns' and resource are specific 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 provides explicit usage guidance: it explains the two mutually exclusive modes (forecast_days vs start_date/end_date), the requirement for both date endpoints, and the fallback to openmeteo_search_locations for place name resolution. It also clarifies when the canvas spill behavior occurs, giving clear context for when to use this tool versus handling large results.

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, and the description adds detailed behavioral context: the return format (per-timestamp records with 'time' fields), the spillover behavior to DataCanvas with bounded preview and truncated flag, and the requirement that at least one variable array must be provided. It also warns about large outputs, which the annotations do not cover.

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 well-structured: it opens with the core purpose, then explains return format, lists common variables, discusses spillover behavior, and ends with a requirement note. Every sentence adds useful information without redundancy. Despite its length, it is dense and front-loaded with the most important facts.

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 tool with 11 parameters and an output schema, the description provides comprehensive context: it covers the data source (ERA5 lag), return structure, handling of large results, and clear guidance for choosing between hourly and daily variables. The existence of sibling tools like openmeteo_get_historical further helps the agent place this tool in context, and the description explicitly addresses that relationship.

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 well-documented. The description adds valuable semantics by listing common hourly and daily variables, clarifying that hourly names cannot be used in daily_variables and vice versa, and noting that daily aggregates must be used for daily summaries. This goes beyond the schema's per-property descriptions and helps the agent select valid and meaningful values.

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 with a specific verb ('Wealther forecast for coordinates') and resource ('coordinates'), and distinguishes it from siblings by noting it covers up to 16 days ahead and can use past_days for recent history. It also explicitly contrasts with openmeteo_get_historical, making the tool's scope 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 explicitly tells the agent when to use this tool: 'Use past_days instead of openmeteo_get_historical for dates within the last 1–5 days'. It also gives contextual guidance on when results spill to DataCanvas, including the trade-off between large past_days and many variables. This is clear, actionable usage direction beyond simple alternatives.

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 and idempotentHint, but the description goes beyond by disclosing the ERA5 data lag (~5 days), the spill behavior to DataCanvas for large queries, and the bounded preview with truncated: true when canvas is not enabled. This adds significant context not captured in structured metadata.

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, four sentences, and front-loaded with the core purpose. It efficiently covers usage, constraints, and edge cases without redundancy. Every sentence 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?

Given the tool's complexity (11 params, 100% schema coverage, output schema present), the description provides essential context: data source, lag, spill behavior, truncation, and comparison with the forecast API. It is sufficiently complete for an agent to select and invoke 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?

The input schema already provides 100% coverage with detailed descriptions for all 11 parameters, so the baseline is 3. The description does not add meaning beyond the schema; it merely restates that start_date and end_date are required and that at least one variable list is needed, which is already present in 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 identifies the tool as providing historical weather from the ERA5 reanalysis archive (1940–present), which is a specific verb+resource combination. It also distinguishes itself from the forecast tool by directing users to openmeteo_get_forecast for recent dates, thereby setting it apart 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?

Explicit guidance is given: for dates within the last ~5 days, use openmeteo_get_forecast with past_days instead. It also states required parameters (start_date, end_date) and the requirement of at least one of hourly_variables or daily_variables, giving clear when-to-use and alternative tool instructions.

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?

Even though annotations already declare readOnlyHint and idempotentHint, the description adds substantial behavioral detail: the mutually exclusive date windows, rejection of a lone start_date or end_date, per-timestamp return structure, canvas spill behavior with truncated previews, and the null ocean_current_velocity caveat. These go well beyond the annotation baseline.

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 information-dense, covering purpose, parameter constraints, usage caveats, and return behavior without fluff. It is front-loaded with the main purpose sentence, and each subsequent sentence contributes a distinct operational or behavioral fact.

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, mutually exclusive date windows, multiple variable categories, and canvas spill behavior), the description is exceptionally complete. It explains the main usage patterns, edge cases (inland points, null ocean current, lone dates), result structure, and large-result handling, so an agent has enough context to invoke it correctly even without reading the full 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?

The input schema already provides 100% coverage for all 10 parameters with descriptions, so the baseline is 3. However, the description adds value by listing common hourly and daily variable names (e.g., wave_height, swell_wave_height, wave_height_max) and clarifying the output record shape ('time' field plus one key per variable), which is not fully specified in 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 opens with a specific verb and resource: 'Marine wave and ocean conditions for a coastal or ocean coordinate,' listing concrete variables such as wave height, wave period, and sea-surface temperature. It clearly distinguishes this tool from weather, climate, air quality, and other sibling tools by focusing on marine/ocean data.

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 clear context on when this tool is appropriate ('Best for open-ocean and coastal exposed points') and an explicit exclusion ('sheltered inland waters return near-zero wave values'). It also explains data-window selection (forecast_days, past_days, or start_date/end_date) but does not explicitly name alternative sibling tools, so it stops short of 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?

Annotations already declare readOnlyHint and idempotentHint. The description adds behavioral details: returns up to 10 matches ranked by population/relevance, and that it is a required prerequisite. No contradictions 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?

Five sentences, front-loaded with purpose, then prerequisites, then parameter usage. Every sentence adds value with no repetition or fluff. Structure is logical and easy to parse.

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 fully explains the tool's role as a prerequisite, how results feed into sibling tools, and the ranking logic. With output schema present, return values need not be detailed. Complete for the use case.

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% (baseline 3), but the description adds significant value: explains that 'name' should be bare, 'country' is for disambiguation, 'language' has script detection and retry logic, and 'count' is for disambiguation. These details go well 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 resolves a place name to ranked coordinate matches with country, region, elevation, timezone, and population. It distinguishes from sibling weather tools by highlighting that it is a prerequisite for name-based queries since weather tools require latitude/longitude.

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?

Explicit guidance on when to use (prerequisite for name-based queries), how to use (search bare place name, use country input to disambiguate), and what not to do (never fold qualifier into name). Clear alternatives via sibling tools are implied.

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