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

Annotations already declare readOnlyHint=true and idempotentHint=true, but the description adds valuable context beyond annotations: it discloses the mode field in the result, that error/hint are set on failure, and that theme mode returns dataset counts and theme metadata. It does not cover rate limits or auth, but that is not expected for a read-only catalog browse.

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 two-sentence intro, a clear two-mode breakdown, a compact Args list, and a Returns note. Every sentence serves a purpose; no fluff or redundancy. It is concise without sacrificing detail.

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 is moderately complex (two modes), and the description fully covers both modes, the output shape (themes vs tables), and error handling. With an output schema present, the description need not explain return types in more detail, but it already covers them sufficiently.

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?

Even though the signal says schema description coverage is 0%, the description fully explains all three parameters in the docstring: theme_code (2-digit code, omit for themes), lang (language codes), and limit (max tables). It also gives concrete examples ('15' for Bildung). This compensates for any schema gaps and adds practical 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 opens with a specific verb and resource: 'Browse the BFS catalogue: the theme list, or the datasets within a theme.' It clearly distinguishes two modes and names downstream tools (bfs_get_table_metadata, bfs_get_data), which differentiates it from sibling tools like bfs_search_tables.

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?

Usage is explicit: 'Omit theme_code → list all 21 statistical themes... Provide theme_code → list the datasets in that theme.' It also states the purpose of the output ('to feed bfs_get_table_metadata / bfs_get_data'), giving clear when-to-use guidance and naming 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 indicate readOnlyHint=true and idempotentHint=true. The description adds that it fetches data simultaneously for multiple cantons and returns JSON. This adds useful behavioral context 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 a single paragraph with an integrated example. It states the purpose upfront and every sentence adds information. No wasted words.

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 moderate complexity and the presence of annotations (read-only, idempotent), the description covers purpose, parameters, usage, and ties to sibling tools. It lacks mention of error handling or response structure, but an output schema is likely provided.

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 provides descriptions for each parameter, but the description adds value by explaining canton code meanings (e.g., '0' for Switzerland total) and including a concrete example in the use case.

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 first sentence clearly states 'Compare a BFS statistical indicator across multiple Swiss cantons', providing a specific verb (compare) and resource (BFS indicator across cantons). This distinguishes it from sibling tools like bfs_get_data which is likely for single-canton queries.

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 a usage context: 'Designed for KI-Fachgruppe demos and benchmarking', and provides an example use case. It also instructs to get canton codes via bfs_get_table_metadata. However, it does not explicitly contrast with alternatives like bfs_get_data for single cantons.

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 read-only, idempotent, and non-destructive behavior. The description adds valuable context beyond annotations: it returns a per-year series with specific fields, is based on official consolidated data, and sets error/hint fields on failure.

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 one-line purpose, a clarifying note about alternatives, an Args section, and a Returns section. Every sentence adds value, and it is appropriately sized for the tool's complexity.

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 rich annotations and output schema, the description is complete: it explains the temporal scope, the one-commune focus, the relationship to an overlapping source, and the expected result shape. Error handling is also disclosed.

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?

Although the schema includes detailed nested descriptions, the context signal reports 0% top-level schema description coverage. The description compensates with explicit Args bullets for municipality_bfs (including an example) and since_year (inclusive, default 2015), giving agents enough semantic grounding.

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 precise verb+resource statement: 'Yearly new buildings and new dwellings for a commune, with room-size mix.' It names the exact BFS data cubes and clarifies that this is the consolidated official yearly statistic, distinguishing it from related construction and pipeline 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 explicitly states when to use this tool: 'this is the *consolidated official yearly* statistic.' It also gives a clear when-not and alternative: 'For up-to-date building-register states and the construction pipeline (Baugesuche / Bauvorhaben), see the swiss-housing-mcp server.'

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 convey read-only, idempotent, non-destructive behavior. The description adds valuable context: output units in 1000 CHF, the per-year series format, the leading-indicator meaning, and error/hint fields. 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 structured with logical sections (overview, args, returns) and every sentence contributes meaning. It is slightly wordy but not bloated, earning a high but not perfect score for conciseness.

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 covers the data source, return series, units, and error behavior. Since an output schema exists, it need not explain returns in detail, but doing so adds completeness. Overall, the tool is fully contextualized for an agent.

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?

Even though the schema has detailed descriptions, the tool description includes an Args section covering all parameters (level, code, since_year) with examples and default value. This fully compensates for the low reported schema description coverage and gives clear guidance on how each parameter should be used.

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 yearly building investment and Arbeitsvorrat for a region/canton/commune, naming the specific BFS STAT-TAB data source. This specific verb+resource combination distinguishes it from siblings like bfs_get_data or bfs_construction_activity.

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 explains the purpose and highlights the Arbeitsvorrat as a leading indicator, giving a clear context for when the tool is useful. However, it does not explicitly mention when not to use it or name alternative 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?

