EPW.tools

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

Annotations already cover read-only, idempotent, open-world and non-destructive behavior, so the description's added value is the operational constraints: no key required (no auth setup), a 10 MB size cap, and that the output includes data-range warnings. It does not mention failure modes for unreachable or non-EPW URLs, which is the main remaining gap.

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?

A single dense sentence that front-loads the purpose, then the returned values, then the access and size constraints. No filler, no repetition of the title or schema, and every clause carries 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?

For a one-parameter, read-only fetch tool with an output schema already present, the definition covers purpose, accepted URL sources, auth requirements and a size ceiling. Only the exact URL format and error behavior are left unspecified, which is minor at this complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% and the single 'url' property is undocumented, so the description has to carry it. It does add meaning by naming acceptable sources (OneBuilding, EnergyPlus, a shared file) and the 10 MB limit, but it never says whether the URL must be a direct .epw file link versus a landing page or station ID.

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: 'Summary statistics of any public EPW by URL', and enumerates the returned quantities (location header, dry-bulb mean/min/max, GHI, warnings). This clearly separates it from the generate_* siblings, which create files rather than analyze one, though it never names a sibling explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives usable context on acceptable inputs ('any public EPW by URL (OneBuilding, EnergyPlus, a shared file)') and notes the tool is free with no API key, which implies 'call this when you already have an EPW URL'. However, it never states when to prefer it over generate_epw or get_design_conditions, leaving the routing 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 the non-read-only, open-world, non-idempotent, non-destructive profile, and the description adds real context beyond that: it is asynchronous (returns a job_id requiring polling) and it consumes credits, with a surcharge path. It also flags that urban_street_level only works for 53 US cities, a meaningful coverage limit not derivable 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?

Three sentences, zero filler, and the deliverable is front-loaded ahead of cost and workflow details. Even the parenthetical about hourly street-level air temperature from citizen stations adds decision-relevant substance rather than 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 values need not be described, and the async job pattern, credit model, temporal scope, and urban-data limitation are all covered. The remaining gap is guidance on data_source and dc_edition choices, which an agent must guess for a tool with high side-effect cost.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description carries the full burden, and it only explains two of eight parameters: the year window (1990 to last year) and urban_street_level (its cost and its 53-US-city restriction). lat, lon, api_key, dc_edition, data_source, and location_name remain entirely unexplained in both schema and description.

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?

"Start an actual-year (AMY) EPW + DDY + STAT for any point, 1990 to last year" gives a specific verb, three concrete output artifacts, and a scope. The AMY framing implicitly separates it from generate_tmy / generate_future_climate, though those siblings are never named.

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?

Supplies the practical context an agent needs before calling: credit cost (1, or +2 with urban_street_level) and the required next step, "poll with get_job_result". It stops short of stating when to prefer this over generate_tmy or generate_forecast, so it is clear context rather than full when/when-not 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 disclose mutation, non-idempotence, open-world behavior, and non-destructiveness; the description adds the forecast horizon and free-tier limit. It does not explain the "start" lifecycle, such as whether a job must be polled via get_job_result, or auth/rate details beyond pricing. This is useful but incomplete for a non-idempotent generator.

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 short sentences, front-loaded with the action and forecast horizon, plus a compact pricing note. No filler or repetition; every clause contributes useful scoping.

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 open-world, non-idempotent forecast generator with an output schema, the description gives enough to initiate the call and understand the horizon. It omits the job/result retrieval path and most parameter semantics, leaving gaps that matter for correct downstream use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must carry parameter meaning, but it only clarifies `days` as 1-15 days with up to 7 free. It says nothing about `lat`, `lon`, `api_key`, or `location_name`, leaving most parameters documented only by name/default.

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 ("Start") and resource ("forecast EPW") and gives the 1-15 day horizon plus example use cases, so the agent can distinguish it from generic EPW/TMY generation. It does not explicitly contrast with siblings such as generate_epw or generate_future_climate, which keeps it from a 5.

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 use cases (operational sims, MPC, demand response) imply when a near-term forecast is appropriate, and the 1-15 day range constrains use. It never explicitly says when to choose generate_epw, generate_future_climate, or generate_tmy instead, nor does it state 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?

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false and openWorldHint=true, so the safety profile is covered. The description adds one genuinely valuable fact not in structured data: the call costs 3 credits. It does not disclose that this is asynchronous work requiring polling via get_job_result, nor what happens to an existing EPW at the same path.

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 dense fragment-sentences with the verb and cost front-loaded and zero filler; every clause carries information. The telegraphic style is efficient but borderline cryptic, and the parameter hints are jammed into one run-on line rather than structured per argument.

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 described. Still, for an 8-parameter, credit-consuming, asynchronous generation tool, the description omits the async/job-result workflow and leaves base_year and location_name undefined, which is not enough to call it confidently on the first try.

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 0% schema description coverage and no enums, the description must carry the weight and does partially: it enumerates the four valid scenario strings and constrains horizon to decades 2030-2100. But half the parameters remain uninterpreted, most importantly base_year (the morphing reference period, default 2010) and location_name, whose purpose and effect are not explained anywhere.

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 artifact: 'Start a CMIP6-morphed future EPW' with the Belcher 2005 method named. This clearly separates it from generate_epw (present-day), generate_tmy (typical year) and generate_forecast. It loses a point only because 'EPW', 'CMIP6' and 'morphing' are unexplained jargon that an unfamiliar agent must infer.

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?

