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

Annotations already declare readOnly, idempotent and non-destructive, so the description earns credit for adding what they don't cover: an error is returned when no report exists, 'latest' implies versioned reports with older ones superseded, and the required 'aegis:read' scope is an auth prerequisite. Return payload details are rightly omitted since an output schema exists.

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?

Four short sentences, front-loaded with the action and scope, then ordering guidance, then failure mode. No redundant restatement of the title or annotations.

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-parameter read tool with an output schema and full annotations, the description covers purpose, timing, failure mode, and permissions. The remaining gap is where the agent obtains a valid incident_id, which is the one thing an agent could get wrong when calling this.

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 only parameter, incident_id, is undocumented in the schema. The description only says 'for an incident id' and does not add format, provenance (presumably the id returned by triage_incident), or what happens with an unknown id beyond the generic no-report error.

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: 'Read the latest persisted triage report for an incident id.' The word 'persisted' plus 'latest' distinguishes it from the sibling triage_incident, which produces reports rather than reading 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?

Gives concrete ordering guidance ('Use after triage_incident, or to resume an investigation'), which tells the agent when this is the right call. It stops short of an explicit exclusion, such as telling the agent to run triage_incident instead when no report exists yet.

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 read-only, idempotent, open-world behavior, yet the description adds genuinely new operational context: untrusted external feed text that must not be treated as instructions, the aegis:read scope requirement, NVD rate limits, and brief caching. The determinism guarantee and per-factor breakdown also tell the agent what kind of result to expect beyond the annotation set.

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?

Four dense sentences, front-loaded with what the tool does, followed by usage, safety, scope, and rate-limit notes in that order. Every sentence carries actionable information with no restatement of the title or 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?

For a two-parameter lookup with an output schema, the description covers purpose, security posture, scope, and operational constraints thoroughly, so return-value detail is rightly omitted. The one real hole is the undocumented asset_criticality input, which materially changes the score and is left entirely 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 description coverage is 0%, so the description must carry parameter meaning, and it does not. asset_criticality is never mentioned at all, leaving the agent unaware that this input presumably weights the risk score, and cve_id gets only an indirect nod ('when the CVE id is already known') while the actual format constraint lives in the schema pattern.

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 ('Enrich a single CVE') and enumerates the exact data sources merged (NVD CVSS, FIRST EPSS, CISA KEV) plus the output (0-100 risk score with per-factor contributions). This clearly separates it from the sibling search_vulnerabilities, which implies multi-result discovery rather than a single-CVE enrichment.

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?

'Use when the CVE id is already known' gives an explicit precondition and implicitly routes discovery work elsewhere. It stops short of naming search_vulnerabilities as the alternative for the unknown-id case, so the routing is inferable 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint and destructiveHint=false, so the safety profile is covered and the description's "Read-only" is redundant. What it adds beyond annotations is the required scope ("aegis:read") and the behavioral consequence of omitting versions (advisory listing rather than precise matching). Output shape is also noted, though an output schema exists.

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 core capability is front-loaded in the first sentence, followed by return contents, safety, scope, and a caveat. Every sentence carries information, though the ecosystem list and "Read-only" partially duplicate the schema enum and annotations.

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 a rich schema, full description coverage and an output schema, the only things the description must supply are scope, external dependency (OSV.dev) and version-matching caveat, all of which are present. Minor gaps: no mention of the 20-package cap, error behavior, or how results map back to each queried package.

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 nested PackageQuery fields, the ecosystem enum and the version default are already documented. The description reinforces the package/version pairing semantics and the ecosystem scope but adds no new constraints beyond the schema, such as the 20-item batch limit or behavior on partial matches.

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 gives a specific verb and resource ("Query OSV.dev for vulnerabilities affecting one or more package/version pairs") and enumerates supported ecosystems, so the agent knows exactly what the tool does. It does not explicitly distinguish itself from siblings like lookup_cve or search_vulnerabilities, forcing the agent to infer the boundary from the package-oriented framing.

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 rather than stated: the agent can infer this is the batch/package-oriented scan versus a single-CVE lookup, but no sibling is named and no when-not-to-use condition is given. The one real guideline is "Caller must supply installed versions for precise matching," which is useful but narrow.

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, openWorldHint and destructiveHint=false, so the 'Read-only' sentence is redundant. However, the description adds genuinely new behavior: the required scope 'aegis:read', the upstream NVD rate limit with guidance to use precise keywords and small limits, and the enrichment/ranking pipeline that explains what the results represent.

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?

