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

Beyond annotations (read-only, idempotent, non-destructive), the description adds useful context: files are updated weekly, preview truncated at 3000 chars, and the output is raw data content.

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 tags for use_case and important_notes, but contains some redundancy (e.g., 'Useful for bulk analysis' and use_case tag). Could be slightly more concise.

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?

Covers all necessary aspects: purpose, prerequisites (list_export_files), format options, limitations (preview truncation), and example. Output schema exists, so return value details are not needed.

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 both parameters well, but the description reinforces with an example and clarifies the format default. The use_case tag adds context 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 it downloads a complete export dataset as CSV or JSON for a specific disease file, distinguishing it from siblings like list_export_files and get_disease_data by specifying the use case of bulk analysis.

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 guides when to use ('useful for bulk analysis', 'retrieve full raw dataset for offline analysis') and when not ('for very large datasets use IDD web interface'). Also directs to use bag_health_mcp__list_export_files to get valid file 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 indicate readOnly, idempotent, and non-destructive. The description adds that it aggregates several series and gracefully handles missing series (reports per-disease status instead of failure). This provides valuable behavioral context 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 well-structured with a clear main sentence, followed by a use_case block, an important_notes block, and an example. Each segment adds unique value without 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?

Given the output schema exists (not shown but present), the description need not detail return values. It covers purpose, typical usage, error handling, and provides an example. It is complete enough for the tool's complexity, though it could explicitly mention the output schema.

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 only mentions the 'canton' parameter in the example and notes it defaults to 'ZH', but does not explain the format or list valid values. The 'include_wastewater' parameter is mentioned but not explained at all. This is insufficient for a low-coverage scenario.

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 the tool gets a public health situation overview for a canton or Switzerland, combining incidence data for specific diseases (influenza, measles, etc.). It distinguishes from sibling tools by positioning itself as a one-call aggregated overview versus more granular series 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 includes a use_case tag targeting school authorities and city administration, and notes it avoids orchestrating multiple series queries. It provides an example query in German. However, it does not explicitly state when not to use it or list alternatives, but the sibling tool list and context imply its role.

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 declare readOnlyHint and destructiveHint, so safety profile is clear. The description adds beyond: return format (YYYYMMDD), weekly update cadence (Wednesdays), and that data is not real-time. No contradictions.

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 uses structured <use_case>, <important_notes>, and <example> tags for clarity. It is concise but covers purpose, usage, and a caveat. Minor improvement could remove redundancy, but overall 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?

For a simple version-check tool with no parameters and an output schema, the description fully explains what it returns, format, and update frequency. No gaps.

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 no meaningful parameters (only an empty 'params' object). With 0 parameters, baseline is 4. Description appropriately omits parameter details as none 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 states 'Get the current data version of the BAG IDD', specifying a distinct resource (data version) and action. It differentiates from sibling tools which focus on diseases, series, or indicators.

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 <use_case> tag explicitly states when to use: 'Check how fresh the data is / which weekly snapshot you are looking at.' The <important_notes> tag provides a key constraint. No explicit alternatives or exclusions, but the context is clear.

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 readOnly, idempotent, and non-destructive behavior. The description adds value by specifying data updates every Wednesday and explaining the meaning of 'incValue' (incidence per 100k) vs 'value' (absolute count), which are useful behaviors 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 concise at around 100 words, well-structured with clearly labeled sections (use_case, important_notes, example), and front-loaded with the core purpose. Every sentence adds essential information without 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 complex time-series data retrieval tool with multiple filters, the description covers data source, update frequency, metric meanings, prerequisites (call get_series_details), and provides an example. The presence of an output schema means the return format does not need to be described here, making it complete.

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 includes descriptions for all parameters (canton, sex, age_group, etc.), so the baseline is 3. The description enhances this by clarifying that 'incValue' is incidence per 100k and 'value' is absolute count, and it provides a concrete example that ties the parameters together.

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 'Fetch time-series surveillance data for a disease from the BAG IDD' with a specific verb and resource. The use_case section emphasizes it as the core data-retrieval tool, distinguishing it from siblings like bag_health_mcp__get_series_details which provides valid filters.

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 directs to call bag_health_mcp__get_series_details first for valid filters, and the use_case states the tool is for getting actual numbers/trends. While it does not explicitly list alternatives, the context from sibling names and the prerequisite hint provide clear usage guidance.

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 safe read operation (readOnlyHint, idempotentHint, destructiveHint false). Description adds behavioral details: return structure (national/cantonal, confidence intervals, dimensions), special case for suchtschweiz (HBSC aggregates), and warning that data is aggregated population statistics only, no personal data.

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 well-structured with use_case, important_notes, and example sections, front-loading core information. While slightly verbose, every section adds meaningful guidance. Could combine notes more tightly, but overall efficient.

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 complexity (6 parameters, multiple data sources, output schema exists), description covers return differences between sources, important caveats (not personal data, national-only restriction for some sources), and provides a concrete example. References sibling search tool for workflow 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?

Input schema already provides descriptions for all 6 parameters (100% coverage). Description adds value by explaining parameter behavior beyond schema: region behavior for national vs cantonal, indicator_id format guidance, and example usage. Gives practical context like year range filtering and language options.

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 uses verb 'fetch' and resource 'health indicator's time series' with explicit data sources (Obsan, Versorgungsatlas, Sucht Schweiz). Clearly distinguishes from sibling bag_health_mcp__search_health_indicators by referencing it for getting indicator_id.

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?

