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 declare readOnly/idempotent/non-destructive, and the description adds substantial beyond-annotation behavior: failure semantics ('the call fails with that reason instead of returning an empty series'), pooled-span handling ('1998-02' = 1998-2002 with first year in 'year'), unit semantics ('g'/'kg' rates vs 'gum' distribution %), and the region-fallback note.

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?

Dense but front-loaded: source/verb first, then variant semantics, then region behavior, then caveats and an example. Every sentence carries factual weight (units, pooling, failure mode), though the volume is near the upper bound for a single tool and could be trimmed slightly.

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?

Extremely complete for a read tool with an output schema: return values need not be explained, yet the description still covers units, variant selection, cantonal fallback, pooled periods, and explicit failure behavior. An agent has everything needed to call it correctly and interpret the result.

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 descriptions already document region, source, year bounds and language, so that coverage carries much of the load. The description still adds genuine meaning for the key parameters: what 'variant' means (one of several non-interchangeable cuts, others listed in 'variants_available') and the region='ZH' cantonal behavior, plus unit interpretation the schema does not express.

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 ('Fetch one health indicator's time series') and names the three concrete sources (Obsan, Versorgungsatlas, Sucht Schweiz/HBSC). It distinguishes itself from the sibling search_health_indicators by casting that tool as the id supplier, so an agent can tell the two apart without opening schemas.

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?

States the prerequisite ('Use an indicator_id from bag_health_mcp__search_health_indicators') and gives explicit when-to-use guidance via the use_case tag ('national trend, or a cantonal series with a Switzerland comparison'). It also states a when-not: HBSC is national-only, and a canton request silently returns the national cut, so the agent knows the comparison is unavailable.

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 cover readOnly/idempotent/openWorld, but the description adds substantial non-obvious behavior: results are aggregated population statistics, not individual advice or personal data; the catalogue does not state available cuts; most Obsan indicators are cantonal while HBSC/suchtschweiz is national only; and some catalogue entries have no series at all. This is exactly the kind of context annotations cannot express.

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 and every section carries information, but there is noticeable repetition: the suchtschweiz source is described three times and the 'aggregated, not individual' warning is restated in the same block. Trimming the duplication would tighten it without losing content.

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 an output schema exists, return-value documentation is not required, and the description still states that matching indicator_ids are returned for the series call. The canton-cut caveat, empty-series caveat, and source semantics leave no significant gap 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?

Reported schema coverage is 0%, so the description must compensate, and it does for the highest-stakes parameter: it defines each source enum value and warns that the region/canton hint may not narrow results. Examples for topic ('alkohol') are given, though limit, language, and year_from/year_to receive no treatment 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?

Opens with a specific verb+resource ('Search health indicators') and immediately enumerates the three distinct sources with scope for each. It also names the downstream sibling (bag_health_mcp__get_indicator_series) so the agent knows where its output flows, making it easy to distinguish from the other bag_health 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 <use_case> tag states the precise trigger ('Find which indicators exist for a topic ... before fetching a series'), and the closing example shows a concrete invocation. It also implicitly routes the agent away from this tool for series data by pointing at get_indicator_series.

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