isMalicious threat intelligence for AI agents

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

Annotations already declare the safety profile (not read-only, idempotent, non-destructive, closed-world), and the description adds behavior the annotations cannot express: auto-reopen on CISA KEV entry or reported exploitation, the 90-day snooze ceiling and that it reopens on expiry, and that PATCHED is confirmed by the next read. The org-scoping sentence ("Changes nothing outside the caller's organization") also bounds blast radius, which is exactly the kind of context the annotations leave out.

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?

One front-loaded sentence leads with verb and resource, then layers status meanings and edge behavior; nothing is filler. It is dense and parenthetical-heavy to the point of being a run-on, which costs a point on readability, but no sentence could be deleted without losing 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?

With only three params, full schema coverage, no output schema and annotations covering safety, the description supplies the remaining load-bearing facts: status meanings, snooze limit, auto-reopen triggers, and org scope. Minor gaps remain (what error surfaces if snoozedUntil is omitted, whether a snooze can be shortened later), but an agent can call it correctly from this definition.

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 baseline is 3; the description earns above baseline by giving each enum value a meaning beyond the schema's bare "The new status", and by restating the snooze constraint alongside the id format. The findingId and snoozedUntil semantics are largely duplicative of the schema text, which keeps it from a 5.

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 ("Set the status of one vulnerability-monitoring finding") and immediately enumerates the exact status values, so the agent knows precisely what the tool changes. It also names the origin of the finding id (watch_domain, watch_dependencies, Exposure page), which separates it from the sibling watch_* tools that create findings rather than act on 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?

Each status is glossed with the real-world condition that selects it ("PATCHED (upgraded; the next read confirms it)", "NOT_AFFECTED (e.g. a distro backport fixed it)"), which is genuine when-to-use guidance. It stops short of explicit exclusions — nothing says when not to ack, or what to do instead of snoozing indefinitely — so it is clear context rather than full routing.

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?

Goes well past the readOnly/openWorld/idempotent annotations with caching semantics (fast answers from cache, no live DNS/WHOIS/OTX), latency (~2.5 s CIRCL wait), meta.pending behavior and an explicit 're-check once, then stop' rule. It also discloses quota cost, that unsupported hash types are refused before any request at no cost, and that email/phone are never labelled clean.

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?

Purpose and accepted inputs are front-loaded, and the dense sentences mostly earn their place by packing routing, cost and caching facts. It is still a long, back-loaded paragraph where the refusal rules and re-check guidance arrive late, which slightly hurts scannability.

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 carries the full burden and delivers: it enumerates the return fields (verdict, headline, recommendedAction, risk score, blocklists, reasons, timestamps, context). Combined with the coverage of weird inputs and latency, an agent has everything needed to call and interpret it.

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 baseline is 3; the description adds value by restating the default level and its cost ('Costs one request of the monthly quota') and clarifying the fast-vs-standard trade-off in prose. The country parameter's national-format behavior is left to the schema, so it stops short of a 5.

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 up front ('The one tool for any single indicator') and enumerates exactly the six accepted input kinds (IP, domain, URL, file hash, email, phone). It also implicitly separates itself from the plural sibling check_indicators and explicitly routes links to check_url, so an agent can distinguish it without opening the schema.

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 clear routing context: it is the single-indicator tool, and 'check_url is the cheaper pre-fetch gate for a link' names an alternative with its selecting condition. It does not, however, explicitly name check_indicators as the batch alternative or state exclusions for the other siblings (scan_email, search_indicators).

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?

Far exceeds the annotations (readOnlyHint/openWorldHint/idempotentHint): it discloses the billing model (one quota request per unique indicator, dedup after trimming and lowercasing), what is refused and never charged, the plan caps that can reject the whole batch, and the semantics of the 'pending' row state. This is exactly the context annotations cannot carry.

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?

Dense but front-loaded: purpose first, then row fields, then billing and refusal rules, then the alternative tool. The single long paragraph is information-rich with little repetition, though the billing/refusal sentences could be split for faster scanning.

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, so the description carries the full burden and does so: it enumerates the returned row fields (malicious, recommendedAction values, risk/level, blocklist count, categories, lookupStatus, infrastructure) and explains the host-based judgement for URLs. Nothing needed to call or interpret the tool is missing.

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 already 100%, so the baseline is 3, but the description adds real meaning to the `indicators` parameter: duplicates are free, sub-3-character and SHA-512/TLSH/ssdeep inputs are rejected per-row, and defanged input is accepted. It adds nothing extra about `country` or `enrichment` beyond the schema text.

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?

