psirt-exposure

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

Beyond the read-only/idempotent/open-world annotations, the description discloses verdict categories, per-item contents, offline CSAF vs live OpenVuln behavior, CISA KEV feed downloading, and only_findings filtering. These are concrete behavioral traits that materially help an agent invoke the tool 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 compact and front-loads the main action and verdict model before listing parameter notes. The fragment style is efficient, though the inventory/netbox omission means it is concise at the cost of completeness.

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 7 parameters, output schema support, and open-world annotations. The description covers the main workflow and outputs, but missing inventory/netbox_filter semantics and prerequisites for live OpenVuln/CISA downloads leave meaningful 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?

Schema description coverage is 0%, so the description must carry parameter meaning. It explains devices, rules, versions, kev, and only_findings, but omits inventory and netbox_filter entirely, leaving two parameters undocumented.

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: matching advisory rules against device configs, with one verdict per device/rule. It does not explicitly differentiate itself from siblings such as report, though it does point to list_devices/list_rules for inputs.

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 is implied by the purpose and by references to list_devices/list_rules for valid names, plus defaults for devices/rules. However, it does not say when to use check versus report, nor does it 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?

Annotations already declare readOnly, idempotent, and openWorld, so the safety profile is covered; the description corroborates the external-system aspect with the NetBox query note. It adds little beyond that — no mention of rate limits, pagination, or what happens when netbox_filter matches nothing.

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 short lines, purpose first, then per-parameter notes — no filler and easily scanned by an agent.

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 annotations covering the safety profile, the description only needed to disambiguate the two inputs, which it does. Minor gap: the interaction between inventory='files' and a supplied netbox_filter is left unexplained.

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 carries the load, and it does: it defines the 'inventory' enum values ('files' = sample config directory, 'netbox') and gives a concrete example filter shape for netbox_filter. That meaningfully exceeds the bare schema, though it never states that netbox_filter is ignored or required depending on inventory.

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 ('List inventory devices') and even names the fields returned (platform PID, IOS XE version), so the agent knows what it gets. It does not differentiate itself from siblings like check or report, which remain ambiguous by comparison.

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 the two inventory sources ('files' as a sample config directory vs 'netbox'), which implies when each mode applies, but it gives no explicit when-to-use-this-vs-alternatives guidance or prerequisite statements relative to check/report.

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, idempotentHint=true and openWorldHint=false, so the safety and determinism profile is covered without prose. The description adds the field set, which is useful orientation, but says nothing about volume, ordering, or whether the list can be empty — gaps that matter for a zero-param 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?

A single front-loaded sentence with the resource first and the field list after the colon. No filler, no restatement of the name.

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

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

With an output schema present, the description need not document return structure, and a zero-param read tool carries little hidden complexity. What remains unstated — ordering, result volume, empty-list behavior — is minor but non-zero for an agent deciding whether to call this first.

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 parameters, so there is no parameter semantics to explain; the baseline for a parameterless tool applies. The description's field enumeration is technically about return values rather than inputs, but nothing is missing on the input side.

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+resource ('List the reviewed advisory rules') and enumerates the fields returned (id, advisory, CVEs, title, exposure summary). It never names a sibling or clarifies scope versus list_devices, so differentiation is left to inference, but the purpose itself is unmistakable.

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 is only implied by the verb 'List' and the zero-parameter signature; there is no explicit when-to-use, no prerequisite, and no mention of alternatives like check or report. An agent can reasonably guess this is the enumeration entry point for rules, but the description does nothing to route 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?

Annotations already declare readOnlyHint, idempotentHint and openWorldHint, so the safety profile is carried. The description usefully discloses the report's section structure, but leaves a material ambiguity: whether rendering returns the document as text or writes a file to disk — a key behavioral fact for an agent deciding whether it can consume the output.

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 output shape, with zero filler. The trailing 'Arguments as for check' is tersely efficient, though it is cryptic enough that brevity shades into under-specification.

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

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

With an output schema present, the description needn't describe return values, but for a 7-parameter, zero-coverage tool it should do more than redirect to 'check'. The dependent-argument note is a reasonable shortcut, yet the missing file-vs-text output behavior and any scope caveats leave the definition adequate but incomplete.

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% across 7 parameters, so the description must compensate and it largely does not. 'Arguments as for check' offloads all semantics to a sibling schema, and opaque parameters such as kev, versions (openvuln/csaf/none) and netbox_filter get no explanation; only the four enum defaults are self-explanatory.

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 (render) and resource (Markdown or HTML report) and enumerates the report's contents: summary, per-device counts, findings with evidence and remediation snippets. That distinguishes it from a mere scan, though it never explicitly contrasts it with the sibling 'check' beyond deferring its arguments.

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 only guidance is 'Arguments as for check', which is a parameter-delegation note, not a when-to-use rule. Nothing tells the agent when to call report instead of check, or whether it is a follow-up step, a standalone scanner, or a superset of check.

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