carbon-fyi

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds meaningful behavioral context beyond this: it warns that the two price sources are NOT comparable and directs attention to the caveats field, which is important for correct interpretation of results.

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 two sentences with no filler. The main subject and data provenance are front-loaded, and the crucial caveat about non-comparability is placed prominently. Every sentence contributes essential 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 no-parameter, read-only tool without an output schema, the description covers the key data categories returned (per-category price/supply and per-class spot prices) and warns about interpretation. It does not spell out exact field names or units, but the caveat pointer and source breakdown provide sufficient operational context.

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 has zero parameters, so the baseline of 4 applies. The description appropriately focuses on data semantics and caveats rather than inputs; there are no parameter ambiguities to resolve.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb-resource pair: getting current voluntary carbon credit prices, and uniquely identifies the two data sources (Carbonmark marketplace and Klima Protocol). It clearly distinguishes this from siblings like get_price_history by specifying 'current' prices and from get_market_summary by focusing on prices rather than summary metrics.

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 clear context: use for current voluntary carbon credit prices, and it emphasizes the need to consult caveats before using the numbers. It does not explicitly name alternative tools or when-not-to-use conditions, but its 'current' and 'two sources' framing makes appropriate usage inferable.

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 readOnlyHint and openWorldHint annotations already communicate that this is a safe, read-only call in an open world, so the description's main job is to add context. It does add content and cross-tool coupling, but it does not disclose any additional behavioral traits such as staleness, rate limits, or response-shape caveats.

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 that starts with the key idea ('One call for orientation') and then presents a scannable list of contents. The final 'Start here.' is short, purposeful guidance with no filler.

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

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

With no parameters, no output schema, and annotations covering safety, the description carries the full burden of explaining what the agent will get and when to use it. It explains all major output categories and links the story tags to search_news, making the call actionable end to end.

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 has zero parameters and an empty input schema, so there is no parameter semantic burcen. The 0-parameter baseline of 4 applies; the description appropriately focuses on what the output contains instead.

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 ('One call for orientation') and enumerates the exact contents: archive availability, last updated, story-tag breakdown, and current price table. This distinguishes it from sibling tools like get_price_history or search_news by describing a cross-cutting summary rather than a targeted retrieval.

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?

'Start here' explicitly tells the agent when to make this call, and the note to use its story tags as tag values for search_news gives concrete follow-up guidance. It does not spell out when not to use each sibling, but the orientation framing provides clear usage context.

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 substantial behavioral context beyond the read-only annotation: the archive is populated three times a day, the series is daily-averaged, the archive starts on 2026-08-27, and callers should check seriesStartsAt because early windows are short. This discloses data limitations and response expectations that annotations alone do not convey.

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 compact and front-loaded with the core definition, followed by rationale and an operational caution. Each sentence earns its place with no filler or repetition of schema 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?

For a tool with no output schema, it usefully reveals the response contains seriesStartsAt and that returned windows can be short. It could go further by describing the shape of the observations themselves, but the essentials for invoking and interpreting the archive are present.

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 key, days, and kind thoroughly. The description itself adds only contextual value about daily averaging and archive start date, not new parameter-level meaning.

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 resource as a daily-averaged historical carbon price series and marks it as unique because it cannot be re-derived or obtained elsewhere. It lacks an explicit imperative verb in prose, but the tool name plus the noun-phrase makes the action unambiguous and distinguishes it from the current-price sibling tools.

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

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

The description implies when to use it – whenever a historical carbon price series is needed, since no upstream API provides one. However, it does not explicitly state when not to use it or name an alternative such as get_carbon_prices for current prices.

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 readOnlyHint annotation already establishes that this is a safe read operation. The description goes further by disclosing that the response includes every source for the story, and that story IDs and public URLs are permanent, making IDs safe to store. These are genuinely useful behavioral details beyond the annotations, 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 two sentences: the first front-loads the action and scope, the second adds valuable durability information. Every sentence earns its place, and there is no redundant filler.

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

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

For a one-parameter, read-only lookup tool with no output schema, the definition is complete enough. It specifies what is returned (a story plus all sources), how the id is obtained (schema reference to search_news), and why the id is safe to persist. An agent has what it needs 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 documents the single id parameter thoroughly, including its source ('as returned by search_news'), type, and length constraints. With 100% schema description coverage, the description does not need to add parameter-level detail, and it does not add any 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 a specific verb ('Fetch'), a specific resource ('a single story'), and the key qualifier ('by its id'). It also clarifies that the result includes every source that reported it, which distinguishes this from sibling tools like search_news or list_sources that return different shapes.

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 intended usage is clear: fetch a single story when you have its id. The schema's hint that the id comes from search_news reinforces the workflow, and the mention of permanent IDs adds useful guidance about storing and reusing IDs. However, there is no explicit comparison to alternatives or a direct statement of when not to use this tool.

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 readOnlyHint=true and openWorldHint=false. The description adds interpretative context about the closed-world nature of the list and its role in coverage judgments, which goes beyond the structured annotation fields.

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 sentence description with no wasted words. The first sentence states what the tool returns, and the second sentence explains its practical value. Highly efficient and well-structured.

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 metadata listing tool, the description fully covers what is returned and how to interpret it. No output schema exists, but the simplicity of the tool does not demand more detail.

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

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

The tool has zero parameters and the schema coverage is 100%, so there is no parameter information lacking. The description is not required to explain parameters that do not exist.

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 resource ('the publications, registries and integrity bodies carbon.fyi monitors') and the operation is implied by the tool name 'list'. It is clearly differentiated from siblings, which deal with prices, summaries, history, stories, and news search.

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 concrete use case: 'Useful for judging coverage — a topic absent from the archive may simply not be covered by these sources.' This gives clear context for when to use the tool, though it does not explicitly mention alternatives or 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 establish readOnlyHint=true and openWorldHint=false. The description adds useful behavioral context: stories are editorially clustered summaries, always carry source name and URL, results are newest-first, and at least one filter is required. 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?

Three sentences pack the core purpose, data characteristics, ordering behavior, filter requirement, and a routing hint with no fillter. The most decision-relevant information is 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 search tool with well-documented parameters and no output schema, the description covers the key facts an agent needs: what is searched, what a story contains, the filter requirement, ordering, and how to discover tags/date ranges. It does not enumerate all returned fields, but enough is conveyed.

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 the schema carries most parameter meaning. The description adds the cross-parameter rule that at least one filter must be supplied, which is valuable, but it does not add individual parameter details 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 identifies a specific action and resource: searching carbon.fyi's curated voluntary carbon market story archive. It explains what a story is, but it does not explicitly distinguish this search tool from sibling get_story or list_sources, so it is clear without direct sibling differentiation.

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 context: supply at least one filter, expect newest-first results, and call get_market_summary first if tags or date range are unknown. It names an alternative for discovery but does not fully spell out when not to use this tool versus every sibling.

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