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

Annotations indicate readOnlyHint=true, and the description adds behavioral details: hybrid retrieval method, RRF scoring, invalid filter failure, limit cap, verbose field population, and score normalization. No contradictions; adds significant context beyond annotations.

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

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

The description is thorough but not excessive; every sentence adds value. It front-loads the purpose and usage, then lists filters and behavior. Slightly long but justified by complexity.

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

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

Given the tool's 7 parameters, many siblings, and existence of an output schema, the description covers purpose, usage, parameter semantics, behavioral traits, and output notes (score and verbose). It references sibling tools for non-applicable cases, 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?

With 0% schema coverage, the description compensates by explaining all optional parameters: classification values, maturity note, tags validated against ism_list_sections, paths effect, limit default/cap, and verbose behavior. The required 'work' parameter is only described as 'free-text description'; a example would strengthen it.

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 ranks ISM controls relevant to a free-text description, calling itself the 'primary discovery tool'. It immediately distinguishes from ism_search for exact lookup, providing a specific verb+resource combination.

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 when to use (for free-text description) and when not (exact keyword lookup, use ism_search). Provides detailed guidance on each optional filter, including maturity scoping and tag validation, making decisions 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 readOnlyHint=true. The description adds: never writes, reads `.ism-coverage.toml`, walks up from cwd, can run `ism_applicable` if `work` supplied, intersects results, and ranks by relevance score. It also describes ordering: uncurated > partial > deferred. This exceeds annotation-provided info and does not contradict.

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 front-loaded: the first sentence gives the core purpose and a safety note ('Never writes'). The second paragraph adds necessary detail without redundancy. Every sentence 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?

With an output schema present and good annotations, the description covers the tool's purpose, behavior, two modes, and ordering. It does not mention error cases or prerequisites (e.g., existence of manifest), but for a tool with this complexity, it is quite 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%. The description explains `work` (triggers intersection with `ism_applicable` results for relevance) and `project_path` (defaults to cwd walk-up). `limit` is not described, only its default (50). Two out of three parameters get meaningful explanation, compensating for lack of schema description.

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

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

The description clearly states it returns outstanding in-scope controls (uncurated, partial, deferred). It distinguishes itself from the sibling `ism_coverage_read` by explaining the complementarity: 'read reports what is curated, gaps reports what is missing.' The verb 'return' and resource 'in-scope controls' are specific.

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 to use it (to get gaps) and what it does (reads manifest, never writes). It contrasts with `ism_coverage_read` but does not explicitly compare with other siblings like `ism_coverage_impact` or `ism_get`. However, it provides clear context on two modes (with and without `work`) and mentions walking up from cwd.

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

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

The description provides rich behavioral details beyond the readOnlyHint annotation: it explains the three output buckets (re_review, removed_upstream, new_uncovered), default behaviors for target_version and project_path, and that it reads the manifest like ism_coverage_read. The annotation is consistent (readOnlyHint=true, 'Never writes').

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: it starts with the core purpose and read-only nature, then details the output buckets, defaults, and contextual usage. 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 output schema exists (so return values are not needed in description), the description adequately covers the tool's behavior, usage context, and parameter defaults. The only minor gap is no mention of the limit parameter, but since it defaults to 50 and has an output schema, this is acceptable.

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 0% description coverage, so the description must compensate. It adds meaning for target_version (defaults to scope.baseline_version or active version) and project_path (walks up from cwd when omitted), but does not describe the limit parameter. Coverage is partial, warranting a score of 3.

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

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

The description clearly states it reports impact of a newer ISM version on coverage, and explicitly says 'Never writes.' It distinguishes itself from sibling tools like ism_coverage_upsert (writes) and ism_coverage_read (reads current state).

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 to use it: 'Run this after ingesting a new ISM release' and what to do next: 'curate the buckets with ism_coverage_upsert.' It also mentions default behavior for target_version and project_path, but does not explicitly state when not to use it.

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

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

The description states 'Never writes', which aligns with the `readOnlyHint` annotation. It further details that `status_filter` narrows the controls map but leaves the summary unfiltered, adding behavioral insight 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. The core function is stated upfront, followed by succinct parameter explanations and a clear sibling alternative reference. No extraneous words.

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

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

