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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description adds that it 'always returns an evaluable status rather than an empty result'. This is important behavioral context not captured by annotations, helping the agent interpret results correctly.

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 two sentences, front-loaded with the core purpose and then a clarifying note about return behavior. Every word earns its place, with no redundancy or irrelevant 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?

Given the tool's simplicity (no parameters), the presence of an output schema, and the annotations, the description fully covers the behavioral nuance that matters: the returned status is evaluable even when empty results occur. Nothing else is 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 tool has zero parameters, and the input schema is empty (100% schema description coverage). The baseline for no parameters is 4, and the description appropriately adds no parameter details. It doesn't need to compensate for schema gaps because there are none.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: 'Check whether the I14Y API is reachable and which endpoints respond.' This uses a specific verb ('check') and resource ('I14Y API'), and it distinguishes itself from sibling data retrieval tools by focusing on API status rather than content.

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 when this tool is useful: to distinguish 'no data matched' from 'the source is down'. This implies using it when an empty result may indicate connectivity issues. It doesn't explicitly name alternatives, but the context is clear for an agent choosing between this and data search tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds actionable detail: returns 'value type and version', which is beyond annotations. 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?

Extremely concise: two lines plus argument list. Every sentence adds value with no redundancy. Front-loaded with the core 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?

Given the presence of an output schema (context: has output schema=true) and rich annotations, the description covers essential usage and parameter semantics. Could mention edge cases but is adequate.

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 has 0% description coverage, so description compensates by explaining concept_id source (from list_concepts) and language purpose (titles/descriptions), adding meaning beyond schema's regex and enum.

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 'Retrieve one concept definition' with specific return details (value type, version). It distinguishes from sibling 'list_concepts' by implying this is for a single entity.

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 mentions the concept_id comes from list_concepts, implying usage context, but does not explicitly state when to use this tool vs. alternatives like search_catalog or list_concepts.

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 meaningful context by specifying the response includes 'full record... including endpoints' and that the language parameter affects 'titles and descriptions', which goes beyond the annotations. No contradiction with 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 extremely concise, with one action-focused sentence and a compact Args block. Every word earns its place, and the structure is easy to scan, making it ideal for agent consumption.

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 read-only tool with two parameters and an output schema, this description is nearly complete. It covers the purpose, parameter semantics, and the prerequisite for the ID. The only minor gap is the absence of explicit alternative/contrast with siblings, but the output schema handles return format details, so the description is sufficient.

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 has no per-property descriptions (0% coverage), so the description must compensate. The Args section does this well: it explains that data_service_id is a UUID from list_data_services and that language controls titles and descriptions, adding practical meaning beyond the raw schema (pattern and enum). Slight imprecision: the schema pattern allows more than UUIDs, but the hint is still helpful.

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 the specific verb 'Retrieve' and clearly identifies the resource: 'full record for one registered API, including endpoints'. This distinguishes it from sibling tools like list_data_services (which lists services) and get_dataset (which targets datasets), leaving no ambiguity about what the tool does.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides an explicit prerequisite by stating that data_service_id is a 'UUID from list_data_services', indicating the tool should be used after listing services. However, it does not explicitly name alternative tools or state when not to use this tool, so it falls short of a perfect score.

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, open-world, idempotent, and non-destructive behavior. The description adds valuable context about the aggregated nature of the response, including what data fields are returned and how the language parameter affects titles/descriptions. It does not mention error handling or null results, but the annotation coverage lowers the bar.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the primary action, followed by a useful but slightly verbose workflow explanation. All sentences contribute value, but the second paragraph about the two-call workflow could be tightened. Overall, it is well-structured and appropriately sized.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description is comprehensive for the tool's complexity: it explains the aggregated nature, parameter provenance, and relationship to sibling tools. Since an output schema exists, return value details are not required in the description. With strong annotations and clear usage guidelines, this is a complete package.

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 explains `dataset_id` as a UUID from sibling tools and `language` as the language for titles/descriptions, which adds meaningful semantics beyond the schema's enumerated values and pattern. Minor gap: no detail on fallback behavior if language is not supported.

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 identifies the tool as retrieving the full aggregated metadata record for one dataset, with specific details (contact point, coverage, documentation, distributions with licences). It distinguishes itself from sibling tools by explaining this is the aggregated detail tool that avoids separate lookups.

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 recommends a workflow: `search_catalog` → `get_dataset` answers key questions in two calls, and states that no separate distributions or contact lookup is needed. It also instructs that `dataset_id` should come from `search_catalog` or `list_datasets`, 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 indicate read-only, idempotent, non-destructive behavior. The description adds valuable context beyond annotations: it warns that licences differ between distributions of the same dataset and instructs to always read the licence field. This is a meaningful behavioral note that helps the agent avoid misuse.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact and well-structured: a one-line summary, a clarifying paragraph, and an args section. Every sentence serves a purpose 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 presence of an output schema (not shown but declared), the description does not need to detail return values. It covers purpose, usage context, parameter sourcing, and a critical behavioral note about licences. For a get-by-ID tool with well-annotated safety, 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 coverage is 0%, so description fully carries parameter semantics. It explains that dataset_id is a UUID from search_catalog or list_datasets, and that language controls titles/descriptions. Both parameters are addressed clearly, adding meaning beyond the schema's enums and pattern.

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 downloadable files and access URLs for a dataset,' which is a specific verb and resource. It distinguishes from sibling tools like search_catalog and list_datasets by focusing on distributions, and mentions that get_dataset returns distributions alongside other data, clarifying the scope.

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 frames the tool as 'the «where do I actually get the data» tool' and advises reading the licence field before reuse. It also specifies that dataset_id comes from search_catalog or list_datasets. However, it does not explicitly state when not to use this tool versus alternatives like get_dataset, though it implies the distinction.

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, open-world, idempotent, non-destructive behavior. The description adds context about the data source (I14Y) and the meaning of catalogues, but does not disclose any behavioral traits beyond what annotations provide. With annotations covering most aspects, a score of 3 is appropriate.

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 exceptionally concise: two lines for purpose/context, then a bullet-like args list. Every sentence adds value, no waste. Front-loaded with the main action.

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 tool's purpose and all parameters. An output schema exists, so return format details are not needed. Given the tool's simplicity (list with pagination), the description is adequately 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 has 3 parameters with defaults and constraints, but no descriptions. The description compensates by documenting each parameter: 'Language for titles', '1-based page number', 'Records per page (1-100)'. This adds meaning beyond the schema, meriting a 4 given the low 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 that the tool lists catalogues feeding into I14Y, and explains that each catalogue represents an organization's data collection. While the purpose is specific, it does not explicitly differentiate from sibling tools like search_catalog or list_datasets, which could help an agent choose correctly.

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?

