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

With no annotations, the description carries the full burden, and it does disclose non-obvious dual-mode behavior plus the fact that a verdict is stored (a mutation). It omits what the evidence package contains, what happens to a previously stored verdict, and what permissions or preconditions the write requires.

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 tightly written sentences, with the core function front-loaded and the branching behavior second. No filler, but the undefined 'axes a-d' shorthand costs a little clarity within that compact frame.

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, no annotations, and the tool performs a write (stores the verdict), so the description should carry more: what the evidence package looks like, how the assessment is consumed downstream, and what 'axes a-d' means. It covers the branching model well but leaves the payload and result semantics undefined.

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 100% and the single `todo_id` parameter is documented as 'The id from list_todos', so the schema does the work. The description adds no format, provenance, or validity detail beyond what the schema already states; baseline 3 applies.

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?

Names a specific verb+resource ('Effort assessment for one to-do') and hints at sibling differentiation by naming `save_assessment`. However, 'axes a-d' is unexplained jargon that an agent cannot act on without outside knowledge, so it is clear but not fully self-contained.

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?

Explains the two operating contexts: sampling-capable clients get the verdict stored directly, others receive an evidence package destined for `save_assessment`. That routing is genuinely useful, though it never states when an agent should avoid this tool or whether re-assessment is expected.

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 per-product cache reuse, that the network is touched only for changes, NVD rate-limit pacing on a cold keyed start, background queue draining, and that the `completeness` field must be checked. The only blemish is the internally tense claim 'Never requires the network' immediately followed by network-touching behavior, which muddies an otherwise strong 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?

The primary action is front-loaded and the sentences are information-dense. There is mild redundancy: the 'read completeness before concluding' caveat is repeated as 'see completeness.status "incomplete"', and the closing sentence partly restates the earlier rate-limit 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 tool with no annotations and no output schema, the description is unusually complete: it names an output field (`completeness`) with a status value and warns about cold-start latency. It still leaves the ToDo list structure and overall return shape unspecified, which keeps it short of a 5.

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 100% and both parameters (refresh, with_epss) are documented in the schema, so the baseline is 3. The description hints at cache freshness and source re-download behavior but does not add syntax or mapping beyond what the schema already provides.

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 ('Match the stored inventory against the CVE sources') plus the effect ('fill the ToDo list'), so the agent knows exactly what it does. It implicitly separates itself from cve_detail (bulk per-product matching vs. single lookup), but it never names a sibling 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?

Usage is only implied: run this to populate the ToDo list from stored inventory. There is no explicit when-to-use versus cve_detail/scan_inventory and no stated prerequisites, so guidance is adequate but not directive.

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 supplied, so the description carries the full behavioral burden. It does disclose the useful trait that results are 'cached for a day,' but it is silent on NVD rate limits, behavior for unknown/invalid CVE ids, and whether auth or a key is required.

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 sentence that front-loads the verb, resource, source, and return fields, then appends the caching caveat. Nothing is wasted.

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 one-parameter lookup with no output schema, the description tells the agent what data comes back (description, CVSS, references) and notes caching. Only edge-case behavior (invalid ids, rate limiting, auth) is left uncovered.

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 schema description coverage at 100% and only one parameter, the schema already documents cve_id, its pattern, and an example. The description adds no format or semantics beyond that, so the baseline 3 applies.

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?

It gives a specific verb (look up), a scoped resource (a single CVE), the upstream source (NVD API 2.0), and the returned fields (description, CVSS, references). The word 'single' implicitly separates it from the bulk-checking sibling check_cves, though no sibling is named explicitly.

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: 'a single CVE' suggests this is for one-off lookups rather than batch checks like check_cves, but there is no explicit when-to-use/when-not-to-use statement or prerequisite detail.

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 behavioral burden. It describes the returned fields but omits whether the call is read-only, what happens when nothing matches, and how the 'one inventory entry' framing squares with the schema's multi-match 'limit' parameter (default 10, max 50) and the with_cves toggle — a real ambiguity for a lookup tool.

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 that names the subject first and then lists the returned content. It is efficient and contains no filler, though it spends its words on return values rather than the invocation guidance an agent also needs.

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 no annotations, so the description is the only source of behavioral context, and it only partially covers this. The return composition is sketched, but match/multiple-match behavior, defaults, and failure modes are left to the schema or entirely unstated.

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 100%, so limit, program, and with_cves are already fully documented in the schema with defaults and constraints. The description adds no parameter-level detail beyond implying CVE inclusion, so the baseline 3 applies.

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 ('Detail view of one inventory entry') and enumerates the payload (sources, paths, versions, CVEs), which is far more informative than the bare title 'Get program'. It does not name or differentiate itself from siblings like scan_inventory or cve_detail, though, so an agent must infer the boundary 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?