Implicitly scopes the tool to future-climate scenario files and explicitly routes the agent to list_cmip6_models for the model argument, which is genuinely useful. However, it never states when to prefer this over generate_epw or generate_forecast, nor any prerequisites such as needing a valid api_key with credits available.

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 information the annotations do not carry: a cost of '1 credit' and a minimum 5-year input window. Annotations already declare readOnlyHint=false, idempotentHint=false, and openWorldHint=true, but the description omits whether the call runs synchronously or returns a job handle requiring get_job_result, which is a meaningful behavioral gap for an open-world generator.

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 short sentences with the resource, the key constraint, and the cost front-loaded. No filler or redundant restatement of the tool name.

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 7-parameter, 5-required generation tool with zero schema descriptions, the definition leaves too much unstated: the required api_key, what dc_edition controls, and whether the call is asynchronous. An output schema exists, so return values need no explanation, but input-side and job-flow completeness are lacking.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% across 7 parameters, so the description must carry the burden and it largely does not. Only start_year/end_year semantics are hinted at ('chosen period', 5-year minimum); lat, lon, api_key, dc_edition, and location_name are given no explanation anywhere.

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?

Names a specific resource (typical meteorological year) and action (generate from a chosen period), so an agent understands the output artifact. It does not distinguish itself from siblings like generate_epw or generate_future_climate, which also produce weather data for a location.

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 parenthetical '(at least 5 years; 10-20 is usual)' gives a real eligibility constraint on the input period, which is genuine usage guidance. However, there is no statement of when to prefer this over generate_epw, generate_forecast, or generate_future_climate, and no prerequisites (e.g., API key requirements) are mentioned.

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/non-destructive, and the description adds genuinely new behavioral facts: the ~0.25 degC validation accuracy against published tables, the 90% tested range for Enhanced, the 1-credit cost of the DDY file via web or API, and that the two modes are never mixed. Cost and accuracy disclosures are exactly the kind of context annotations cannot carry.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the one-line summary, then a per-mode block, so an agent can read only as far as it needs. A few phrases are slightly redundant ('not the ASHRAE method', 'that are never mixed') but the density of useful facts per sentence is high.

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 described, and the two modes plus cost are well covered. The gaps are the undocumented current_climate flag and location_name, plus no note on units or how the result differs from get_nearest_stations output for the same coordinates.

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 0% schema description coverage the description must carry the load, and it does for the two most consequential parameters: mode is explained in depth for both values, and the full edition list (2025, 2021, 2017, 2013, 2009, 2005) is supplied even though the schema declares no enum. However, location_name and current_climate receive no explanation at all, leaving two of six parameters undocumented anywhere.

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 resource (heating and cooling design conditions for a site) and the two distinct computation modes, which no sibling (analyze_epw, generate_tmy, get_nearest_stations) offers. An agent can immediately tell this is the design-condition lookup rather than an EPW analysis or generation 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?