No guidance is provided on when to use this tool versus alternatives (e.g., search_catalog for filtering, list_datasets for sub-resources). The description only explains what catalogues are, not the appropriate context for invocation.

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, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable behavioral context beyond annotations, explaining that concepts are shared definitions and not searchable via catalog, and detailing parameter origins. No contradictions with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured into a purpose statement, context paragraph, and parameter list. It is concise with no redundant sentences, though the parameter list could be slightly more compact. Still, it earns its place.

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 presence of an output schema (not needed to explain return values), the description adequately covers what the tool does, what concepts are, filtering by publisher and language, and pagination. It is sufficient for an agent to use without ambiguity.

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 0% schema description coverage, the description fully compensates by explaining each parameter's meaning: `publisher_identifier` from `list_publishers`, `language` for titles/descriptions, `page` as 1-based, `page_size` range 1-100. This adds critical context beyond the schema's type and constraints.

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 harmonised concepts and code lists of the Swiss administration' with a specific verb and resource. It also distinguishes itself from the sibling `search_catalog` by noting that these are not reachable through that tool, making purpose and differentiation explicit.

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 context on when to use this tool (to access shared semantic definitions) and explicitly excludes `search_catalog`. However, it does not compare against other siblings like `list_datasets` or `get_concept`, so usage guidance is good but not exhaustive.

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 non-destructive behavior. The description adds valuable context about what the tool returns (endpoint URLs and OpenAPI specs) and pagination details, going 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 and well-structured: purpose first, then strategic payload, then usage guidance, then parameter list. Every sentence adds value with 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 complexity (4 optional parameters, annotations, output schema present), the description covers all essential aspects: what is returned, when to use it, and parameter details. The presence of an output schema reduces the need to explain 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?

With 0% schema description coverage, the description fully compensates by explaining each parameter in the Args section: publisher_identifier, language, page (1-based), and page_size (1-100). This adds meaning 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 'List machine interfaces (APIs) registered by Swiss public bodies,' using a specific verb and resource. It distinguishes itself from sibling tools by mentioning 'the national register of official APIs' with endpoint URLs and OpenAPI links.

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 explicit usage guidance: 'Use this to discover whether an interface already exists before building a scraper.' It also references the sibling tool `list_publishers` for obtaining the publisher_identifier, though it does not explicitly state when not to use this tool.

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

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

