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

With no annotations, the description carries the full behavioral burden and does well: it discloses that it contacts only this project's GitHub releases (network scope), that it works even when the knowledge base is not built, and what not_ready conveys. It still omits whether the call is cached, rate-limited, or purely read-only, so it falls short of a complete behavioral picture.

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?

Front-loaded with the core purpose, then the network scope, then the action/return contract. The enumeration is dense but every clause maps to a real behavior or routing decision; only the nested parenthetical about build_locally is slightly heavy.

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?

No output schema exists, so the description must describe the return contract, and it does: action, reason, not_ready, and upgrade_to. Together with the edge-case note about running before a knowledge base is built, an agent has everything needed to call it and react to its 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 tool takes no input parameters, so there is nothing to document; per the baseline, a 0-parameter tool scores 4. The description correctly spends no space on nonexistent inputs.

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?

States a specific verb and resource: check whether a newer prebuilt knowledge base is published than the one installed. It also scopes the network call to this project's GitHub releases, so an agent knows exactly what this check touches, distinct from siblings like install_knowledge_base or list_stigs.

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 enumerates every outcome of action (install, upgrade_package, build_locally, none) and routes each to the concrete next step, naming install_knowledge_base, upgrade_to, and the stig-mcp-fetch/stig-mcp-ingest path. This is explicit when/when-not guidance tied to alternatives rather than inference.

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?

With no annotations, the description carries the full load and does so richly: per-id-family return shapes, technique_description being null when a mitigation is not paired with the technique, revoked ids answering for their replacement via technique.redirected_from, not_found listing unmatched ids, outright refusal when nothing matches, and a {"status": "not_ready"} fallback instead of an error. It even discloses a semantic caveat that analytics describe what to collect, not how to enable 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?

Front-loaded with the core action and the id families, then moving into return shapes and edge cases. It is a dense wall of text with long compound sentences, but nearly every clause conveys a distinct behavioral fact rather than repeating structured data.

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?

No output schema and no annotations, yet the description specifies what comes back for each id family, the fields of a detection strategy and analytic, the null/redirect edge cases, the not_found contract, and the not_ready state. An agent has everything needed to call and interpret this 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?

Schema coverage is 0%, so the description must compensate, and it does: ids is documented as taking up to 10 case-insensitively matched identifiers, and technique_id is documented as adding technique_description to the response. It does not state that technique_id is only meaningful for mitigations (not detection strategies or analytics), leaving a small 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?

States a specific verb and resource — return MITRE's text for ATT&CK defenses named by id — and enumerates the three id families it accepts (M1026 mitigations, DET0103 detection strategies, AN0286 analytics). It also tells the agent where those ids come from (protect.mitigations / detect in a defenses_for_technique answer), which separates it from the sibling defenses_for_technique that discovers rather than resolves ids.

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

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

Usage context is clear: this is the detail-lookup step after you already hold ids from defenses_for_technique or techniques_for_actor, and chunking is bounded at 10 ids per call. It never explicitly names an alternative tool or states a when-not-to-use condition, so it stops short of the top tier.

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?

With no annotations, the description carries the full burden and does so richly: it discloses the {"status": "not_ready"} state instead of an error, revoked-technique redirection via technique.redirected_from, the titles degradation rule ('CAT I only') with an explicit warning never to describe untitled findings, the 200-item cap on benchmark_ids and 100 on log_sources, and the precise present/absent/empty semantics of detect.applicable and detect.detectable.

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?

Almost every sentence carries non-redundant information, so the size is largely earned, but it is delivered as one massive unstructured block that jumps between return shape, parameter behavior and error states, making it hard to scan. Bullets or headers would preserve the content with far better retrieval.

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?

There is no output schema, and the description fully assumes that duty by walking through the response layout (summary counts, protect.controls, via mappings, detect.*, mitigations) and explaining how counts should be used rather than recomputed. Combined with the not_ready and redirect handling, an agent has everything needed to call and interpret this 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 coverage is 0%, so the description must compensate, and it documents all six parameters with formats, constraints and examples: severity narrows to CAT levels (e.g. ["I"]), platforms takes ATT&CK platform names and is validated, log_sources takes ATT&CK log source names case-insensitively up to 100, benchmark_ids caps at 200, and system_description should include the product build because it selects between STIG versions.

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?

States a specific verb and resource up front ('Return the defenses the knowledge base holds for an ATT&CK technique') and enumerates the three content families returned: 800-53r5 controls, DISA STIG findings, and ATT&CK mitigations/detection strategy. It distinguishes itself from siblings by directing detail lookups to finding_details and defense_details rather than doing everything itself.

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?