The description aligns with annotations (readOnlyHint=true, etc.) and adds detail on return format (DataTableResult with topic, canton_filter, error/hint fields). No contradictions, and it elaborates on parameter effects.

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 concise and well-structured with Args/Returns sections, front-loaded purpose, and no unnecessary words.

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 rich input schema, annotations, and presence of an output schema, the description covers all essential aspects: purpose, parameters, return shape, and error handling.

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 descriptions already cover all three parameters. The description restates them but adds little new beyond the schema. High schema coverage sets baseline at 3.

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 explicitly states it retrieves Swiss education statistics as a convenience tool for the Schulamt context, listing specific topics (teachers, students, scenarios, scholarships) and filtering by canton. It differentiates from siblings like bfs_get_data by noting no need for table IDs.

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 clearly indicates this is for common education topics without table IDs, implying use over bfs_get_data. However, it does not explicitly state when not to use it or provide alternative tool names.

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, destructiveHint, idempotentHint, and openWorldHint. The description adds valuable behavioral context by noting the tool returns a curated shortlist with recommended use cases and specific output fields, which goes beyond the 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 succinct with front-loaded primary purpose, followed by contextual details and a minimal Args section. No redundant sentences; every part contributes to understanding.

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 has only one parameter, rich annotations, and an output schema, the description adequately covers usage context (target audience, use cases, output contents) without needing to detail return values.

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 should compensate. However, it only restates 'lang (str): Language code' without adding value beyond the schema's already detailed description (default, pattern, allowed values). This fails to provide additional 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 states the verb 'Return' and the resource 'curated list of high-value BFS datasets' targeted at Schulamt and public administration. It differentiates from siblings like bfs_list_tables_by_theme by emphasizing curation and high-value selection.

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 specifies when to use the tool: as a starting point for education planning, demographic analysis, and political context. It does not provide explicit when-not or alternative tools, but the context from sibling names implies appropriate 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 provide readOnlyHint=true and destructiveHint=false, so the description's claim of querying data is consistent. The description adds behavioral context about the safety limit max_rows and the potential for large datasets when no filters are applied. It also describes error handling in the return (error and hint fields). This fills gaps beyond 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 concise and well-structured: a clear purpose statement, a critical prerequisite, and then a bullet-point list of parameters with their roles. Every sentence adds value, and the most important information (what the tool does and the precondition) is front-loaded. There is no unnecessary verbosity.

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 that an output schema exists (DataTableResult), the description does not need to detail return values, but it does mention key fields (dimensions, rows, truncated, etc.). It covers prerequisites, filtering, language, and safety limits. The tool is a simple query with clear inputs and outputs, and the description addresses all relevant aspects.

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 provides detailed descriptions for each parameter (table_id, filters, lang, max_rows), so the description's summary in Args adds only marginal value. The description does include practical examples (e.g., '['1', '2'] for Zürich and Bern') in the schema itself, but the tool description restates key points concisely. Since schema coverage is high, the description does not significantly enhance parameter 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 queries statistical data from a BFS table with optional filters, distinguishing it from sibling tools like bfs_get_table_metadata (which fetches metadata) and bfs_search_tables (which searches for tables). The verb 'Query' and resource 'data values from a STAT-TAB table' are specific and 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 advises calling bfs_get_table_metadata first to understand available variables and values, which is a clear prerequisite. It also notes that without filters, all data is returned (may be very large), implying when to use filters. However, it does not explicitly state when not to use this tool or list alternatives, but the context is sufficient.

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 and idempotent behavior. The description adds valuable context about the return format (JSON with title, source, update date, variables with codes and value options) and provides an example output structure. This goes 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 well-structured with clear sections: purpose, workflow position, args, returns, and example. The purpose is front-loaded. The Args section duplicates schema descriptions, slightly bloating length, but the overall structure and example justify the size.

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 covers purpose, when to use, return structure, and example output. It does not mention error cases or size limitations, but the output schema (present) and annotations reduce the need for such details. It is sufficiently complete for an agent to 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 description's Args section restates the schema's parameter info (table_id and lang) with no additional semantic depth. The example ID and language codes already exist in the schema. With schema description coverage at 0%, the description fails to compensate by offering new meaning or richer explanations.

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 'Get metadata for a BFS table: title, variables, and available filter values,' using a specific verb and resource. It also distinguishes itself from siblings by positioning as an 'Essential step before calling bfs_get_data,' making it distinct from data retrieval and search/browse 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 explicitly says 'Essential step before calling bfs_get_data,' giving clear when-to-use context within the BFS workflow. It does not explicitly mention alternatives or when not to use, but the reference to bfs_get_data implies the intended usage pattern.

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 indicate readOnlyHint, destructiveHint, idempotentHint. Description adds context about 'flexible filtering' and dataset source, but does not disclose behavioral traits beyond what annotations provide. 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?