Includes <use_case> and <important_notes> sections that explain when to use national vs cantonal series, that obsan/suchtschweiz are national only, and that versorgungsatlas supports canton comparisons. Provides explicit guidance on using sibling search tool first.

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 and destructiveHint=false, so the safety profile is clear. The description adds behavioral context beyond annotations by noting that available dimensions vary by series, so one should always check. No contradictions.

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 XML tags for use case, important notes, and example. It is front-loaded with the core purpose. Slightly long but each part adds value.

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 parameter and an output schema, the description covers all relevant aspects: what it returns, when to use it, and an example. It also warns about varying dimensions. Completeness is high.

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 single parameter series_id has a description in the schema that explains the format and suggests using list_series to discover IDs. The description reinforces this and provides an example. Although the schema description coverage metric is 0% for top-level params, the nested description and the tool description together add 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 it gets metadata and available filter values for a specific data series. It distinguishes from sibling tool bag_health_mcp__get_disease_data by noting it should be called first to know valid filter options.

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 says 'Always call this before bag_health_mcp__get_disease_data to know valid filter options.' Also provides a use case, important notes, and an example, giving clear guidance on when and how to use.

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, openWorldHint, idempotentHint, and destructiveHint. The description adds context about output grouping but does not contradict annotations. Additional behavioral detail (e.g., no side effects) is already covered.

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 (~3 sentences plus XML), front-loaded with purpose, and every sentence adds value. The XML tags appropriately structure usage and example.

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 no parameters, a non-empty output schema, and comprehensive annotations, the description fully covers what the tool does, its output, and its role in the workflow.

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?

There are no meaningful parameters (only an empty params object). The description does not need to document parameters and instead focuses on the output, effectively compensating for the 0% schema coverage.

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 lists all 51 disease topics from the BAG Infectious Disease Dashboard, and explains output (slug, category). This is specific and distinct from sibling tools that handle series or data 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 XML tags <use_case> and <important_notes> explicitly instruct the agent to start here and note that slugs are required for other tools, providing clear when-to-use guidance.

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, openWorldHint, idempotentHint, destructiveHint=false. The description adds context: 'Returns file names, not the data' and mentions version parameter behavior, which 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 structured with XML tags (use_case, important_notes, example) and is front-loaded with the core statement. It is slightly verbose but each sentence adds value. The example aids 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?

With an output schema present, the description does not need to detail return format. It covers the main purpose, parameter version context, and links to the sibling tool. For a simple list tool, this is sufficiently complete.

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% (though the schema itself describes the version parameter). The description does not elaborate on the version parameter but successfully explains the return value and usage. Baseline 3 is appropriate given the schema's own description covers the parameter.

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 lists export file names from BAG IDD, provides examples of file names (e.g., INFLUENZA_oblig), and differentiates from the sibling tool download_export by noting it returns names not 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?

The description includes a use_case tag explaining when to use (discover bulk datasets) and an important_notes tag directing to use with bag_health_mcp__download_export. It does not explicitly exclude alternatives, but the guidance is clear for the intended use.

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, destructiveHint=false, idempotentHint=true, and openWorldHint=true. The description adds behavioral context beyond annotations, such as the output format 'topic/chapter/aggregation/temporality' and the fact that it returns series IDs for subsequent use. No contradictions.

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, with only necessary information. It is well-structured using <use_case>, <important_notes>, and <example> tags for easy parsing. The main sentence is front-loaded, and every piece of content adds value.

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 an output schema, so the description does not need to explain return values. It covers the purpose, prerequisite, usage scenario, and output format. For a simple list tool with one parameter, this is complete.

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%, but the schema itself includes a description for the topic parameter. The description reinforces the parameter's purpose by stating the need for a valid slug from list_diseases and demonstrating usage in the example. However, it does not elaborate on constraints like pattern or maxLength.

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 'List all available data series for a specific disease topic', identifying the verb ('list') and resource ('data series'). It distinguishes from siblings by noting that the returned series IDs are used with other tools, and the example further clarifies the output format.

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 includes a <use_case> explaining when to use this tool ('before fetching data'), and <important_notes> highlighting the prerequisite of a valid topic slug from list_diseases. It does not explicitly state when not to use it, but the context is clear enough for agent 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 indicate read-only, idempotent, non-destructive behavior. The description adds important context: the data is aggregated population statistics, not individual advice or diagnosis, and notes limitations (e.g., cantonal breakdowns are rare). No contradictions.

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 comprehensive but not overly verbose. It is front-loaded with the main purpose and uses structured tags (use_case, important_notes, example) for readability. Minor redundancy could be trimmed, but overall efficient.

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 complexity of searching across three sources with multiple parameters, the description covers key aspects: sources, output use, limitations (national focus), and example. It references the output schema indirectly via the downstream tool, making it complete for selection and 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?

The input schema has detailed descriptions for all parameters, so the description's contribution is modest. However, it adds value by explaining source semantics ('obsan', 'versorgungsatlas', 'suchtschweiz') and providing an example that illustrates topic and source 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?

The description clearly states it searches health indicators across three Swiss sources. It specifies the output (matching indicator_ids) and the downstream tool (bag_health_mcp__get_indicator_series). This distinguishes it from sibling tools like list_series or get_series_details.

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 includes a use case tag and an example, guiding when to use: before fetching a series. It does not explicitly state when not to use, but it provides enough context to infer appropriate usage.

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