Given the tool has only two parameters, an output schema, and clear annotations, the description covers all necessary aspects: purpose, parameters, behavior, and alternatives. It is complete for an AI agent to select and invoke correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Despite 0% schema description coverage, the description fully explains both parameters: `project_path` behavior (walk-up from cwd) and `status_filter` acceptable values and effect (filters controls map, not summary). This compensates the missing schema descriptions completely.

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 reads the project's coverage manifest, specifying the resource (`.ism-coverage.toml`) and the action. It also distinguishes itself from a sibling tool, `ism_coverage_gaps, by clarifying that this tool returns curated entries while the sibling shows missing items.

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 tells when to use this tool versus the alternative `ism_coverage_gaps`. It also explains the behavior when `project_path` is omitted (walks up from cwd) and fails if not found, providing 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?

The description goes far beyond the annotation hints (idempotentHint, destructiveHint). It discloses atomic rewrite, whole replacement of existing entries, validation against ISM DB, requirement for attachment paths to exist on disk, default value for last_reviewed, and return of action taken plus warnings/failures. No contradiction 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 concise but packs substantial information. It front-loads the core purpose in the first sentence, then adds critical context in subsequent sentences. Every sentence earns its place, with no redundancy or filler.

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

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

Given the complexity (12 parameters, 3 required, no schema descriptions, and existence of an output schema), the description covers the core behavior, validation rules, and return value. It could mention the output schema or explain more optional parameters, but it provides enough for an agent to use the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description compensates well by explaining the 'status' enum values, the default for 'last_reviewed', validation rules for identifiers and attachments, and that URLs/attachments need descriptions. However, not all 12 parameters are individually described, leaving some like 'files', 'commits', 'reviewed_by' unaddressed.

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 creates or updates one entry in the coverage manifest, specifying the exact resource (.ism-coverage.toml) and using the verb 'upsert'. It explicitly distinguishes from siblings by stating it is 'the only tool that writes to disk'.

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

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

The description explicitly states when to use the tool: for writes to the coverage manifest, and that it is the only write tool, effectively excluding all sibling read-only tools. It also lists conditions for proper use (valid identifier, attachments on disk, URLs/attachments with descriptions) and failure modes (validation errors).

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

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

Annotations already provide readOnlyHint=true and openWorldHint=false. Description adds useful context: fails on unknown versions, returns specific structure {from, to, summary, changes}, and change_types behavior (unrequested buckets set to null). Adds value beyond annotations.

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

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