Annotations already declare readOnly, idempotent, and non-destructive hints. The description adds valuable behavioral context: it paginates correctly, covers the complete register (~2000 datasets), and includes records missed by the search index. This enriches transparency beyond annotations, though it could mention potential latency or consistency.

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, starting with the primary purpose, then differentiation from a sibling, followed by a clear parameter list. Every sentence adds 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 tool's moderate complexity, the description covers the essentials: purpose, differentiation, parameter meanings, and key behavioral traits (pagination, coverage). However, it omits details like sorting order or timeout behavior. An output schema exists, so return values need not be documented.

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 0% schema description coverage, the description carries full burden for parameter semantics. It provides meaningful descriptions for all parameters: `publisher_identifier` from `list_publishers`, `access_rights` examples, `language` values, and pagination details. This compensates well, but lacks specifics on default values (already in schema) or format constraints.

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 registered datasets with optional filtering by publisher. It explicitly distinguishes from the sibling `search_catalog` by highlighting its correct pagination and complete register coverage, providing a specific verb+resource differentiation.

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 explicit guidance on when to use this tool (for complete register and correct pagination) and contrasts with `search_catalog` as an alternative. It also documents parameter examples like `publisher_identifier` from `list_publishers` and `access_rights` values, offering clear context for usage.

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, idempotentHint, and destructiveHint=false. The description adds that it lists public services, which is consistent but does not disclose additional behavioral aspects like pagination behavior or rate limits beyond parameter docs.

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: one sentence for purpose followed by a clear docstring with each parameter explained. No fluff, 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?

Given the tool's simplicity (list with pagination and optional filter) and the presence of an output schema, the description adequately covers what the tool does and parameter semantics. Missing are potential error conditions or additional output context, but it's sufficient.

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 0% schema description coverage, the description compensates by explaining all 4 parameters: publisher_identifier source, language purpose, page base, and page_size range. This adds context beyond the schema constraints.

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 'registered public services' with the parenthetical 'administrative offerings for citizens', which distinguishes it from sibling tools like list_datasets or list_data_services that list other entity types.

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 no explicit guidance on when to use this tool vs alternatives, but hints at a dependency by noting that publisher_identifier comes from list_publishers. No when-not-to-use or alternatives are mentioned.

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, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds that it returns identifiers and the Swiss UID, which is useful but does not significantly extend the safety profile already conveyed by 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 two sentences plus a bullet list of parameters. No word is wasted; every sentence adds unique value: purpose, output context, and parameter details. Structure is clear and front-loaded.

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, the description appropriately mentions the key output fields (identifiers, Swiss UID). It covers all necessary aspects for a listing tool with filters, though could briefly mention pagination behavior (already in 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?

Despite 0% schema description coverage, the description fully explains each parameter: identifier, uid (with example), language, page (1-based), and page_size (1-100). This compensates entirely for the lack of schema descriptions.

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 the public bodies that publish into I14Y', providing a specific verb-resource combination. It distinguishes from sibling tools like list_datasets and list_catalogs by focusing on publishers, and hints at its role supplying identifiers needed by other 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 mentions that the output contains 'publisher identifiers needed by the other tools' and notes the UID as a join key to register-mcp. This gives context for when to use it, but does not explicitly state when not to use it or contrast with 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, openWorldHint, idempotentHint, and destructiveHint=false. The description adds the server-side capping of limit due to upstream ignoring paging, and the limitation that some type filters yield zero results despite existence. This adds valuable behavioral context beyond annotations, though could mention rate limits or error handling.

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 main paragraph, a limitation note, and parameter list. It is informative but slightly verbose; some sentences could be tightened without loss of clarity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (6 parameters, sibling tools) and presence of output schema, the description covers all essential aspects: purpose, when to use, parameter semantics, known limitations, and alternatives. No gaps in guidance for effective 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?

Despite 0% schema description coverage, the description provides detailed explanations for all 6 parameters in the Args section, including query free-text, language options, types (with known limitation), themes, publishers, and limit behavior. This fully compensates for the schema's lack of descriptions.

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 Switzerland's national metadata catalogue for data resources' and describes it as the primary entry point to find who publishes data on a topic. It lists returned fields (titles, publishers, themes, permalinks) and distinguishes from sibling tools like list_concepts and list_data_services.

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 'use this to find out *who* publishes data on a topic before looking for a specific dataset.' Provides a known limitation that types other than 'Dataset' may return zero results and directs to alternative tools (list_concepts, list_data_services). Also warns against empty query returning full index.

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. Description adds behavioral context beyond annotations: the constraint on concept_type, that language is required by upstream API, and pagination semantics. 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?

Concise yet thorough: a clear introductory sentence, a context paragraph, and structured Args section. Every sentence adds value; no 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 tool's complexity (4 parameters, output schema exists, annotations present), the description is complete. It explains purpose, usage context, parameter details, and a key behavioral condition. Output schema covers 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%, but the description fully compensates by explaining each parameter: concept_id as UUID from list_concepts, language as required by upstream API, page as 1-based, page_size range (1-200). This adds significant meaning beyond the schema types.

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 action ('List the individual codes') and the resource ('a code-list concept'), with a specific use case example. It differentiates from sibling tools (e.g., list_concepts) by focusing on entries within a codelist.

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 explicit context: 'Use this to resolve official code values' and a condition ('Only concepts with concept_type == "CodeList" return entries'). It does not explicitly state when not to use or list alternatives, but the usage is well implied.

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