groundhog.markets

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

Annotations already cover safety (readOnly, idempotent, non-destructive, closed-world), yet the description adds real value beyond them: the required id provenance from search, the attribution obligation ('Keep the credits and link the url'), and an inline sketch of the response fields despite there being no output 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?

Two short sentences with no filler, and the core purpose leads. The phrasing of the attribution clause ('when you repeat numbers') is slightly garbled but still actionable.

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 no output schema, the description helpfully enumerates the return keys, but it does not explain what 'text' or 'metadata' contain or what happens when the id is unknown. Adequate for a one-parameter read tool, but not fully self-sufficient.

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 0% and the single 'id' property is an undescribed string, so the description must compensate. It does partially by stating the id comes from search, but gives no format, example, or failure behavior for an invalid 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?

The name 'fetch' is generic, and the description says it returns 'the 7-day forecast of a place id from search' while listing return fields {id, title, text, url, metadata} that read like a place record rather than a forecast. That internal tension leaves the actual resource ambiguous, and nothing distinguishes it from the sibling 'forecast' 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?

'a place id from search' establishes a prerequisite: the id must come from the search tool, which is genuinely useful routing. However, it never says when to use this instead of 'forecast', 'places', or 'history', so the agent has no explicit selection rule among four plausibly overlapping siblings.

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 establish readOnly, idempotent, non-destructive, non-open-world, so the safety profile is covered. The description adds genuinely useful behavior: token cost per size (~321 line, ~566 week, ~1,567 table, ~1,564 series, ~647 rain line), the credits requirement, and the page URL to cite. It does not explain error behavior or how many forecast sources are actually consulted.

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 front-loaded with what the tool returns and wastes few words, but the notation is telegraphic ('line ≈321 tok', 'size=runs:') and the second half is a dense run-on of mode variants that requires re-reading. Information density is high, but structure and readability suffer.

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 15-parameter tool with no output schema, the description does a solid job of sketching output shape and cost per size, and it flags the two major mode branches (runs and rain). Gaps remain around what 'median/spread' means across mixed sources and around several secondary parameters, but the core is covered.

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 93% schema coverage the baseline is 3, and the description earns more by explaining mode-specific semantics the schema does not: that size=runs surfaces each source's newest run with run_utc/fetched_at and that NBM additionally emits XND, P12 and Q12, and that variable=rain reports members' share of >=0.01in with n = model families. Still, several params (stn, win, credits enum values, include_6h) get no narrative elaboration.

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 opening sentence gives a concrete verb+resource: daily high/low for a place aggregated across every free forecast, plus rain, obs, alerts, credits and page URL. It is unmistakably a forecast-reading tool, but it never names a sibling to distinguish it from 'fetch' or 'history', so differentiation is left to inference.

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?