112 words, front-loaded with main purpose. Every sentence adds value: defaults, alternatives, parameter effects, return structure, failure case. 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 output schema exists, description provides sufficient return structure and error behavior. References sibling tools for context. Covers all necessary aspects without being verbose.

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 explains all three parameters: from_version and to_version with defaults, change_types with enumerated possibilities and effect (unrequested buckets set to null). This compensates for 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 it catalogs delta between two ISM versions, using specific verb+resource. It distinguishes from siblings like ism_history (one control's timeline) and ism_versions (loadable versions).

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 explains defaults (version before active vs active), so bare call answers 'what changed in latest release'. Provides alternatives: ism_versions to see loadable versions, ism_history for one control's timeline.

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 (safe read). Description adds: input tolerance (various formats), return fields (title, control text, etc.), failure on no match, defaults to active version, and version parameter for historical. 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?

Four concise sentences. Front-loaded with purpose and input format. Efficiently covers behavior, defaults, and alternatives. 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 output schema exists (signal indicates true) and annotations provide safety info, description adds all necessary context: input handling, output fields, failure mode, version defaults, and sibling guidance. Complete for a getter tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema has 0% description coverage, so description must compensate. It thoroughly explains identifier parameter (tolerant input, example, canonical ID). Version parameter is mentioned as optional with reference to ism_versions, but could provide more detail on format. Still largely covers key aspects.

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

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

Description clearly states verb 'Get' and resource 'full record for one ISM control'. Identifies specific input ('by identifier') and gives example. Differentiates from siblings by recommending ism_search or ism_applicable when identifier is unknown.

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

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

Explicitly states when to use (known identifier) and when not to (unknown identifier, suggests alternatives). Mentions default behavior (active version) and optional parameter (version) with reference to ism_versions.

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. Description adds that identifier input is tolerant and unknown IDs return empty timeline with hint rather than error, going beyond annotations.

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

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

Three efficient sentences, front-loaded with main purpose, no redundant text.

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 main behavior, error handling, and alternative tool. Output schema exists so return format need not be detailed. Could briefly mention that timeline includes changes across versions, but overall 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 for the single parameter. Description mentions 'tolerant like ism_get' but does not clarify identifier format or what it represents. Partially compensates but remains vague.

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

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

Clearly states the tool shows one control's evolution across all loaded ISM versions. Distinguishes from sibling ism_diff by noting it is for whole-catalog delta.

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 directs to use ism_diff when needing whole-catalog delta. Mentions identifier tolerance akin to ism_get, but lacks broader comparison to other siblings like ism_search.

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

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

Annotations already indicate readOnlyHint=true. The description adds that it returns a summary with ids only, and that an unknown level fails. This provides useful behavioral context beyond the annotations, though it could mention the return type more formally.

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 three sentences each adding distinct value: purpose, parameter guidance, and return/error behavior. Front-loaded with the main action, 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 presence of an output schema, the description provides sufficient context: it lists controls by classification, returns a summary format, and errors on invalid input. It could be more explicit about the identifiers' nature, but overall it is complete for a simple listing tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description explains the classification parameter in detail, including allowed values and a hint to another tool for mapping. However, it omits any explanation of the optional version parameter. With schema coverage at 0%, the description should cover both parameters.

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 controls by classification level. The verb 'list' and resource 'controls' are explicit, and it distinguishes itself from siblings like ism_get (full records) and ism_list_by_topic (filter by topic).

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?

It specifies that classification takes canonical abbreviations and directs to ism_list_classifications for the mapping. It also instructs to use ism_get for full records. While it does not explicitly contrast with ism_list_by_topic, the purpose is clear enough for the agent to choose correctly.

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?

Discloses return shape `{topic, count, identifiers}` with only IDs, and default behavior for unknown topic (empty list, not error). No contradiction with readOnlyHint annotation; adds value beyond it.

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?

Two sentences, front-loaded with purpose, no wasted words. Efficient and clear.

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 2 parameters and output schema exists, description fully covers behavior: return shape and error handling. Complete for intended use.

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 0% means description must compensate. It explains 'topic' is exact match and references ism_list_topics for enumeration, adding semantic value. Version parameter is not mentioned, so partial compensation.

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

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

Clearly states verb 'List', resource 'controls under a specific topic', and scope 'exact match'. Distinguishes from sibling ism_list_topics by specifying enumeration.

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

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

Provides clear context: when to use (list by topic), alternative (ism_list_topics for enumeration), and follow-up (ism_get for full records). Lacks explicit 'when not to use' but sufficient.

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

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

Description adds value beyond annotations by disclosing 'Static data, no database read' and explaining output structure (parallel lists). Annotations already have readOnlyHint=true, but description provides concrete behavioral context.

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?

Very concise, two sentences plus a code-like explanation of the data structure. No wasted words, purpose is 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?

Tool has zero parameters, high schema coverage, and output schema exists. Description explains output format and relations to siblings, which is fully adequate for this simple tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

No parameters exist, so baseline is 4. Description adds meaning by detailing the output structure and interaction with sibling tools, which is helpful for understanding return format.

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

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

Description clearly states it returns 'classification vocabulary as parallel lists' with explicit mapping between canonical and friendly terms. Verb 'Return' is specific to resource, and it distinguishes from siblings by mentioning which sibling accepts which form.

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

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

Explicitly states when to use this tool vs alternatives: ism_applicable accepts either form, ism_list_by_classification accepts canonical only. Also clarifies static data with no database read, guiding appropriate 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=true and openWorldHint=false. The description adds that the data is static and involves no database read, which aligns with annotations and provides extra context.

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 very concise: two sentences that front-load the main purpose and then add necessary context. Every sentence earns its place 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 no parameters and an output schema, the description is fully complete. It explains the tool's return values, its static nature, and its relationship to other tools, leaving 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?

There are zero parameters, so schema coverage is 100%. The description adds meaning by listing the actual maturity levels (ML1, ML2, ML3) and explaining their role in the broader system.

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

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

The description clearly states the verb 'Return' and the specific resource 'Essential Eight maturity levels: ML1, ML2, ML3'. It distinguishes from siblings by focusing on maturity levels, which are unique to this tool.

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 that these maturity levels are used for filtering in ism_applicable and coverage manifest scope, providing context for when to use the tool. It doesn't explicitly state when not to use, but the purpose 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 indicate read-only; the description confirms listing behavior and adds details on return format ({count, sections}) and version handling, going beyond annotation.

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 consists of two efficient sentences that front-load purpose and cover key behavior without waste.

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 list tool with one optional parameter and an output schema, the description sufficiently covers purpose, return shape, and version behavior.

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 coverage, the description explains that version overrides the active version, adding meaning to the otherwise vague parameter definition.

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 distinct ISM Section values and connects to the `tags` filter on ism_applicable, distinguishing it from sibling list tools like ism_list_classifications.

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 that this tool provides the vocabulary for the `tags` filter on ism_applicable, implying usage for obtaining filter values, but does not explicitly exclude alternatives.

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

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

Annotations already indicate readOnlyHint=true, so the description's non-destructive nature is reinforced. The description adds behavioral details: it returns {count, topics} and respects an optional version parameter, which goes beyond the annotations.

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

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

Two sentences with no superfluous words. The first sentence states the core purpose, the second adds contextual information. Every sentence 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?

With the existence of an output schema (not provided but noted), the description's mention of the return format ({count, topics}) is sufficient for a simple listing tool. It covers the single optional parameter and the behavior, making it complete enough for the given complexity.

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 0% description coverage, so the description must compensate. It explains the version parameter controls which ISM version to query, adding semantic meaning. However, it does not fully describe the version's format or default behavior, leaving some ambiguity.

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 distinct topic strings from the ISM, using specific verb 'List' and resource 'distinct topic strings'. It also differentiates itself from sibling by noting it provides the vocabulary for ism_list_by_topic, making its purpose unambiguous.

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

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

The description explicitly indicates this tool is the source for valid topic arguments for ism_list_by_topic, providing clear usage context. While it doesn't explicitly state when not to use it, the context is strong enough to guide the agent effectively.

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, but description adds value beyond that: FTS operators are neutralized for literal matching, limit defaults to 10 (capped at 200), and version defaults to the active ISM version. No contradictions found.

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 5 sentences, each adding distinct information. It is front-loaded with purpose, then usage guidance, then behavioral details, return format, and defaults. 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 output schema exists, description explains return format {query, count, results} with full control records. Covers default behaviors and version handling. With sibling context and clear purpose, it is complete for a search tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so description must compensate. It clarifies that query is the search term, limit has a default of 10 with a cap of 200, and version defaults to null (active version). This adds meaning beyond the raw schema but doesn't detail each parameter completely.

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 'Full-text keyword search (FTS5 BM25) over ISM control text and topics,' using a specific verb and resource. It distinguishes from sibling ism_applicable by clarifying when each is appropriate.

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 'Best when you already know the terms... To rank controls against a free-text description of work, use ism_applicable instead,' providing clear guidance on when to use this tool vs. its sibling.

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, indicating the tool is safe and non-destructive. The description adds that it reports database state and is a first call, but does not disclose additional behavioral traits beyond what annotations provide.

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

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

Four sentences, each essential. First states purpose, second notes no arguments, third gives usage context, fourth references sibling. No fluff, perfectly 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?

For a zero-parameter tool with an output schema, the description is complete. It covers what the tool does, how to use it (first call), and points to an alternative for full version list. 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?

There are no parameters, so baseline is 4. The description adds value by explaining what the output contains (active ISM version, version/control counts, db path), which goes beyond the empty 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 the tool reports database state with specifics: active ISM version, version and control counts, db path. It distinguishes itself from sibling tools by noting that for the full version list, one should use ism_versions.

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 it is useful as a first call to confirm data ingestion and identify which ISM release other tools will answer from. Also directs users to ism_versions for the full version list, providing clear when-to-use and when-not-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=true, and the description adds the return structure and ordering (newest first). No contradictory or missing behavioral traits given the tool's read-only nature.

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?

Two sentences, front-loaded with the main action, then return format and usage. 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 simplicity (no parameters, output schema exists), the description fully covers what the tool does, its return value, and its role relative to siblings. Complete and 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?

Tool has zero parameters, so no parameter information is needed. Baseline score of 4 is appropriate as the description explains the tool's purpose without needing to elaborate on parameters.

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 states 'List loaded ISM versions, newest first' with a specific verb and resource. It also clarifies that this tool provides the vocabulary for version/from/to arguments, distinguishing it from siblings like ism_get or ism_search.

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

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

Explicitly says to call this before passing version, from_version, or to_version to other tools. Provides clear context for use, though no explicit when-not-to or alternative suggestions.

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