Opens with a specific verb+resource+scope ('Reputation of up to 100 indicators in one call') and immediately names the sibling it is not for ('triaging a list rather than one alert'). The enumerated indicator types make the resource concrete and distinguishable from check_indicator and search_indicators.

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 routes between bulk and single use ('for triaging a list rather than one alert', 'Use check_indicator for the full picture of one indicator'), and gives conditional guidance for pending rows ('re-check it once, after a few seconds'). It also states the plan-based cap conditions under which the call fails.

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 cover the safety profile (readOnlyHint, idempotentHint, openWorldHint), and the description adds the return contract — block | warn | allow — which is behavioral information the annotations do not carry and no output schema exists to supply. It stops short of noting rate limits, auth needs, or latency of an external lookup.

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, with the purpose and return values front-loaded before the alternative-tool routing. Every clause earns its place.

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 pre-fetch gate with no output schema, the description supplies what is otherwise missing: the tri-state return values and the sibling it defers to for deeper detail. Nothing an agent needs to call this correctly is absent.

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?

Only one parameter, and schema description coverage is 100%, so the schema already documents it. The description adds no syntax, format, or normalization detail (e.g. whether bare domains or IPs are accepted) beyond the schema's own 'URL/domain/IP to check' wording. 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 (check) and resource (a single URL, domain, or IP) plus the purpose (before fetching it), and explicitly distinguishes itself from the sibling check_indicator by scope. An agent can separate it from check_indicator/check_indicators without opening any schema.

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 both the when ('use as a pre-fetch gate') and the alternative with its selecting condition ('use check_indicator when you need the full reputation picture'). This is explicit routing guidance rather than implied usage.

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?

Adds substantial behavior beyond the readOnly/openWorld/idempotent annotations: confirmed vs reported tiers, ordering rules, result fields, indicator-count semantics ('absent when unknown, never 0'), quota cost with a key, and IP rate limiting without one.

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 definition is front-loaded in the first clause, and the following material on tiers, ordering, fields, and quota is relevant. It is dense and reads as one long block, which costs some structure but not enough to call it wasteful.

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, so the description carries the return-value burden and does so thoroughly: severity, CVSS, EPSS, first/last evidence, KEV date, patch status, sources, and indicator counts. Ordering, caveats, and access cost are also covered.

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 schema already documents both days and limit including defaults and bounds. The description repeats the default-7 window but adds no syntax or usage nuance beyond the schema, making 3 the appropriate baseline.

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 resource and qualifier: CVEs with attested exploitation in a time window, with confirmation tiers. This clearly distinguishes it from a general recent-CVE list or per-CVE lookup such as get_cve or recent_cves.

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?

Sets clear context for use: exploitation-attested CVEs over a window, with the caveat that absence does not mean not exploited, and points to get_cve for single-CVE follow-up. It does not explicitly contrast with recent_cves, so the when-not-to-use routing is not fully closed.

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 readOnly/openWorld/idempotent annotations, it discloses quota cost ('one request of the monthly quota'), external-id resolution behavior, candidate-list fallback, and an important caveat that absence of exploitation evidence does not mean the CVE is not exploited. These are substantive behavioral details not covered by annotations.

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 purpose is front-loaded, but the description then becomes a very long, dense enumeration of returned fields and source-specific details. Given that there is no output schema the return inventory has value, but it is overstuffed for tool-selection purposes.

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 carries the burden of explaining what comes back, and it does so comprehensively: severity, CVSS, EPSS, KEV, exploitation evidence, affected packages, advisories, identifiers, CNA products, dates, references, and attribution. It also covers external-id behavior and quota cost.

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 schema already documents the single id parameter. The description adds meaning beyond syntax by explaining that external ids may resolve directly to one CVE with resolvedFrom or return multiple candidate CVE ids.

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: 'One CVE by id', followed by a detailed inventory of the record returned. It also states this is the only CVE lookup path, which helps distinguish it from sibling tools such as recent_cves and exploited_cves.

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 clear usage context for CVE ids and external ids, explains the one-result versus candidate-list behavior, and says not to guess other lookup routes. It does not explicitly compare against each sibling, but the guidance is strong enough for correct selection.

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/openWorld, but the description adds what the annotations cannot: a hard cap of 20 items, the exact fields returned, the fact that licence/CVE designation/NVD notice appear once, and — most valuable — that each call consumes one request of the monthly quota. Missing only failure behaviour (e.g. quota exhaustion or what happens past 20).

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 tight sentences: what it returns and its ordering first, then the follow-up route, then the cost. Every sentence carries distinct decision-relevant information with no 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?