Description is front-loaded with main purpose, followed by details in a structured Args/Returns format. Every sentence adds value; no unnecessary words.

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 has an output schema and the description covers parameters, return type, and use case, it is complete for an agent to select and invoke 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?

Despite schema description coverage of 0%, the description includes an Args section that explains each parameter (region, year, breakdown) with types and examples. This compensates for the missing schema descriptions, though it could be more detailed on year format.

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?

Description clearly states it retrieves Swiss population statistics by region, year, and breakdown. It mentions the specific dataset and use cases (school space planning), distinguishing it from siblings like bfs_compare_cantons or bfs_education_stats.

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?

Description implies usage for demographic projections, but does not explicitly state when not to use or compare to alternatives like bfs_compare_cantons. No exclusions or conditions provided.

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 the tool read-only, idempotent, and non-destructive. The description adds substantial context: data flows via opendata.swiss (CKAN), default user agents are rejected (403) requiring a custom UA, results are cached 24h, and IMPI returns only source links due to publication format. It also notes error handling, exceeding the annotation coverage.

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-organized with a short intro, bullet points for each index, a note on data flow, and clear Args/Returns sections. Every sentence provides distinct value, and the structure makes it easy to scan.

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 one input object and an output schema, the description fully explains the two operational modes, return types, caching behavior, and error handling. Combined with the existing annotations and output schema, the description is complete for an agent 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 schema already provides descriptions for `index` and `since_year`, covering accepted values and meaning. The description's Args section largely repeats this information, adding little beyond the schema. Since schema coverage for the nested parameters is strong, a baseline of 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 immediately identifies the tool's purpose: providing Swiss price indices (Baupreisindex and IMPI) not available in STAT-TAB. It clearly distinguishes between the two index variants and explains what each returns, setting it apart from sibling tools that handle tables, metadata, or other construction statistics.

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 a clear scope ('not carried by STAT-TAB') and distinguishes between the two index modes, including the IMPI limitation (PDF/HTML only). However, it does not explicitly mention alternatives or when not to use this tool, though the scope implies when it is appropriate.

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 indicate readOnlyHint=true and destructiveHint=false. The description adds valuable context: first call makes ~682 API requests, subsequent calls within 1 hour are instant, and error handling behavior (error and hint fields). Does not mention potential rate limits or result size.

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?

Well-structured with clear sections: purpose, details, caching note, parameter listing, and return info. Every sentence is informative. Front-loaded with purpose.

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?

Complete for a search tool with an output schema. Covers purpose, parameters, caching, and error handling. Mentions that results include table IDs for other tools, which aids in task chaining.

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?

Description provides explicit parameter explanations, including examples for query (e.g., 'Lehrkräfte'), description of theme_code filter, lang, and limit. This adds significant value beyond the schema's descriptions, even though schema has descriptions. The examples help understand usage.

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?

Clearly states it searches BFS statistical tables by keyword in titles, distinguishing from sibling tools like bfs_list_tables_by_theme. Mentions relevance to downstream tools (bfs_get_table_metadata, bfs_get_data).

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?

Explains that it performs full-text search across all tables and describes caching behavior (first call slow, subsequent instant). Implicitly guides when to use for keyword-based search, but doesn't explicitly contrast with other search tools or mention exclusions.

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?

Adds meaningful behavior beyond annotations: explains how canton membership is derived from the Parent chain, states sorting by BFS number, and discloses error/hint fields. No contradiction with readOnly/idempotent/destructive hints.

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?

Purpose is front-loaded in first sentence; the remaining sentences explain derivation, output fields, params, and return behavior in a compact structured Args/Returns layout. 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?

For a list tool with output schema and readOnly annotations, the description covers scope, date semantics, output sorting, and error behavior. It is self-sufficient 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?

With schema coverage at 0%, the description compensates by documenting both params: canton accepts abbreviation or name with examples, and valid_at_date is ISO date defaulting to today. It adds practical format details beyond bare property names.

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?