Gives clear routing conditions: call finding_details for check/fix text or CCIs, defense_details for M-/DET-/AN- ids, pass system_description when you cannot name a system, and benchmark_ids when you already know the benchmark. It does not, however, position itself against other entry points such as search_techniques or techniques_for_actor, so the top-level choice is left implicit.

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?

With no annotations, the description carries the full burden and does: it documents the refusal-on-no-match behavior, the not_found list, the {"status": "not_ready"} response for an unbuilt knowledge base, and the quoting/labeling protocol for check_text and fix_text. These are non-obvious behaviors an agent cannot infer from the schema.

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?

Front-loads the core purpose and the payload contents before the id mechanics, and every sentence adds actionable detail. It is dense and slightly long, but no sentence is filler.

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

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

For a single-param tool with no output schema or annotations, the description covers the return contents, id semantics, error/refusal modes, and degraded-state response. An agent has everything needed to call it 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?

Schema coverage is 0%, so the description must compensate, and it does: it specifies the 50-id cap, the two accepted id formats (SV-...r..._rule and V- ids), the prefer-V- rule, and the multi-benchmark dedup behavior. This is far more than the bare string array in 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?

States a specific verb and resource: 'Return DISA's check and fix text for STIG findings,' and immediately names the payload fields (benchmark, release, CCIs). It is clearly distinguishable from siblings like defense_details or check_sources.

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?

Tells the agent where ids come from (defenses_for_technique, techniques_for_actor) and which id form to prefer (V- over rule id, with the release-matching rationale). It stops short of explicitly saying when to choose this tool over defense_details or check_sources, so no full exclusion clause.

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?

With no annotations, the description carries the full burden and does so well: it discloses network dependency ('uses the network'), approximate size and duration ('about 5 MB and can take several seconds'), the SHA-256 verification step, the rollback mechanism via 'release pins an exact kb-YYYY-MM-DD tag', and the no-network branch. This is unusually rich behavioral context for an install/mutate operation.

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?

Every sentence contributes information — download source, verification, size/latency, offline path, trigger conditions — and the primary action is front-loaded. It is somewhat dense and reads as one continuous block rather than clearly separated modes, which costs a point.

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 no-annotation, no-output-schema, 3-parameter tool, the description covers inputs, network behavior, verification, and invocation triggers thoroughly. It does not mention what a successful invocation returns or how failures surface, a minor gap given there is no output schema to lean on.

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, and it does: 'release pins an exact kb-YYYY-MM-DD tag, for rollback'; 'path (a .sqlite.xz or .sqlite copied from a release)'; 'sha256 (the value its SHA256SUMS lists)'. Each of the three parameters gets format and purpose beyond the bare 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 states a specific verb and resource ('Install the prebuilt knowledge base this server answers from') and immediately scopes the default behavior (download newest release, verify SHA-256, install). It also differentiates itself from siblings by noting it is 'the only tool besides check_sources that uses the network.'

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 gives explicit trigger conditions: 'Call this when another tool returns {"status": "not_ready"}, or when check_sources reports "install".' It also names the conditions under which the offline parameters apply ('On a host without network access, pass path ... and sha256'). Both when-to-use and when-to-use-the-alternative-mode are covered.

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?

No annotations are provided, so the description carries the full burden. It adds genuine behavioral value by disclosing the not-ready state return ({"status": "not_ready"}) instead of an error, but says nothing about permissions, pagination, or the shape/ordering of the returned STIG list.

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 core purpose and followed by the edge-case behavior. No filler or 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 single-param, no-output-schema list tool this is nearly complete: purpose, filter semantics, and the not-ready edge case are all covered. Only the return format of a successful call (fields, ordering, size) is left unspecified.

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% and the single 'filter' param is undocumented in the schema, so the description must compensate. It does, explaining that the filter is a substring match against title, benchmark id (with a concrete example, RHEL_9_STIG), or product keywords — meaning the schema alone does not provide.

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?

States a specific verb (List) and resource (STIGs in the knowledge base) and scopes it by the filter dimensions. An agent can immediately distinguish this read/list tool from siblings like search_techniques or mitigations_for_technique.

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 implies usage through the filtering options (title substring, benchmark id, product keywords) but never states when to prefer this over siblings or any prerequisite workflow. It does tell the agent what happens when the KB isn't built, which is useful context, but no explicit when/when-not guidance is given.

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?

