Threatfox

Search Hash

search_hash

Read-onlyIdempotent

Everything ThreatFox knows about one file hash (md5 / sha1 / sha256), across BOTH relations it stores hashes in — they are different facts and a caller with a hash in hand rarely knows which one they have. (1) sample_to_c2: the hash is a malware SAMPLE, and ThreatFox returns the botnet C&C servers that sample talks to (this is what abuse.ch's own search_hash query answers, and only this). (2) hash_listed_as_ioc: the hash is itself published as an indicator — threat_type "payload" — in which case the row IS the answer. matched_relation says which one fired, or is null when neither did. AN EMPTY RESULT IS A REAL ANSWER HERE, not a failure: ThreatFox is a C&C-tracking feed, not a sample database — most hashes on any malware site are in neither relation. It also expires every IOC older than six months, so a hash from an old report can legitimately return nothing today. For sample metadata (file type, size, signature, YARA) use the malwarebazaar pack, which is the same vendor and indexes every sample.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`hash`	Yes	md5 (32 hex), sha1 (40 hex) or sha256 (64 hex). Anything else is rejected upstream as illegl_hash [sic] rather than answered empty.

Output Schema

TableJSON Schema

Name	Required	Description
`count`	Yes	Number of results returned
`query`	Yes	The query type sent (search_hash)
`status`	Yes	Query status (ok, no_result, or null)
`results`	Yes	IOCs associated with the file hash
`matched_relation`	No	WHICH of ThreatFox's two hash relations answered. "sample_to_c2": the hash is a malware sample and the rows are the C&C servers it talks to. "hash_listed_as_ioc": the hash is itself published as an indicator (threat_type "payload") and the row IS the answer. null: neither matched - both were searched, see searched_relations.
`searched_relations`	No	Present only when nothing matched: the relations that WERE searched, so an empty answer cannot be mistaken for a partial lookup.

Schema Changelog

Changes observed during successful MCP inspections.

Changed4 schema fields changedSep 22, 2026

changedInput schema / examples

Previous value: -[
-  {
-    "hash": "d41d8cd98f00b204e9800998ecf8427e"
-  },
-  {
-    "hash": "356a192b7913b04c54574d18c28d46e6395428ab"
-  }
-]New value: +[
+  {
+    "hash": "2a85f2e5876b278a7af9393483de455b"
+  },
+  {
+    "hash": "da168c3ff95c749beec0a2f29a1e6b82"
+  }
+]

changedInput schema / properties / hash / description

Previous value: -"md5 / sha1 / sha256"New value: +"md5 (32 hex), sha1 (40 hex) or sha256 (64 hex). Anything else is rejected upstream as illegl_hash [sic] rather than answered empty."

addedOutput schema / properties / matched_relation

Added value: +{
+  "description": "WHICH of ThreatFox's two hash relations answered. \"sample_to_c2\": the hash is a malware sample and the rows are the C&C servers it talks to. \"hash_listed_as_ioc\": the hash is itself published as an indicator (threat_type \"payload\") and the row IS the answer. null: neither matched - both were searched, see searched_relations.",
+  "enum": [
+    "sample_to_c2",
+    "hash_listed_as_ioc",
+    null
+  ],
+  "type": [
+    "string",
+    "null"
+  ]
+}

addedOutput schema / properties / searched_relations

Added value: +{
+  "description": "Present only when nothing matched: the relations that WERE searched, so an empty answer cannot be mistaken for a partial lookup.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

Changed2 schema fields changedMay 22, 2026

addedInput schema / examples

Added value: +[
+  {
+    "hash": "d41d8cd98f00b204e9800998ecf8427e"
+  },
+  {
+    "hash": "356a192b7913b04c54574d18c28d46e6395428ab"
+  }
+]

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "properties": {
+    "count": {
+      "description": "Number of results returned",
+      "type": "integer"
+    },
+    "query": {
+      "description": "The query type sent (search_hash)",
+      "type": "string"
+    },
+    "results": {
+      "description": "IOCs associated with the file hash",
+      "items": {
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "status": {
+      "description": "Query status (ok, no_result, or null)",
+      "type": [
+        "string",
+        "null"
+      ]
+    }
+  },
+  "required": [
+    "query",
+    "status",
+    "count",
+    "results"
+  ],
+  "type": "object"
+}

First observedMay 13, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Annotations already provide readOnlyHint/openWorldHint/idempotentHint, but the description adds critical behavior beyond that: empty results are meaningful, IOCs expire after six months, the exact semantics of matched_relation (fired relation or null), and upstream rejection of invalid hashes. This is rich behavioral transparency that the annotations alone do not convey.

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?

The description is long but every sentence contributes substantive information: relation semantics, empty-result handling, expiry, and alternative routing. The opening sentence front-loads the overall scope, and the numbered relations make the structure readable. Some formatting noise (ALL CAPS, em-dashes) adds mild friction, but the content density justifies the length.

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

Completeness5/5

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

Given a single well-documented parameter, an output schema, and comprehensive annotations, the description fully covers the two relation semantics, matched_relation behavior, empty-result meaning, expiry, and when to use an alternative tool. Nothing needed for correct invocation or interpretation is missing.

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

Parameters3/5

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

Schema coverage is 100%, and the hash property in the schema already documents accepted formats (md5/sha1/sha256) and the rejection behavior. The description adds conceptual context about what the hash may represent (sample vs IOC) but does not extend parameter syntax or constraints beyond the schema. Baseline 3 is appropriate.

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

Purpose5/5

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

States 'Everything ThreatFox knows about one file hash' and explicitly enumerates the two stored relations (sample_to_c2 and hash_listed_as_ioc), making the tool's scope unmistakable. It also contrasts with the malwarebazaar pack for sample metadata, helping an agent disambiguate from that alternative.

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

Usage Guidelines5/5

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

Provides explicit when-not guidance: 'For sample metadata (file type, size, signature, YARA) use the malwarebazaar pack'. It also instructs that an empty result is a valid answer and not a failure, and explains that IOCs expire after six months, which prevents incorrect assumptions about failures. This is clear, actionable usage guidance.

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

All Threatfox tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.