Description opens with a specific verb+resource ('List all communes of a canton, as of a given date') and specifies output contents (BFS number, LINDAS URI). It clearly distinguishes from sibling single-commune/table tools by emphasizing 'all communes' and official division by date.

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 clear context: use when you need all communes for a canton at a specific date, with membership based on the snapshot's Parent chain. It does not explicitly name alternatives/exclusions, so not a 5, but it gives enough context for appropriate 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?

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds valuable behavioral context: it specifies the exact return fields (BFS number, canton, validity, LINDAS URI), explains the date-sensitive state of the commune, and discloses error handling (error and hint fields are set). This goes beyond the annotations to clarify expected outputs and failure modes.

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 an opening purpose statement, a brief context paragraph, and clearly labeled Args/Returns sections. While slightly verbose with the join key explanation, every sentence contributes meaningful context. It is front-loaded with the main purpose and easy to scan.

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 simplicity, the presence of an output schema, and strong annotations, the description covers all necessary aspects: what it does, key parameters, return structure, and error behavior. It is complete enough for an agent to understand when and how to use it without further documentation.

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 provides rich descriptions for both parameters, including examples and matching behavior for name_or_bfs_number and the ISO date format for valid_at_date. The description's Args section merely repeats this information without adding new semantic depth, so it adds little 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 opens with a specific verb and resource: 'Resolve a Swiss commune by name or BFS number, as of a given date.' It clearly states the tool's scope and output (official register entry with BFS number, name, canton, validity, LINDAS URI), distinguishing it from siblings like list_communes or resolve_historical_commune by emphasizing temporal resolution and the portfolio's join key.

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 contextual hints—'as of a given date' and 'portfolio's join key'—but does not explicitly state when to use this tool over alternatives like resolve_historical_commune or list_communes. There are no stated exclusions or alternative naming, so the usage guidance is only implied, not explicit.

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, destructiveHint=false, and the description adds meaningful behavioral context: it returns a mutation path (fusions/renamings with dates), resolves to today's BFS number/name/LINDAS URI, and provides error/hint fields. This goes beyond the annotations and clarifies the tool's behavior accurately.

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, purpose elaboration, and Args/Returns sections. It is slightly verbose with phrases like 'core value of the reference layer' but each sentence contributes useful context. The front-loaded summary is strong, making it easy to scan.

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 relatively specialized historical resolution tool, the description covers the core use case, the output structure (resolves_to and mutation_path), error handling, and how to apply it for re-keying. Combined with the output schema, the description is complete and sufficient for an agent to select and invoke this 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 provides detailed descriptions for all three parameters (bfs_number, from_date, to_date) including examples and constraints. The description's Args section repeats this information without adding much new semantic value. Since schema coverage is high, the baseline is 3; the description doesn't significantly enhance parameter 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 begins with a specific verb 'Map a historical BFS commune number onto today's number(s)', clearly identifying the resource (historical commune numbers) and the action (mapping to current numbers). It also distinguishes itself from siblings by focusing on mutation paths and re-keying old statistics, which is unique among the listed 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 provides clear usage context: 'when old statistics are keyed on a BFS number that has since been merged or renamed'. It explains the use case for re-keying old figures. However, it doesn't explicitly list when not to use this tool or mention alternative sibling tools like search_historical_series or lookup_commune, so it lacks explicit exclusions/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. The description goes beyond this by disclosing the licence (CC BY-NC-SA 3.0), that every response includes a licence notice, and that the period parameter is informational only because HSSO does not support per-table filtering. It also notes the error/ hint fields, adding useful behavioral detail.

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 front-loaded purpose, a brief resource context, licence notice, and an Args/Returns layout. Every sentence contributes necessary information without redundancy or 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 description provides complete context for a read-only search tool: resource, input semantics, output shape, error behavior, and licensing. Since an output schema exists, the return values need not be exhaustively described, and the description covers all other relevant aspects adequately.

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?

Context reports schema description coverage at 0%, so the description must compensate. It explains that topic is a keyword that all must match the title, and that period is optional and informational only. This is sufficient semantic guidance even though the nested schema actually contains detailed descriptions; the description adds compact, accessible meaning for the 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?

The description opens with a specific verb-resource-scope statement: 'Search long-run historical time series (HSSO) by topic.' It clearly distinguishes this tool from the BFS sibling tools by focusing on HSSO's static XLSX table catalogue, and it states what is returned (page and XLSX URL). No ambiguity about the tool's purpose.

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 clear context by explaining that this searches the HSSO catalogue of long-run 19th–20th century series, which distinguishes it from BFS-oriented siblings. It does not explicitly name alternatives or state when not to use it, but the resource scope ('Historical Statistics of Switzerland', 'HSSO') makes the usage context evident.

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