With no annotations, the description carries the full burden and discharges it: it explains the limit semantics (caps distinct benchmarks, not rows, and can yield more rows than limit), the 'applicable' field, the tie-overflow note, and the not_ready status with remediation commands instead of an error. This is unusually rich operational disclosure.

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 and return shape are front-loaded, and each sentence carries information. It is dense and runs long, with the tie-note and multi-part-note behavior occupying separate sentences that could be tightened, but nothing is 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?

No output schema exists, so the description must describe returns itself; it names 'candidates', 'notes', the 'applicable' field, and the not_ready shape. For a 2-parameter lookup tool with no annotations, everything an agent needs to call and interpret it is present.

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 the description must compensate and does: limit is explained in depth (benchmarks vs rows, multi-major benchmarks contributing several rows), and system_description gets guidance on including build strings and how multi-system input is parsed. Both parameters gain meaning beyond their bare schema titles.

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 opening sentence states a specific verb (resolve) and resource (free-text system description → candidate DISA STIGs), and the tool is clearly distinguishable from siblings like list_stigs or search_techniques. An agent can tell what it returns ('candidates' and 'notes') without opening any schema.

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 gives strong input-shaping advice (include the product build, multi-system descriptions are split on 'and'/commas) but never states when to prefer this over list_stigs or another sibling, nor any explicit when-not-to-use condition. Usage is implied rather than contrasted against 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?

With no annotations, the description carries the full burden and does well: it discloses that revoked ids/names still match and return a replacement with redirected_from set, and that an unbuilt knowledge base yields {"status": "not_ready"} with commands rather than an error. It does not mention pagination, result caps, or auth needs, so it is not exhaustive.

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 tight sentences, each earning its place: the core purpose first, then revoked-id behavior, then the not-ready edge case. No filler.

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

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

With no output schema and no annotations, the description covers the important edge cases (revoked techniques, unbuilt knowledge base) well. It is only slightly incomplete in not describing the 'limit' parameter or the shape of successful results.

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 the description must compensate. It adds real meaning for 'query' (matches by name or id, including revoked ids), but 'limit' (default 10) is never explained and no query syntax or matching semantics are given.

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?

States a specific verb (search) and resource (ATT&CK techniques) plus the matching keys (name or id). It is clearly distinct from siblings like mitigations_for_technique or techniques_for_actor, but it never names or contrasts those siblings explicitly, so it falls short of a 5.

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 purpose implies when to use it, but there is no explicit when/when-not guidance and no routing to alternatives such as techniques_for_actor or mitigations_for_technique. Usage is left to be inferred from the verb.

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?

With no annotations present, the description carries the entire burden and does so unusually well: it discloses that misspellings are not auto-corrected and the error names nearest groups, that benchmark_ids caps at 200 and log_sources at 100, that severity/platforms/log_sources are validated but inert without include_defenses, that controls/findings are de-duplicated, and that an unbuilt knowledge base returns {"status": "not_ready"} rather than an error.

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 purpose is front-loaded, but the body is a single dense paragraph of conditionals and nested return-shape semantics (summary.coverage, gaps, applicable/detectable id lists) with no structural breaks. Much of it is legitimately load-bearing given the complexity, yet grouping into sections would have made it materially easier to scan.

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

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

For a 7-parameter tool with no output schema and no annotations, the description covers essentially everything an agent needs: normalization and error behavior, parameter limits, the effect of include_defenses, the shape of summary/counts/coverage/gaps, and the not_ready state. Nothing critical for correct invocation appears to be missing.

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, and it does for every one of the seven parameters: actor (id/name/alias, normalization rules, matched_as/also_matches), severity (CAT levels, e.g. ["I"]), platforms, log_sources, benchmark_ids, include_defenses, and system_description. This is far beyond what the bare schema conveys.

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: 'List an ATT&CK actor's techniques,' then qualifies scope with 'optionally expanded with defenses for given systems.' It also implicitly separates this tool from siblings by routing sub-data (defenses_for_technique, finding_details, defense_details) elsewhere, so an agent can tell what this tool owns.

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?

Gives concrete conditional guidance: use system_description 'to scope a system you cannot name,' call finding_details for check/fix text, and call defense_details for MITRE's text on M-/DET-/AN- ids. It also instructs the agent to retry with a group id after a misspelling. It never states when this tool should be preferred over siblings like search_techniques, so it stops short of full when/when-not coverage.

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