Explains what each mode means — ASHRAE Ch. 14 replicated at the nearest station for a chosen edition versus EPW.tools Enhanced computed at the site for today's climate — which lets an agent pick a mode from the requirement. It stops short of an explicit 'use mode X when you need Y' statement and never mentions when to prefer siblings like get_nearest_stations or analyze_epw.

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, so the safety profile is covered. The description adds that completed jobs expose download URLs, which is useful, but it says nothing about pending/failed states, result expiry, or what the trailing remark about the key means.

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?

It is a single front-loaded sentence with no filler. The parenthetical about the key is the only awkward element, reading as an afterthought rather than a clear statement.

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 described, and annotations cover safety. What is missing for a polling tool is lifecycle guidance: intermediate states, failure handling, and retrieval cadence, which an agent needs to use it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must carry the parameter burden, and it largely does not. The job_id comes implicitly from a generate_* tool, but neither parameter is explained, and 'they carry the key' is too cryptic to clarify why api_key is required separately.

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 resource and action: it reports the status of a job that was started by a generate_* tool, and it says download URLs appear on completion. The reference to the generate_* family distinguishes it from siblings such as get_design_conditions or list_cmip6_models.

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?

Usage is implied rather than stated: an agent infers it should call this after a generate_* tool returns a job id. There is no explicit guidance on when to stop polling, how often to poll, or what to do if the job fails.

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 readOnly, idempotent, openWorld and non-destructive, so the bar is lower. The description still adds real context beyond them: "Free, no key" tells the agent no authentication is required, and the parenthetical previews the payload contents. It does not mention network latency, failure behavior when no stations exist, or distance units.

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 compact fragments, front-loaded with the core capability and no filler. The telegraphed style ("Free, no key.") trades a little readability for density but wastes no 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?

An output schema exists, so return values need not be explained, and the annotations carry the safety profile. What remains missing for a spatial lookup tool is coordinate format/units, the meaning of `n`, and behavior on empty results — enough gaps to keep it at minimum viable.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% and the description never mentions any of the three parameters. It does not state that lat/lon are decimal degrees or WGS84, nor what the `n` result limit controls or that it defaults to 5, so the description fails to compensate for the undocumented 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?

"Nearest weather stations to a point" names a specific resource and spatial scope, and the parenthetical enumerates the returned fields (name, WMO id, distance, years of record). It is clearly distinct from the generation/analysis siblings (generate_epw, analyze_epw), though it never explicitly says so.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no statement of when to call this versus the sibling tools, nor any prerequisite or follow-up guidance (e.g., use this to find a station before calling generate_epw). Usage is only inferable from the purpose sentence itself.

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 annotations already declare readOnly, idempotent, non-destructive and open-world, so the safety profile is covered. The description adds behavior-relevant facts beyond that: spatial resolution per family, that regional data is Europe-only with explicit lat/lon bounds, and that the call is "Free" (no quota/cost). It does not describe ordering of results, but that is a minor omission given the 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?

A single dense sentence with no filler; the purpose and the two model families are front-loaded. The coordinate bounds and resolution values are terse but each earns its place for a geospatial lookup. Slightly compressed phrasing ("27-72 N / 25 W-45 E" without degree markers) costs a little readability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter, read-only discovery tool with a full output schema and rich annotations, the description supplies exactly the missing domain context: what the two categories mean, their resolution, and their spatial limits. An agent can decide whether this tool serves its region and how to use the returned ids without further information.

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, so the baseline is 4 and no parameter explanation is required. The description instead spends its words on the shape of the returned categories (`models` vs `regional`) and their geographic limits, which is a reasonable substitute.

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 precisely what the tool returns: available models for future-climate morphing, split into global CMIP6 models (NASA NEX-GDDP, 25 km) and regional EURO-CORDEX pairs (12.5 km). It implicitly distinguishes the two model families and their intended consumer (`model` ids). It stops short of an explicit verb ("list") or naming the sibling that consumes the ids (generate_future_climate), so sibling differentiation is implied rather than stated.

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?

Usage is implied by "available for future-climate morphing" and "usable as `model` ids," which hints this is a lookup step feeding generate_future_climate. There is no explicit when-to-use statement, no mention of what to do if the desired region is outside 27-72 N / 25 W-45 E, and no comparison against other discovery tools such as get_nearest_stations.

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