get_emissions_series

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

With no annotations, the description carries the burden. It discloses non-obvious behavior: avoids certain variants (TREND/BASE_YEAR_AVG/PREV_SUBMISSION), sorts client-side by year, and restricts accounting_scope to totals. These are valuable insights beyond 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?

The description is well-structured: a leading high-level summary followed by parameter-specific guidance and a behavioral note. Every sentence adds value, and the warning about not summing sectors is a critical, concise inclusion. No fluff.

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 tool has 6 parameters and an output schema, so return values are covered. The description explains the domain-critical specifics (curation rules, sector codes, accounting scope) and points to the sibling tool for sector discovery. It is sufficient for an agent to select and invoke correctly, though a bit more detail on gas values could complete it.

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

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

Schema description coverage is 0%, so the description must compensate. It adds meaning for the key parameters: country format (ISO-style Discodata codes), sector hierarchy and valid depths, and accounting_scope options. It omits gas/start_year/end_year, but those are self-explanatory from names and defaults.

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 curated national GHG inventory time series. The 'statistically correct variable' phrasing is somewhat opaque, but the resource and action are clear, and it distinguishes itself from sibling data access tools by highlighting the curated nature.

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?

Provides concrete usage guidance: how to discover sector codes via search_emission_sectors, warnings against summing sectors with parents/children, and clarifying that accounting_scope applies to totals only. This gives the agent context on when and how to use the tool, though it doesn't explicitly contrast with alternatives beyond the sector discovery hint.

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