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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, covering safety. The description adds value beyond that by stating the rate limit (8 requests per minute per instance) and the specific data returned (health, rate limit status, cache statistics). This is useful behavioral context that annotations do not provide. 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 compact and well-structured: first a one-line purpose, then a 'Use when' bulleted list, then a rate limit note. Every sentence earns its place – there is no fluff. Information is front-loaded, so an agent quickly understands what the tool does and when to use it.

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 health-check tool with no parameters and an output schema (which likely defines the return structure), the description covers the purpose, use cases, and rate limit. The siblings are all sufficiently different that there is no ambiguity about selection. Nothing critical is missing for an agent to decide whether and when to call this 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?

With zero parameters, the schema is trivially complete (100% coverage). The baseline for 0 params is 4, and the description adds no parameter-related meaning because none is needed. The description's mention of what is returned (health, rate limit, cache stats) provides context that would indirectly help understand any potential future parameters, but for now it's appropriately handled.

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: 'Get server health, rate limit status, and cache statistics.' This distinguishes it from all siblings, which deal with statistics, subject areas, metadata, and queries – none of which match a health check. The purpose is unambiguous and immediately actionable.

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?

Explicit 'Use when:' list with three concrete triggers: queries failing/slow, needing to check remaining API quota, and debugging connection issues. This gives an agent clear conditions for invocation. While it doesn't explicitly say when not to use it, the context is specific enough that misuse is unlikely, and the distinct scope of siblings implicitly excludes alternatives.

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=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: it explains that variable codes are table-specific and version-stamped, that value codes can be numerous (300+), and that includeAllValues defaults to showing only the first 20. This goes beyond what annotations provide.

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 with a clear opening sentence, a bulleted list of what the output shows, and a concrete example. It's slightly longer than strictly necessary but every section earns its place by conveying critical usage information. The 'REQUIRED before querying' callout is front-loaded and effective.

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 is complete for a read-only metadata tool. It explains the purpose, the prerequisite relationship to query_table, the nature of the output (codes, values, required/optional), and the scale of data. The output schema exists, so return values don't need to be described in detail. The only minor gap is not explaining what 'total possible data combinations' means precisely, but this is a minor omission given the overall completeness.

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 all three parameters (tableId, language, includeAllValues). The description adds context about the meaning of the output (variable codes, value codes) and the scale of values, but doesn't add much parameter-specific detail beyond the schema. Baseline 3 is appropriate.

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 the tool's purpose: retrieving table structure including variable codes, value codes, required vs optional variables, and data combinations. It explicitly distinguishes itself from query_table by positioning this as the prerequisite step before querying. The verb 'get' plus the specific resource 'table metadata/structure' is unambiguous.

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 explicitly says this is REQUIRED before querying, and instructs the agent to use query_table afterward with the exact codes from this output. It also warns against assuming or reusing codes from another table, providing clear when-to-use guidance and routing to the correct sibling 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?

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.

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

Annotations already cover the read-only, idempotent, and non-destructive profile. The description adds useful behavioral context by promising the complete set ('all 149') and giving representative codes and labels. It doesn't mention ordering or language-dependent output, but that is less critical given the 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?

The core message is front-loaded in the first sentence, the examples earn their place by making return values concrete, and the last sentence is actionable. There is no filler or repetition.

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, parameterless, read-only list operation with an output schema and complete parameter docs, the description covers purpose, when to use it, and what to do next. Nothing required to invoke it correctly 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 only parameter, language, is fully documented in the input schema with enum values, default, and meaning. The description adds no parameter-level guidance, so it stays at the baseline expected when schema description coverage is high.

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?

Opens with a specific verb and resource: 'List all 149 subject areas (topics) in StatFin database.' The topic examples make the resource concrete, and the final sentence distinguishes it from list_tables, so an agent can clearly tell what this tool produces.

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?

Explicitly states when to use it: 'when you don't have a specific search term,' and gives a clear next step to list_tables. It doesn't name search_statistics as the counterpart for specific queries, but the contextual cue is strong enough to guide selection.

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, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is well covered. The description adds useful context about typical table volume and data views, but it does not disclose further behavioral traits such as response size limits, pagination, or result variability.

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 front-loaded with a one-sentence definition, followed by compact bullets and a short routing note. Every sentence contributes useful information, and there is no redundant restatement of the schema or title.

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 two-parameter read-only tool with full schema coverage, an output schema, and strong sibling guidance, the description is complete. It explains how to discover the required argument, what kind of content to expect, and when to choose an alternative 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 description coverage is 100%, so the baseline is 3. The description adds real value beyond the schema by mapping example subject-area IDs to content ('population tables', 'employment tables', 'housing price tables') and expected table counts, making the required subjectArea parameter more meaningful to an agent.

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: 'List all statistical tables within a subject area.' It also distinguishes itself from siblings by naming list_subject_areas and search_statistics and clarifying that the scope is subject-area-based, not a general 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?

Explicitly tells the agent when to use this tool versus alternatives: 'Use list_subject_areas first to find the area ID, or use search_statistics for direct search.' It also gives concrete subject-area examples with expected table counts, which helps the agent decide whether this is the right entry point.

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 behavior, lowering the burden. The description adds useful behavioral context beyond annotations: the 'all' filter can return large datasets, variable codes are table-specific, and the example shows how selections are structured. It does not contradict 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 long but every section earns its place: purpose, workflow, selection-type semantics, a concrete example, and critical warnings. It is front-loaded with the core action and workflow, and the example is highly instructive rather than 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?

Given the tool's complexity, the 100% schema coverage, and the presence of an output schema, the description is complete. It covers the required workflow, selection semantics, the need for table-specific codes, and caution around large result sets. Nothing essential for an agent to call this tool correctly 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?

Schema description coverage is 100%, so the baseline is 3, but the description adds significant meaning beyond the schema by explaining the three selection types with concrete examples and emphasizing value codes over labels. The example JSON demonstrates exactly how to populate selections, which is valuable for correct invocation.

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 the tool executes a query to retrieve actual statistical data from a table, using a specific verb and resource. It also positions the tool within a workflow (search_statistics → get_table_metadata → query_table), which differentiates it from sibling tools like search_statistics and get_table_metadata.

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 WORKFLOW line explicitly places query_table as the final step after search_statistics and get_table_metadata, giving clear sequencing. The description also warns to read variable codes from get_table_metadata first and never reuse codes, but it does not explicitly state when not to use query_table or name alternative tools for other needs.

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 destructiveHint=false. The description adds useful behavior beyond that: results are ranked by relevance, return fields are enumerated, and Finnish terms often work better. This gives the agent realistic expectations about search behavior without contradicting 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 most important instruction: 'USE THIS FIRST.' Every section earns its place: the one-line purpose, usage priority, examples, return fields, and next-step workflow. No filler or redundancy.

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, the description covers the essential agent workflow: search, interpret results, and proceed to metadata before querying. The output schema exists to document return structure, and the description still enumerates key return fields. Nothing critical is missing for correct invocation.

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 all three parameters. The description adds examples and notes about Finnish terms, but those complement rather than substantially extend the schema. Baseline 3 is appropriate.

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: 'Search Statistics Finland's StatFin database for statistical tables by keyword.' It also differentiates the tool from siblings by emphasizing keyword search and ranked results, which is distinct from list_tables, list_subject_areas, or query_table.

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 contextual guidance: 'USE THIS FIRST when looking for data.' It also provides a follow-up workflow: use get_table_metadata before querying. However, it does not explicitly state when not to use this tool or compare it against list_tables and list_subject_areas, so it stops short of full when/when-not coverage.

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