MacTech STIG

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds meaningful behavioral context: 'Rules you do not supply a status for come out as Not_Reviewed.' This discloses a key default behavior not captured by annotations, adding value beyond the structured fields.

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 four sentences, each earning its place: the action, the artifact's significance, the default behavior, and explicit usage guidance. It is front-loaded with the core purpose and has zero fluff.

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

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

The tool has no output schema, but the description adequately explains what the tool produces (a .ckl XML), its real-world purpose (handed to STIG Viewer/eMASS/POA&M), and the important default behavior for unspecified rules. This is enough for an agent to select and invoke correctly in context.

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 67%, and the description adds clarity by mentioning 'optionally filtered by severity' (matching the severity param) and 'pre-populated with findings' (clarifying the findings array). It also reinforces the meaning of the findings status field by explaining the Not_Reviewed default. The description does not cover host_ip/host_fqdn, but those are straightforward.

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 'Generate[s] a DISA STIG Viewer checklist (.ckl XML) for a benchmark' with specific verb and resource. It also distinguishes itself from sibling tools by positioning this as producing the hand-off artifact, not simply reading rules.

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 gives usage direction: 'Call this when the user wants a checklist, a scan result recorded, or evidence to submit, rather than just to read a rule.' This clearly identifies when to use the tool and contrasts it with the read-only actions of 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 declare readOnly, idempotent, and non-destructive behavior. The description adds value by enumerating the returned content (requirement discussion, check procedure, fix text, severity, NIST mapping, SCAP-automatable), which is not in the structured annotations. No contradiction or misleading claims.

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 concise sentences, front-loaded with the core purpose and followed by usage guidance. Every clause adds information; 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 simple one-parameter read-only tool with strong annotations and no output schema, the description covers purpose, usage, and return content effectively. It gives enough context for an agent to invoke it correctly without additional documentation.

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 for sv_id is thorough, with example format and fragment matching behavior. The description adds the useful hint that the id comes from 'search_stig', but this is a minor addition beyond the schema. With 100% coverage, baseline 3 is appropriate.

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 gets the complete detail for one DISA STIG rule by its SV id, listing specific fields. It distinguishes itself from siblings by referencing 'from search_stig' and framing it as the detailed follow-up to search results, unlike listing benchmarks or exporting checklists.

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?

Explicit when-to-use guidance is provided: 'Call this when the user needs to implement or verify a specific rule.' The reference to 'from search_stig' implies the typical workflow but does not explicitly name alternatives or when not to use the tool, so it falls short of a 5.

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, and the description aligns by saying 'list'. It adds value by specifying the return contents (versions, rule counts, severity breakdowns), which goes beyond the annotations. No contradiction.

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 a single sentence that conveys purpose, output content, and usage guidance without wasted words. It's 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?

For a simple list tool with no parameters and no output schema, the description provides sufficient context: what it lists, what each entry includes, and when to call it. Could be slightly more detailed on return structure 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?

The input schema has zero parameters, so schema coverage is 100%. With no parameters to explain, the description doesn't need to provide parameter semantics; baseline for 0 params is 4.

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 uses a specific verb 'List' and identifies the resource 'DISA STIG benchmarks' with scope 'this server covers', and adds detail about versions, rule counts, and severity breakdowns. This clearly differentiates it from sibling tools like get_stig_rule or search_stig.

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 instructs to 'Call this first when unsure whether a platform is covered', giving a clear when-to-use scenario. It doesn't mention when not to use or alternatives, so not a 5.

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 discloses the keyword matching order ('rule IDs and titles first, then descriptions'), states the return format ('Returns summaries'), and explains severity mapping ('high/medium/low, mapping to CAT I/II/III'). Annotations already convey read-only and idempotent, and the description adds context beyond that. However, it mentions a 'category' filter that does not exist in the schema, creating a minor accuracy blemish.

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 sentences: the first states scope and filtering, the second gives explicit use cases, the third explains the summary vs. full-text distinction. Every sentence earns its place, and the most important information 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?

Given 6 parameters, no output schema, and rich annotations, the description covers platforms, filters, use cases, and return nature. It appropriately defers to get_stig_rule for full details. The minor gap is the category mismatch and lack of mention of pagination, though offset parameters are described in the schema.

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

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

Schema description coverage is high (83%), so the baseline is 3. The description adds useful context for the query parameter (matching order and example 'ssh banner' or rule ID) and clarifies severity mapping, but it also introduces a non-existent 'category' filter, which confuses parameter semantics. Overall it provides marginal added value 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 opens with a specific verb and resource: 'Search DISA STIG hardening rules' and lists the exact platforms. It clearly distinguishes from siblings by stating it returns summaries and directs to get_stig_rule for full text, so an agent can differentiate this search tool from the retrieval 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?

It explicitly says 'Call this when the user asks how to harden one of these platforms, what a STIG requires, or which rules cover a topic...' and provides an alternative: 'use get_stig_rule for full check and fix text.' This is direct, actionable guidance with a clear when-to-use and a named alternative.

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