Skip to main content
Glama

Search Hash

search_hash
Read-onlyIdempotent

Everything ThreatFox knows about one file hash (md5 / sha1 / sha256), across BOTH relations it stores hashes inthey 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 databasemost 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.

Example tool call

This call uses example arguments supplied in the tool’s input schema.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "hash": "2a85f2e5876b278a7af9393483de455b"
    },
    "name": "search_hash"
  }
}

Input Schema

NameRequiredDescriptionDefault
hashYesmd5 (32 hex), sha1 (40 hex) or sha256 (64 hex). Anything else is rejected upstream as illegl_hash [sic] rather than answered empty.

Output Schema

NameRequiredDescriptionDefault
countYesNumber of results returned
queryYesThe query type sent (search_hash)
statusYesQuery status (ok, no_result, or null)
resultsYesIOCs associated with the file hash
matched_relationNoWHICH 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_relationsNoPresent 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.

  1. Changed4 schema fields changed
    • 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"
      +}
  2. Changed2 schema fields changed
    • 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"
      +}
  3. First observed

TDQS

A4.6/5.0
Behavior5/5

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

Goes well beyond the supplied read-only/idempotent/open-world annotations by explaining the two internal relations (sample_to_c2 and hash_listed_as_ioc), how matched_relation identifies which one fired, and why null/empty results are expected. It also discloses the six-month IOC expiry and malformed-hash rejection behavior.

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-loads the core purpose and uses numbered items to distinguish the two relations. It is dense and mostly earns its length, though there is a run-on sentence and a typo ("inthey") that slightly reduce polish.

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?

Complete for a read-only lookup with a full schema, annotations, and an output schema: it explains relation semantics, matched_relation, empty-result interpretation, expiry behavior, and when to use a different pack. Nothing essential for correct invocation appears 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 description coverage is 100%, and the single hash parameter already documents accepted formats and rejection behavior. The description adds context about why the caller may not know the relation, but does not add new syntax or handling details for the parameter itself.

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 a specific verb and resource: "Everything ThreatFox knows about one file hash (md5 / sha1 / sha256)" and explains the two relations it searches. It clearly distinguishes this from sample-metadata lookup by directing users to the malwarebazaar pack for file type, size, signature, and YARA.

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?

Explains the core use case: a caller has a hash but may not know which relation it belongs to, so the tool checks both. It explicitly warns that an empty result is a real answer, notes six-month IOC expiration, and names an alternative for sample metadata.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.