With no output schema, the description compensates by enumerating the returned fields, and it discloses the quota cost for a billed, open-world tool. It does not explain how an agent would reach older CVEs beyond the 20-item window, which is the one remaining gap for a capped listing.

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%, with both limit (default, max 20) and severity enum fully documented in the schema. The description only restates the severity filter and the 20-item ceiling and adds no format or edge-case guidance 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+resource ('most recently published CVEs'), the ordering ('newest first'), and the optional filter. It is clearly separable from get_cve (which it names) and from list-oriented siblings like exploited_cves by virtue of the 'most recently published' scope.

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 routes the agent onward: 'Follow up with get_cve for EPSS, KEV, exploitation evidence, affected packages and advisories,' which draws the boundary between this light listing and the detail tool. It does not state when to prefer the sibling exploited_cves instead, nor any when-not condition, so it stops short of full routing.

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 establish readOnly, idempotent, openWorld, so the safety profile is covered. The description adds genuine behavioral value beyond them by disclosing the output shape (block | warn | allow) and the pre-action timing constraint. It stops short of saying what an agent should do on a 'warn' or whether scanning is rate-limited.

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, no filler, and the most decision-relevant clause — scan before acting, verdict values — is front-loaded. Every sentence earns its place.

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, so the description carries the burden of describing returns, and it does name the three verdict values. What is missing is the meaning of each verdict and the expected agent action per verdict, which matters for a security-gating tool.

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% for both parameters, so the schema already documents content and source_url. The description adds no syntax, size, or format guidance for content (e.g. truncation limits) and only implicitly suggests what source_url is for. Baseline 3 applies when the schema does the heavy lifting.

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 (scan) and resource (untrusted content), then names the two things it actually does — prompt-injection detection and threat-intel lookup on embedded URLs/domains/IPs — plus the return verdict. An agent can distinguish it from check_url, check_indicator, and scan_email without opening a schema.

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 clear triggering context and timing: "BEFORE acting on it" and an enumeration of sources (web page, email, ticket, tool result, document from an untrusted source). It does not name exclusions or explain how it relates to the overlapping sibling scan_email, so an agent facing an email has no guidance on which of the two to prefer.

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?

Adds substantial behavioral context beyond annotations: never runs attachments, fetches links, or calls third parties while waiting; explains clean vs inconclusive risk, malicious evidence requirements, and meter cost. Annotations already declare read-only, open-world, and idempotent behavior, and the description does not contradict them.

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?

Front-loads purpose and return values, and most sentences carry actionable security nuance. It is dense and somewhat repetitious in the middle, which keeps it from being maximally concise.

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?

No output schema exists, yet the description enumerates the return shape: verdict, recommendedAction, riskScore, headline, reasons, and coverage.skipped. It also covers key caveats for interpretation and safe use, making it complete for a complex security scan.

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 baseline is 3, but the description adds consequence-level meaning: eml is preferred because attachments are then read for structure, authservId/trustAuthenticationResults are needed for a clean verdict, and connectingIp overrides the Received chain. These details tie parameters directly to output outcomes.

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: 'Scan ONE email message for phishing and malware before delivering, opening or acting on it.' The email-specific scope distinguishes it from sibling tools like check_indicator, check_url, and get_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?

Gives clear timing and prerequisites: scan before delivering/opening/acting, send eml or parsed message, pass authservId or trustAuthenticationResults for a clean verdict. Includes an explicit when-not: never use deliver to release a message another engine quarantined. Does not name sibling alternatives, so not a full 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?