Mode selection guidance is present in fragments ('size=runs: one place, each source's newest runs by day', 'variable=rain: ...'), which tells the agent when to pick those modes. There is no statement of when to prefer this tool over fetch/history/sources, and no exclusions or prerequisites. The 'Keep the credits and link the page' line is attribution guidance, not tool-selection 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 read-only, idempotent, closed-world behavior. The description adds valuable context beyond that: the no-look-ahead guarantee, the presence of fetched_at and origin (bf:* = backfilled) in rows, and the default TSV output. This gives the agent a clear picture of the data's provenance and 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 a single dense paragraph that front-loads the core purpose and then efficiently packs parameter guidance. It is appropriately sized for a 15-parameter tool, though the heavy use of shorthand and parentheticals makes it slightly harder to parse on first read.

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 15 parameters and no output schema, the description covers the essential behavioral context: the three kinds, date-range constraints, run selection logic, and output format defaults. It does not explain all returned columns, but given the schema's completeness and the annotations, this is largely sufficient.

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, the schema already documents each parameter. The description still adds meaningful semantics: the from/to constraint (<= 366 days, 1 unit per 31 days), the run/lead/cycle/asof relationships, and the meaning of kind values. It does not repeat the schema verbatim but enhances understanding.

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 it returns 'as-issued history for backtests (no look-ahead)' and enumerates three distinct kinds (daily, nbm, obs) with their respective data. It does not explicitly differentiate itself from siblings like 'forecast', but the 'as-issued/no look-ahead' framing makes its specific niche apparent.

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 context 'for backtests' implies when to use it, and the description explains the semantics of the kind and date parameters. However, it does not explicitly say when to choose this over alternatives such as 'forecast' or 'fetch', nor does it state any exclusions or prerequisites.

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 read-only, idempotent, non-destructive behavior, while the description adds useful context: no prices, settlement/rule semantics, token estimates for line/table/all-cities output, and a fallback city-list behavior. It does not mention permissions or rate limits, but it adds behavior beyond the annotations without contradicting them.

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 leads with the resource and content, then states constraints, fallback behavior, and token-cost implications. Every clause carries operational information, including the no-prices exclusion and size-cost estimates.

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?

Because there is no output schema, the description carries the return-content burden and does so by listing the market fields and forecast values. It also explains fallback behavior and output size costs, though 'credits' remains undocumented and the exact output shape is only partially described.

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 83%, and the schema already documents enums and defaults for date, place, family, size, and format. The description adds useful meaning for place/family requirement and size token costs, but it omits the 'credits' parameter entirely and adds little detail for date/format 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 names the resource (weather markets) and enumerates the returned content: settlement station and rule, the observed number, our value, the official result, and forecast daily max/min. It also explicitly excludes prices, making the purpose specific enough to distinguish it from a generic forecast tool, though it does not directly name sibling alternatives.

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 states the key input constraint, 'Needs place or family,' and explains the fallback when neither is supplied: the list of market cities. It also ties size defaults to whether a place is provided, but it does not compare this tool with forecast/history/search or state when not to use it.

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, non-destructive behavior, and openWorldHint=false, so the safety profile is covered. The description adds that the result is a place slug and lists accepted lookup formats, but it does not explain response shape, failure behavior, or the ambiguous phrase 'says full blend or grid only'.

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 front-loaded sentence with no wasted preamble. It is almost too terse, and the trailing phrase 'says full blend or grid only' is cryptic rather than informative, but overall it remains compact.

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 simple two-parameter lookup tool with no output schema and rich safety annotations, the description covers the main query forms and result type. It is still incomplete because it omits limit semantics and leaves the final clause ambiguous, which matters when schema coverage is 0%.

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. It substantially documents the required q parameter by listing accepted formats such as name, City, ST, airport code, and lat/lon, but it never explains the optional limit parameter or its 1-10 bound.

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 a specific verb and resource: find a place slug. It also lists accepted query forms (name, City, ST, airport code, lat/lon), which makes the tool's purpose easy to distinguish from generic siblings like search or fetch. However, it does not explicitly name an alternative or clarify its relationship to those 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 no explicit when-to-use guidance, no exclusions, and no named alternatives among fetch, search, forecast, history, markets, receipts, or sources. The accepted input formats imply it is for location resolution, but an agent must infer when this tool is preferable to search.

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 read-only, idempotent, non-destructive, closed-world behavior. The description adds useful scope detail that every mismatch is included and prices are excluded, but it does not explain pagination, limits, or output structure.

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 no wasted language, and the key scope constraints are front-loaded. The 'No prices.' fragment is terse but 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?

The description conveys the basic return concept (match frequency with every miss, no prices), which partially compensates for the lack of an output schema. It still leaves important parameter semantics and output detail gaps for an audit-oriented tool.

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

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

Schema coverage is only 50%, and the description does not clarify the venue, family, days, or format parameters. The 'family' enum values (high, low, rain, all) are especially cryptic without description-level explanation.

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 identifies the resource as settle-value match results versus venue results, including misses, and 'No prices' scopes it away from price data. However, it lacks a clear action verb and the name 'receipts' is ambiguous, so the purpose is only implied rather than stated directly. Sibling differentiation is minimal beyond the price exclusion.

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 explicit guidance on when to use this tool instead of siblings like history or markets, nor any prerequisites or exclusions beyond 'No prices'. The audit/reconciliation use case is only implied by the content.

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 read-only, idempotent, closed-world behavior, so the description's main added value is disclosing the return structure ({results: [{id, title, url, text}]}) and the id-chaining contract with fetch. That is meaningful context beyond the annotations, with only minor gaps (ordering, result limits) left unstated.

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 tightly packed sentences: accepted inputs first, then return shape and the follow-up call. Nothing is redundant and the most decision-relevant information leads.

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 search tool with no output schema, the description supplies both input formats and an inline return shape, which is nearly everything an agent needs. Only edge details like empty-result behavior or result caps are omitted.

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 0% for the single 'query' parameter, so the description must carry the semantics — and it does, spelling out the four accepted input formats including lat,lon. Additional constraints such as delimiters or formatting examples for lat,lon are not specified.

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 pairs the verb "Search" with a concrete resource (places) and enumerates accepted query forms (name, City/ST, airport code, lat,lon), so an agent knows exactly what this returns. It partially differentiates from siblings by naming the follow-up 'fetch' step, though the generic tool name 'search' relies on the title for resource disambiguation.

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?

"pass an id to fetch" gives an explicit two-step usage pattern: search first, then fetch by id. It does not state when to prefer this over sibling tools such as places or markets, so the routing guidance is clear but not exhaustive.

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 provide robust operational guarantees (ReadOnly, DestructiveHint=false). The description successfully supplements this by specifying the content of the output, listing the four key attributes ('licence, latest run, age, status'), which is valuable content context for the agent.

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, concise sentence that directly lists the key information being provided. It avoids unnecessary filler while still attempting to define the scope of the data.

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?

While it adequately describes the contents of the return value (the attributes), it is slightly incomplete because it fails to specify that the tool *retrieves* or *lists* these sources, which is the necessary action.

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 is empty, resulting in 0 parameters. With 100% coverage and no input parameters to describe, the description is merely at the baseline score for parameter 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 informs the user about the attributes available ('licence, latest run, age, status') but lacks a specific action verb combined with the resource, making the purpose somewhat vague. It doesn't clearly state that the tool retrieves or lists these sources.

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?

Since there are no parameters and no alternative tools are mentioned in the context that this tool should compete against, there is zero guidance on when to invoke this tool versus its sibling tools.

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