Five short sentences, front-loaded with the core operation and pipeline, then filters, then usage routing, then operational constraints. Nothing is padding except the 'Read-only' line, which is a small overlap with the annotations rather than 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?

A machine-readable output schema exists, so return values need not be described; the description still usefully explains that results are enriched and risk-ranked. The main gap is the unmentioned asset_criticality parameter and how it affects ranking, which an agent would need to know to get sensible ordering.

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 only 40%, so the description has to compensate, and it does for most parameters: keyword precision, limiting result count, the CVSS floor, and the KEV-only filter. It never explains 'asset_criticality', the one parameter that presumably drives the composite-risk ranking, leaving that enum's effect on ordering 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 names a specific verb and resource ('Keyword search over the NVD corpus') plus the processing pipeline (EPSS/KEV enrichment, composite-risk ranking). It also explicitly separates itself from a sibling by saying 'Use for discovery when no CVE id is known,' which implicitly points to lookup_cve.

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 usage context ('discovery when no CVE id is known') and documents two filtering modes plus a rate-limit caution. It would reach a 5 if it named lookup_cve explicitly as the alternative for known-ID lookups rather than only implying 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 cover readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is free. The description earns credit for adding what annotations cannot: the required scope 'aegis:read' and the assurance that the endpoint exposes no secrets or principals, which an agent needs before deciding this is safe to surface. It does not discuss rate limits or latency, so it is short of a 5.

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?

Four short sentences, payload enumerated first, constraints after — well front-loaded. 'Read-only.' is redundant with readOnlyHint=true, but the repetition costs little and the rest of the text is dense with non-duplicated 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?

A parameterless read-only status tool with a full output schema and complete annotation coverage needs little more than this: what it returns, that it is safe, and what scope it needs. All three are present, so an agent could call it correctly on the first attempt.

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?

Zero parameters, so the baseline is 4 and there is genuinely nothing schema-side left to explain. The description correctly adds only scope and sensitivity framing rather than inventing parameter talk.

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 ('Return') and resource ('runtime status') and then enumerates the exact payload: version, transport, offline mode, cache size, circuit-breaker states, readiness. That enumeration makes it unmistakable against the sibling tools (lookup_cve, triage_incident, scan_packages), which all concern vulnerabilities and incidents rather than server state.

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 one concrete decision rule: 'Use to decide whether retries are appropriate.' That is a real when-to-use signal, not an implied one. It stops short of naming when-not-to-use or pointing to an alternative, but the siblings occupy a different problem space so there is little ambiguity to resolve.

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?

Beyond the annotations, it discloses concurrent collection, partial reports with explicit coverage after source failures or deadline expiry, required authorization scopes, and stored-report replay for identical requests. It also precisely explains the write behavior: a local report is persisted while upstream systems are never changed.

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 front-loads the workflow and then presents failure behavior, selection context, side effects, authorization, and replay semantics in a logical order. Although dense, each sentence contributes distinct operational information without 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 complex workflow, it covers orchestration, degraded operation, persistence, upstream safety, authorization, and idempotency, while the output schema can define the report structure. Clearer parameter-level guidance and explicit routing to narrower sibling tools 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?

With schema description coverage at only 14%, the description needed to compensate, but it mostly explains the workflow rather than individual arguments. References to identifiers, assets, CVE and package intelligence, and deadlines provide indirect cues, while incident_id's relationship to report reuse and asset_criticality's effect on scoring remain unexplained.

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 specifies a concrete incident-triage workflow, including intelligence gathering, correlation, scoring, prioritized actions, and report persistence. Its end-to-end incident scope clearly distinguishes it from narrower siblings such as lookup_cve, scan_packages, and get_incident_report.

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 explicit instruction to use it for a production incident affecting assets provides a clear selection context. It does not state when not to use it or direct agents to narrower siblings for simple CVE lookups, vulnerability searches, or package scans.

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