Get All Values for a Variable

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

Annotations already cover readonly/idempotent/non-destructive behavior, so the description adds value by explaining that it returns a complete list beyond the metadata's first 20. It also provides concrete behavioral context (e.g., common region codes and search filter behavior) that helps set expectations about the output. 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 well-structured and front-loaded with the core purpose first. It uses bullet points for readability and groups related information (useful cases, region codes). It is a bit longer than strictly necessary, but every sentence adds practical value—examples and codes are not filler. The structure makes it scannable for an agent.

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 value-list tool with an output schema, the description is thorough. It covers the primary use cases, gives concrete examples of how to use the search filter, and provides domain-specific knowledge (region codes, year range 1972–2024) that an agent would otherwise lack. The existence of an output schema reduces the need to describe return structure. No critical information is missing.

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 describes all parameters with 100% coverage (baseline 3). The description goes well beyond by explaining variable code patterns (e.g., 'alue_23_20260101', 'timeperiod_y'), providing common region codes (e.g., KU091, MK01), and showing the search parameter example with 'Helsinki'. This enriches the schema's bare definitions and helps the agent choose correct parameter 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 opens with a specific, actionable purpose: 'Get the complete list of values for a variable when metadata only shows first 20.' This clearly distinguishes it from metadata retrieval (get_table_metadata) which provides a truncated list. The 'Useful for' bullets further clarify the intended use cases (region codes, year lists, category codes), leaving no ambiguity about what the tool does.

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 states when to use the tool: when metadata only shows the first 20 values. This implicitly contrasts with get_table_metadata, but it does not name alternatives or explicitly say not to use other tools. It gives clear context for the typical scenarios (finding region codes, years, category codes) but lacks explicit 'when not to use' guidance or reference to sibling tools.

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