isMalicious threat intelligence for AI agents

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?

Annotations already declare readOnly, idempotent, and openWorld, so the safety profile is covered. The description adds genuinely non-structured context: the monthly quota cost of one request and the specific evidence categories returned, which helps an agent decide whether the call is worth spending.

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 waste: the returned payload is front-loaded, followed by the routing constraint and the quota cost. Nothing is padded or repeated from the schema.

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 return fields, and it discloses the quota cost and routing constraint. For a single-parameter read tool, an agent has everything needed to call it 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 description coverage is 100% and the id parameter is fully documented with a regex pattern and example, so the baseline is 3. The description adds no syntax or format detail 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+resource ('One CVE by id') and enumerates the exact data returned (CVSS, EPSS, KEV status/due date, exploitation evidence, dates, references). It is clearly distinguishable from sibling list/scan tools like recent_cves or check_indicator.

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?

'This is the only CVE lookup path; do not guess other routes' explicitly tells the agent not to invent alternative routes, which is strong routing guidance. It stops short of naming when to prefer recent_cves for browsing versus this tool for a known ID.

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 and idempotentHint, but the description adds non-obvious behavior: a hard cap of 20 items, the exact fields returned, and that each call consumes one request of the monthly quota. The quota cost is genuinely useful context an agent cannot get from annotations, though pagination/empty-result behavior is not addressed.

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 with no filler: what it returns and ordering first, then return shape, then the routing hint and cost. Every sentence carries distinct information and the most decision-relevant facts are front-loaded.

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 read tool with no output schema, the description supplies the missing return contract (id, severity, CVSS, publication date, title), the result cap, and the quota cost, which is everything an agent needs to call and interpret it 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 description coverage is 100%, so both limit (default 10, max 20) and severity (enum of CRITICAL/HIGH/MEDIUM/LOW) are fully documented in the schema. The description restates the severity filter and the 20-item cap but adds no syntax or semantics beyond that, 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?

States a specific verb+resource ('Most recently published CVEs'), the ordering ('newest first'), and the optional severity filter, so an agent knows exactly what it returns. It also names the sibling get_cve as the detail-fetching counterpart, making it distinguishable from the other lookup tools.

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 explicitly routes follow-up work ('Follow up with get_cve for details'), which tells the agent to use this for discovery and get_cve for depth. It gives clear context but no explicit when-not-to-use case (e.g., searching by keyword or product, which search_indicators may cover).

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.