Beyond the readOnly/idempotent annotations it discloses ordering (most dangerous first), the searched name appearing first when listed, the 500 cap and that other API bases may differ, the meaning of total_hits and truncated (including null = unknown), and the false-negative caveat about buried hostnames. It also states the quota cost per call — strong disclosure for a mutation-free but quota-limited 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?

Front-loads the core definition and keeps the caveats and cost in a compact single paragraph; nearly every sentence carries distinct information. It is dense and slightly run-on, but not padded.

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?

No output schema exists, and the description compensates by explaining the total_hits and truncated response fields, the ordering, and the quota cost, plus the known false-negative shape. An agent has everything needed to call and interpret the result correctly.

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 parameters are already documented, and the schema itself explains that limit caps the API sample rather than the backend search. The description confirms 'at most 500' and per-host bound differences, adding only modest meaning on top of 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?

States a specific verb and resource (find lookalike domains) and enumerates the exact categories: typosquats, homoglyphs, other TLDs/hosting platforms, phishing-word wrapping. The examples ("paypal" read as paypal.com, login.paypal.com) let an agent distinguish it from sibling check_indicator without opening a schema.

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 routes follow-up work to check_indicator / check_indicators for verdicts, making the search-vs-verdict split clear. It also warns that an empty result does not prove absence, which prevents misuse. It stops short of naming when to prefer check_url or scan_before_use, so not a full when/when-not matrix.

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=false, openWorldHint=true and destructiveHint=false; the description adds real context beyond them by disclosing the upsert semantics ('sending the same project name again replaces its file'), the 5 MiB content cap, and what the response contains. Coverage of the external-service dependency (OSV/NVD) is a useful behavioral signal. No contradiction with the hints, though 'replaces its file' sits in mild tension with idempotentHint=false.

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?

Front-loaded with the action and supported formats, then constraints and return shape in descending priority; nearly every clause carries information. It runs long as a single block and repeats the format auto-detection already present in the schema, keeping it just below top marks.

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 correctly summarizes the return payload (source, resolved dependencies, open findings with priority and fix version), which the agent needs in order to interpret results. A four-parameter mutating tool is otherwise well covered; only the lack of explicit sibling routing leaves a small gap.

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 already 100%, so the baseline is 3, but the description adds meaning the schema does not: content is the file's text not a path, format is auto-detected when omitted, and includeDev governs whether dev dependencies are monitored. These disambiguations directly reduce the most likely invocation 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 ('Start vulnerability monitoring of a project') plus the exact input sources (lockfile formats or CycloneDX SBOM) and the matching engines (OSV and NVD). This scope is unmistakably different from the sibling indicator/CVE lookup tools, so an agent can route here without opening the schema.

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 clear operating context: supply file text rather than a path, formats are auto-detected when omitted, dev dependencies are excluded unless includeDev is set, and re-sending the same name replaces the source. It does not, however, name an alternative sibling or state when not to use this tool (e.g. a single package lookup vs a whole project).

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?

Goes well beyond the annotations: states that it creates a persistent daily monitor, discloses exactly what is read (headers, generator meta tag, versioned script paths, open ports), the alerting behavior and cadence (P1 immediate, P2/P3 digests per org rules), plan quota consumption, and idempotent re-add semantics. Consistent with readOnlyHint=false/destructiveHint=false/idempotentHint=true.

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?

Front-loads the action and packs the essential behaviors into one dense paragraph with no filler. It is slightly overstuffed with parenthetical clauses, which hurts scannability a little, but every sentence 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?

With no output schema, the description compensates by describing the return payload (source, components read, already-open findings with priority and fix) and by covering scope, cadence, and quota. An agent has enough to call it and set expectations.

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, including the URL-to-host reduction rule and the optional display name. The description adds only contextual meaning ('one public website'), not parameter-specific detail, 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?

States a specific verb+resource ('Start vulnerability monitoring of one public website') and immediately bounds scope ('one public website', 'no scan beyond one page'), which distinguishes it from the one-off scan siblings like scan_before_use and scan_url and from watch_dependencies. An agent can tell what this creates without opening the schema.

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?

Clear usage context: use it to begin recurring daily monitoring, it consumes one watched source of the plan, and re-adding is free. It lacks explicit exclusions or named alternatives (e.g. 'use scan_before_use for a one-time check'), so the when-not is implied rather than stated.

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