There is no explicit when-to-use guidance or mention of alternatives such as scan_inventory or cve_detail. The phrase 'Detail view' weakly implies this is the drill-down counterpart to a scan, but nothing states when to prefer this tool or what input form (name substring vs exact id) is appropriate.

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 supplied, so the description carries the behavioral burden. It does disclose the non-obvious sort order (confirmed-KEV, then confirmed findings, then severity/EPSS), which is real added value, but says nothing about permissions, pagination, or the shape of the returned entries.

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 short sentences with no filler; the priority ordering — the most decision-relevant fact — leads the description, and filtering is appended compactly.

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 annotations and no output schema, the description should carry more. It explains ordering and filtering but omits what a returned to-do actually contains (CVE id, status, KEV flag) and how the KEV-first sort interacts with the kev_only filter.

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 100% and each parameter is fully documented (limit default 40, status enum with a default, kev_only boolean). The description's 'filterable by status' merely restates one schema field and adds no syntax or semantics beyond it, so baseline 3 applies.

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 names the resource ('The CVE to-do list') and its ordering, which combined with the verb in the tool name makes the operation unambiguous. It distinguishes itself from siblings like assess_todo or reset_todos by being the enumeration tool, though it never explicitly contrasts them.

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?

'Filterable by status' plus the stated priority ordering implies this is the triage/entry-point read for a vulnerability queue, but the description gives no explicit when-to-use, when-not-to-use, or pointer to an alternative such as scan_inventory or check_cves.

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. It does disclose the destructive outcome ('back to empty', entry 'reset to open'), which is genuinely useful context, but it omits reversibility, whether confirmation is needed, and permissions.

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 tight sentences, front-loaded with the primary action, followed by a short rationale. The trailing 'without editing the JSON file' clause is mildly redundant but does justify the tool's existence.

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?

A simple one-optional-parameter tool with no output schema; the description covers both call modes adequately. A brief note on whether the reset is recoverable would make it fully 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 100%, so the todo_id semantics (omit or "*" for full clear) are already fully documented in the schema. The description restates the two modes but adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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 names a specific verb ('clear', 'reset') and resource ('to-do list'), and distinguishes its two operating modes: wiping the whole list vs. resetting one entry to open. It does not explicitly differentiate itself from siblings like list_todos or save_assessment, but the intent is 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?

It gives a clear context for use: getting back to a clean list without hand-editing the JSON file. There is no explicit when-not-to-use clause and no named alternative sibling, which keeps it 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?

With no annotations, the description carries the full burden, and it does disclose the core side effect: status is set to 'assessed' (with 'dismissed' available via schema). It does not say whether this overwrites an existing assessment, requires prior assessment, is idempotent, or what errors can occur.

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 short sentences, zero filler, with the mutation and its resulting state change front-loaded. Nothing is wasted and the key effect is stated first.

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 an 8-parameter mutation tool with no annotations and no output schema, the description covers the write and status outcome but omits prerequisites (must the to-do be previously assessed?), return/error behavior, and what 'non-sampling path' actually governs. The rich schema compensates on parameters, but the behavioral envelope is thin.

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 100%, so all 8 parameters including the (a)/(b)/(c)/(d) tokens, confidence default, and dismiss flag are documented in the schema itself. The description adds no syntax or meaning beyond that, so the baseline 3 applies.

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: writing an effort assessment back to a to-do, plus the resulting status change. The parenthetical '(the non-sampling path)' hints at a distinct route versus a sampling sibling, though it does not name that sibling explicitly.

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 non-sampling path' implies an alternative exists, but the description never names it or states when to pick this tool over it. Usage is implied (writing back a non-sampled assessment) rather than explicitly bounded.

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 behavioral burden. It discloses the mechanics (three sources read) and the return shape (per-source counters plus deduplicated result), but says nothing about whether the stored inventory is overwritten, how long the scan takes, whether winget/portable scanning needs network or elevated permissions, or what happens on partial failure.

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 tight sentences, front-loaded with the action and scope, followed by the return summary. Every clause earns its place; no filler or restatement of the tool 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 no output schema, the description does the right thing by summarizing return values, and it covers both optional parameters' domains. The remaining gap is side-effect/permission context for a refresh operation that mutates stored inventory state, which matters more given the absence of annotations.

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 100%, so both parameters are already documented in the schema and the baseline is 3. The description usefully connects the 'portable .exe scan' wording to the `roots` parameter and enumerates the three source names matching the `sources` enum, but adds no default or format detail 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?

Specific verb+resource: 'Refresh the installed-software inventory', with the three data sources named concretely (registry, winget list, portable .exe scan). That is far clearer than a bare 'scan', though it never names a sibling to distinguish itself from get_program or check_cves, which also touch installed software.

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?

'Refresh' implies the use case (re-sync a stale inventory), but there is no explicit when-to-use statement, no exclusion of alternatives, and no note on how this differs from get_program (single lookup) or check_cves. Usage is only inferable.

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