Skip to main content
Glama

virustotal_report

Fetches VirusTotal v3 reports for IPs, domains, URLs, or file hashes to verify reputation and security risks.

Instructions

VirusTotal v3 report for an IP, domain, URL or file hash.

kind is auto|ip|domain|url|file. Requires VIRUSTOTAL_API_KEY (or VT_API_KEY, or a "virustotal" entry in ~/.config/osint-mcp/keys.json). Free keys allow about 4 requests/minute.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "target": "<target>"
    },
    "name": "virustotal_report"
  }
}

Input Schema

NameRequiredDescriptionDefault
kindNoauto
targetYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv2.0.0

TDQS

A3.5/5.0
Behavior3/5

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

With no annotations, the description must carry behavioral disclosure, and it does supply two genuinely useful facts: the required API key (including fallback sources) and an approximate free-tier rate limit of ~4 requests/minute. It omits important behavior for this tool class, notably whether a URL/file lookup merely queries or actually submits the sample to VirusTotal (a privacy-relevant side effect), and what happens on unknown indicators or quota exhaustion.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the purpose, then parameter semantics, then operational prerequisites. Every sentence carries information, though the parenthetical listing of three key sources is slightly verbose relative to its value for a calling agent.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple (two params, no annotations, no output schema), so the bar is modest, and auth plus rate-limit disclosure covers the biggest operational risk. Still missing are the shape of the returned report and the submission side-effect question, which matter for an enrichment tool whose output feeds further analysis.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description must explain both parameters, and it largely does: it enumerates the meaningful `kind` values (auto|ip|domain|url|file) that the bare string schema does not, and defines `target` implicitly through the indicator-type list. The only gap is that it never states that `target` is required or what format a file hash should take.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a concrete verb and resource ('VirusTotal v3 report') plus the exact indicator types it accepts (IP, domain, URL, file hash), so an agent can immediately tell this is a reputation lookup against VirusTotal. It does not explicitly distinguish itself from sibling lookups such as dns_lookup or asn_lookup, which is the only thing keeping it from a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied by the indicator types and by the `kind` value list, which effectively tells the agent how to select the lookup mode or let it auto-detect. There is no explicit guidance on when to prefer this over another enrichment tool, nor on what to do when the target type is ambiguous or the indicator is unknown to VirusTotal.

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