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 it does disclose two useful behaviors: the specific local data sources (cvelistV5 delta, CISA KEV, EPSS) and the guarantee that no network access is needed. It also reveals a write side effect ('fill the ToDo list'). However, it does not say whether existing ToDo entries are overwritten or appended, what permissions are required, or how much work the match entails.

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, zero filler, and the core action and its inputs are front-loaded before the network-free guarantee. Every clause carries information.

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 never says what the call returns or how the ToDo list is affected beyond 'fill it'. For a tool that mutates ToDo state with no annotations to cover safety or idempotency, more disclosure would be warranted.

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 both booleans (refresh, with_epss) are already fully documented in the schema, including the default for with_epss. The description adds no additional meaning about them, which is the expected baseline when the schema does the work.

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 names a concrete verb (match) plus the two operands (stored inventory vs. local CVE sources) and the resulting side effect (filling the ToDo list). That is far more specific than the sibling names alone, though it never explicitly contrasts itself with scan_inventory, which an agent could plausibly confuse it with.

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 the situation (post-inventory matching against local CVE data) but never states when to call this versus scan_inventory, assess_todo or cve_detail, nor any prerequisite or ordering. Usage is inferable from context rather than stated.

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 one real side effect: it sets the status to 'assessed' (or 'dismissed' per the dismiss param). It says nothing about permissions, idempotency, whether an existing assessment is overwritten, or what a successful write returns.

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, no filler, and the action is front-loaded before the status side effect. The only dead weight is the unexplained parenthetical about the non-sampling path.

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?

This is a mutation tool with eight parameters (five required), no annotations, and no output schema, so the description needs to do more work. It never explains the relationship to assess_todo, the sampling distinction, or any failure/authorization behavior, leaving significant gaps for a write operation.

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 the eight parameters and their meanings are already fully documented in the schema. The description adds no syntax, format, or defaulting 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 states a specific verb and resource ('Write an effort assessment back to a to-do'), which is concrete enough to act on. However, '(the non-sampling path)' is internal jargon that does not help distinguish this tool from the sibling assess_todo, leaving the core purpose only partially differentiated.

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 and no mention of the obvious alternative assess_todo. The parenthetical '(the non-sampling path)' is an implicit hint about differing execution modes, but it is not explained, so an agent cannot reliably choose between the two.

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.