Skip to main content
Glama
joblinours

DEFAIR MCP Server

by joblinours

DEFAIR

Digital Forensics & Incident Response platform — MCP-first, containerized, modular.

CI Python 3.13+ License: MIT


What is DEFAIR?

DEFAIR is a reproducible DFIR platform that orchestrates multiple forensic engines, unifies their results, and exposes the investigation to a human or an AI agent via CLI, API, and MCP (Model Context Protocol).

It is not "a giant Docker container with 50 forensic binaries". It is a forensic orchestration platform where external tools are specialized engines managed through a common architecture.

                     Analyst / AI Agent
                            │
                ┌───────────┴───────────┐
                │                       │
               CLI                     MCP
                │                       │
                └───────────┬───────────┘
                            │
                     Service Layer
                            │
                    ┌───────┴────────┐
                    │  Orchestrator  │
                    └───────┬────────┘
                            │
          ┌─────────────────┼─────────────────┐
          │                 │                 │
    Evidence Manager   Tool Registry     Job Engine
          │                 │                 │
          └─────────────────┼─────────────────┘
                            │
                  Normalization Layer
                            │
             ┌──────────────┼───────────────┐
             │              │               │
          Timeline       Findings          IOC
             │              │               │
             └──────────────┼───────────────┘
                            │
                     Reports / Export

Core principles

  1. MCP-first — every capability is exposed via CLI and MCP simultaneously

  2. Read-only on evidence — source files are never modified

  3. Hash & provenance — every result is traceable back to its source

  4. Reproducible — every execution is logged, versioned, and replayable

  5. No shell via MCP — the MCP exposes forensic operations, not arbitrary commands

  6. Offline-first — designed to work without internet access


Related MCP server: Files MCP Server

Quick start

Installation

# Clone
git clone https://github.com/joblinours/defair.git
cd defair

# Create venv and install (dev includes pytest, ruff, etc.)
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

# Verify installation
defair --version
pytest tests/ -v

CLI usage

# Create a forensic case
defair case create "Incident 2026-09 — Host compromise"

# List cases
defair cases list

# Register evidence (computes SHA-256 automatically)
defair evidence add CASE-2026-001 /evidence/host01.E01 --type disk_image

# List evidence (all or filtered by case)
defair evidence list
defair evidence list --case CASE-2026-001

# Get details
defair case get CASE-2026-001
defair evidence get EVD-001

# Verify evidence integrity (re-hash and compare)
defair evidence verify EVD-001

Container orchestration

DEFAIR runs forensic tools in isolated Docker containers — one per investigation:

# Create a forensic container linked to a case
defair container create --case CASE-2026-001 --evidence /evidence/host01.E01

# List containers
defair container list

# Execute a command inside the container
defair container exec defair-case-2026-001 ls -la /evidence

# Get container details / logs
defair container get defair-case-2026-001
defair container logs defair-case-2026-001

# Stop / remove
defair container stop defair-case-2026-001
defair container remove defair-case-2026-001

MCP usage

DEFAIR exposes a MCP server over stdio — compatible with Claude Desktop, Claude Code, and any MCP client:

# Run the MCP server
defair-mcp

Available MCP tools:

Tool

Description

Case & Evidence

create_case

Create a new investigation case

list_cases

List all forensic cases

get_case

Get case details by ID or case number

register_evidence

Register evidence with SHA-256 hash

list_evidence

List evidence (optionally filtered by case)

get_evidence

Get evidence details by ID or number

verify_evidence

Re-hash evidence and verify integrity

Container

create_container

Create an isolated forensic container

list_containers

List DEFAIR containers

get_container_info

Get container details

start_container

Start a stopped container

stop_container

Stop a running container

remove_container

Remove a container

exec_in_container

Execute a command inside a container

container_logs

Get container logs

Discovery & Analysis

discover_evidence

Discover forensic artifacts on mounted evidence

list_tools

List available forensic tools

tools_health

Check tool availability in a container

list_tool_runs

List past analysis runs

list_artifacts

List normalized artifacts from analysis

analyze_evtx

Parse Windows Event Logs (EvtxECmd)

analyze_mft

Parse NTFS Master File Table (MFTECmd)

analyze_registry

Parse Windows Registry hives (RECmd)

analyze_prefetch

Parse Prefetch files (PECmd)

analyze_amcache

Parse Amcache.hve (AmcacheParser)

analyze_shimcache

Parse Shimcache (AppCompatCacheParser)

analyze_jumplist

Parse Jump Lists (JLECmd)

analyze_lnk

Parse LNK shortcuts (LECmd)

analyze_recyclebin

Parse Recycle Bin (RBCmd)

analyze_shellbags

Parse ShellBags (SBECmd)

analyze_srum

Parse SRUM database (SrumECmd)

analyze_wintimeline

Parse Windows Timeline (WxTCmd)

analyze_sqlite

Parse SQLite databases (SQLECmd)

Detection & Hunting (v0.3)

hunt_evtx

Run Hayabusa Sigma detection on EVTX

build_timeline

Build unified timeline summary

search_timeline

Search/filter timeline with multi-criteria

list_findings

List investigation findings

search_ioc

Search IOC across all artifacts

Docker

# Build
docker compose build

# Run CLI
docker compose run --rm defair defair case create "Docker test"

# Run MCP server
docker compose run --rm mcp

Architecture

DEFAIR follows a triple-interface architecture: CLI, MCP, and API all call the same async Service Layer. No business logic lives in the interface layers.

CLI (click)          MCP (FastMCP)          API (FastAPI — planned)
     │                     │                      │
     │  run_sync()         │  async direct         │  async direct
     └─────────┬───────────┴──────────────────────┘
               │
        Service Layer (async)
               │
     ┌─────────┴──────────┐
     │                    │
  SQLite            Docker SDK
  (aiosqlite)       (container_service)
                          │
              ┌───────────┴───────────┐
              │  DEFAIR Container 1   │  evidence :ro
              │  DEFAIR Container 2   │  workspace :rw
              └───────────────────────┘

Project structure

src/defair/
├── config.py              # YAML + Pydantic configuration
├── logging.py             # Structured logging (structlog)
├── database.py            # SQLite schema & connection management
├── models/                # Pydantic data models (Case, Evidence, ...)
├── services/              # Async service layer (shared by CLI & MCP)
├── cli/                   # Click CLI commands
└── mcp_server/            # FastMCP server & tool definitions

Tech stack

Component

Technology

Language

Python 3.13

CLI

Click + Rich

MCP server

FastMCP 4.x (stdio)

Database

SQLite via aiosqlite

Models

Pydantic v2

Logging

structlog (JSON / console)

Config

YAML + Pydantic

Tests

pytest + pytest-asyncio

Lint

Ruff

Container

Docker + Compose

CI/CD

GitHub Actions


Roadmap

DEFAIR is built MCP-first: every phase delivers the forensic capability and its MCP exposure simultaneously.

✅ v0.1 — Core + Evidence Manager

  • Case & Evidence models

  • CLI: case create, cases list, case get, evidence add/list/get/verify

  • MCP: create_case, list_cases, get_case, register_evidence, list_evidence, get_evidence, verify_evidence

  • SQLite database with provenance

  • SHA-256 hashing + integrity verification on evidence

  • Structured logging with correlation IDs

  • Docker + CI/CD

✅ v0.1.5 — Host Wrapper + Container Orchestration

  • Docker SDK integration — orchestrate forensic containers from the host

  • One container per investigation, evidence mounted read-only

  • CLI: container create/list/get/start/stop/exec/logs/remove

  • MCP: create_container, list_containers, get_container_info, start_container, stop_container, exec_in_container, container_logs, remove_container

  • Persistent workspaces at ~/.defair/workspaces/

  • AI agent can create, control, and run commands in forensic containers via MCP

✅ v0.2 — Windows foundation + MCP analysis

  • Dissect integration (host discovery, artifact identification)

  • 14 EZ Tools with BaseTool wrappers + normalizers: MFTECmd, EvtxECmd, RECmd, PECmd, AmcacheParser, AppCompatCacheParser, JLECmd, LECmd, RBCmd, SBECmd, SrumECmd, WxTCmd, SQLECmd, bstrings

  • Normalization layer (BaseNormalizer → unified artifact schema)

  • Evidence discovery with automatic tool recommendations

  • MCP tools: discover_evidence, analyze_evtx, analyze_mft, analyze_registry, analyze_prefetch, analyze_amcache, analyze_shimcache, analyze_jumplist, analyze_lnk, analyze_recyclebin, analyze_shellbags, analyze_srum, analyze_wintimeline, analyze_sqlite

  • Tested on HackTheBox DFIR challenges (Jingle Bell, Recollection)

✅ v0.3 — Detection + Timeline + MCP hunting

  • Hayabusa v4.1 integration (4000+ Sigma rules, MITRE ATT&CK mapping)

  • Timeline Engine — unified timeline over all artifacts (summary, search, export CSV/JSONL)

  • Findings Engine — auto-created from Hayabusa high/critical detections (FND-NNN)

  • IOC search across all artifacts (description, data, hostname, username)

  • Hunting orchestration (hunt_evtx → detect → normalize → findings)

  • CLI: defair hunt, defair timeline, defair findings, defair search

  • MCP: hunt_evtx, build_timeline, search_timeline, list_findings, search_ioc

✅ v0.3.1 — Prefetch analysis fix

  • Replaced PECmd (Windows-only) with cross-platform Python-native Prefetch parser (windowsprefetch)

  • analyze_prefetch MCP tool works end-to-end in Linux containers

✅ v0.3.5 — Mass YARA + Sigma scanning (current)

  • YARA mass scanner on mounted evidence (files, memory dumps, disk images)

  • Sigma mass scanner via Hayabusa on all EVTX sources

  • Default rule sets embedded in the container (YARA community rules + Hayabusa Sigma rules)

  • Custom rules mounting: bind-mount /rules/yara/ and /rules/sigma/ for custom rules

  • Scan results normalized as Findings with severity, confidence, and MITRE mapping

  • MCP tools: scan_yara, scan_sigma

  • CLI: defair scan yara, defair scan sigma

  • 209 tests, 16 tool wrappers

📋 v0.4 — Orchestration + MCP profiles

  • DAG-based analysis orchestration

  • Declarative profiles (windows-triage, windows-full, ransomware, persistence)

  • Plaso integration (supertimeline)

  • Worker scheduling, parallel jobs, retry, timeout

  • MCP tools: run_profile, analyze_evidence

  • 🎯 Milestone: MVP MCP — an AI agent can conduct a full Windows investigation via MCP

📋 v0.5 — Reporting + API REST

  • Forensic reports (Markdown, HTML)

  • REST API (FastAPI + OpenAPI)

  • MCP tools: generate_report, export_case

📋 v0.6+ — Extended forensics

  • Volatility 3 — memory forensics

  • Zeek / TShark / Suricata — network DFIR

  • Linux DFIR — journald, SSH, cron, systemd, Docker artifacts

  • Web UI

  • RBAC, audit trail, supply chain security

📋 v1.0 — DEFAIR

  • Complete forensic workflow

  • Windows + Linux + Memory + Network

  • Stable MCP + API

  • Reproducible reports

  • Offline installation

  • Production-ready security

See defair_Roadmap.md for the full detailed roadmap.


Forensic engines (planned)

Engine

Purpose

Phase

Status

Dissect

Host discovery, artifact identification, filesystem access

v0.2

EZ Tools (14 tools)

Windows artifacts (MFT, EVTX, Registry, Prefetch, Amcache, ...)

v0.2

Hayabusa

EVTX detection with 4000+ Sigma rules, MITRE ATT&CK

v0.3

YARA

File/memory pattern matching, malware detection

v0.3.5

🔜

Plaso

Supertimeline, multi-source timestamp normalization

v0.4

📋

Volatility 3

Memory forensics (processes, network, DLLs, persistence)

v0.6

📋

Chainsaw

Fast EVTX search, Sigma detection

v0.6

📋

Zeek

Network traffic analysis, protocol logs

v0.6

📋

TShark

Packet capture analysis

v0.6

📋

Suricata

Network IDS, alert generation

v0.6

📋


Development

# Run tests
pytest tests/ -v

# Lint
ruff check src/ tests/

# Run CLI
defair --help

# Run MCP server
defair-mcp

Adding a new MCP tool

  1. Add the service function in src/defair/services/

  2. Add the CLI command in src/defair/cli/

  3. Add the MCP tool in src/defair/mcp_server/server.py with @mcp.tool()

  4. Add tests (unit + CLI + MCP integration)

  5. Both CLI and MCP must call the same service function


License

MIT


DEFAIR: a reproducible DFIR platform capable of orchestrating forensic engines, unifying their results, and exposing the investigation to a human or an agent via CLI, API, and MCP.

Available Tools

7 tools
create_caseCreate CaseC

Create a new forensic investigation case.

ParametersJSON Schema
NameRequiredDescriptionDefault
nameYesName of the case (e.g. "Incident host-01 ransomware").
descriptionNoOptional longer description of the case.

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

C2.9/5.0
Behavior2/5

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

With no annotations, the description carries the full behavioral burden, and it says nothing beyond the act of creation: no persistence guarantees, no required auth/permission level, no indication of whether the case is immediately visible to get_case/list_cases, and no side effects. For a mutation tool this is a meaningful gap.

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?

A single short sentence with the verb-resource pair front-loaded and zero filler. It is efficient, though its brevity is partly under-specification rather than disciplined conciseness.

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?

An output schema exists, so return values need not be explained, and the schema fully covers the two simple parameters. However, as an unannotated mutation tool it omits permissions, side effects, and any post-creation workflow hints, leaving the definition minimally but not fully adequate.

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 schema already documents both 'name' and 'description' including an example and a default. The description adds no parameter meaning beyond the schema, so the baseline of 3 is appropriate.

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 specific verb and resource ('Create a ... case') and the domain ('forensic investigation'), which is enough to distinguish it from the read-oriented siblings (list_cases, get_case, verify_evidence). It does not explicitly name or contrast the nearest alternative, so it stops short of 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 Guidelines2/5

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

There is no guidance on when to create a case versus reusing an existing one, no prerequisites (e.g., authentication or permissions), and no mention of sibling tools such as register_evidence that would follow. The agent must infer context entirely.

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

get_caseGet CaseB

Get details of a specific forensic case.

ParametersJSON Schema
NameRequiredDescriptionDefault
case_idYesThe case number (e.g. "CASE-2026-001") or internal UUID.

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.1/5.0
Behavior2/5

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

No annotations are provided, so the description carries the full behavioral burden. 'Get' weakly implies a read, but the description never states that this is a non-mutating lookup, what permissions are required, or whether case data is sensitive/auditable. With zero annotation coverage this is a notable gap.

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

Conciseness5/5

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

A single short sentence with no waste, front-loaded with the verb and resource. Appropriate size for a one-parameter lookup tool.

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?

Output schema exists so return values need not be described, and the single parameter is fully documented in the schema. But with no annotations and no usage guidance, an agent still lacks context on safety profile and when to prefer this over list_cases/get_evidence. Minimum viable.

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 case_id description already provides format examples (CASE-2026-001, internal UUID). The description adds nothing about the parameter, so the baseline of 3 applies – the schema does the heavy lifting.

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 specific verb ('Get') and resource ('details of a specific forensic case'), clear enough to distinguish from siblings like list_cases (plural, listing) and create_case (mutation). However it doesn't explicitly contrast with get_evidence or explain what 'details' includes, leaving some ambiguity about sibling selection.

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

Usage Guidelines2/5

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

No when-to-use guidance, no prerequisites, no mention of alternatives. The singular 'a specific forensic case' weakly implies you need a known case_id, but nothing tells the agent when to reach for this versus list_cases or get_evidence.

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

get_evidenceGet EvidenceC

Get details of a specific evidence item.

ParametersJSON Schema
NameRequiredDescriptionDefault
evidence_idYesEvidence number (e.g. "EVD-001") or internal UUID.

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

C2.9/5.0
Behavior2/5

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

With no annotations, the description carries the full behavioral burden but only implies a read via 'Get'. It says nothing about whether the evidence must exist, error behavior for unknown IDs, any access restrictions, or what happens with the two accepted ID formats. Minimal disclosure for a tool with zero annotation coverage.

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?

A single, front-loaded sentence with no wasted words and the verb/resource established immediately. It is efficient, though almost too terse to carry any extra value.

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?

An output schema exists, so return values needn't be explained, and there is only one well-documented parameter. The definition is adequate for a simple lookup but omits error/edge behavior and sibling differentiation that would make it fully complete.

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 parameter is documented with concrete examples ("EVD-001" or internal UUID). The description adds no additional meaning beyond the schema, so the baseline of 3 applies.

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 specific verb ('Get') and resource ('a specific evidence item'), which is clear and unambiguous. However, it does nothing to distinguish itself from siblings like get_case or list_evidence/verify_evidence, leaving the agent to infer from the name alone.

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

Usage Guidelines2/5

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

There is no guidance on when to use this tool versus list_evidence, verify_evidence, or register_evidence. The description offers no context, prerequisites, or exclusions, so an agent must guess that this is the single-item lookup counterpart to list_evidence.

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

list_casesList CasesB

List all forensic cases.

Returns a list of cases with their case number, name, status, and creation date. Cases are ordered by creation date (newest first).

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.4/5.0
Behavior3/5

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

With no annotations, the description carries the full burden, and it does add real behavioral context: the ordering (newest first) and the fields returned. However, it is silent on whether the full result set is returned unbounded, whether pagination or limits exist, and whether any permissions are required.

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?

Three short sentences, front-loaded with the purpose. The second sentence largely restates the output schema's fields, which is mild redundancy but not enough to hurt readability or comprehension.

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

Completeness4/5

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

An output schema exists, so return values need not be explained in prose, and the empty input schema means there are no parameter gaps to cover. The only missing piece is whether results are bounded or paginated, which is a minor gap for a zero-parameter list tool.

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?

The tool takes zero parameters, so per the rubric the baseline is 4. There is nothing for the description to disambiguate beyond confirming the operation takes no input.

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?

The description states a specific verb and resource ('List all forensic cases') and the scope ('all') implicitly distinguishes it from get_case, which retrieves a single case. It is unambiguous but never explicitly contrasts itself with the sibling read tools.

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

Usage Guidelines2/5

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

There is no guidance on when to call this versus get_case, and no mention of whether the result set is filtered, paginated, or capped. The agent must infer that 'all' means no filtering and no pagination control exists given the empty parameter schema.

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

list_evidenceList EvidenceB

List registered evidence items.

ParametersJSON Schema
NameRequiredDescriptionDefault
case_idNoOptional — filter by case number (e.g. "CASE-2026-001") or UUID. If omitted, returns all evidence across all cases.

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.1/5.0
Behavior2/5

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

No annotations are provided, so the description carries the full behavioral burden. It doesn't state whether this is a read-only operation, whether it paginates, what the return volume might be, or any auth requirements. For a list tool with no annotations, this is a significant gap.

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

Conciseness3/5

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

The single sentence is concise and front-loaded, but it's so terse that it sacrifices useful context. It earns points for zero waste, but doesn't provide enough substance to be considered well-structured for a list tool.

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?

An output schema exists, so return values needn't be explained. The single optional parameter is fully documented in the schema. However, with no annotations and no behavioral context, the description is barely adequate for an agent to understand when and how to use this tool versus siblings like get_evidence or list_cases.

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% — the case_id parameter is fully documented in the schema including its optional nature, accepted formats (case number or UUID), and default behavior. The description adds no parameter information beyond what's already in the schema, so the baseline of 3 is appropriate.

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 clear verb+resource: listing registered evidence items. This distinguishes it from get_evidence (singular retrieval) and register_evidence (creation). However, it doesn't explicitly contrast with list_cases, the closest sibling, leaving some sibling differentiation implicit.

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?

The description implies usage (you call it to see a list of evidence), but provides no explicit when-to-use guidance, no exclusions, and doesn't name alternatives like get_evidence for single-item retrieval. The optional case_id parameter's behavior is documented in the schema, not the description.

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

register_evidenceRegister EvidenceA

Register a new piece of evidence in a forensic case.

Computes SHA-256 hash of the file and stores metadata. The original file is never modified or copied.

ParametersJSON Schema
NameRequiredDescriptionDefault
pathYesAbsolute path to the evidence file.
case_idYesCase number (e.g. "CASE-2026-001") or UUID.
evidence_typeNoType of evidence — one of: disk_image, memory_dump, logs, triage_archive, pcap, other.other

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A3.8/5.0
Behavior4/5

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

With no annotations provided, the description carries the full behavioral burden and discloses important side effects: it computes a SHA-256 hash, stores metadata, and explicitly states the original file is never modified or copied. It still omits permissions, duplicate-registration behavior, and error conditions, but the core mutation and file-safety behavior are clearly conveyed.

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

Conciseness5/5

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

The description is three short sentences with the purpose front-loaded, followed by concise behavioral details. Every sentence adds useful information without repetition or filler.

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

Completeness4/5

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

Given no annotations, complete parameter descriptions, and an existing output schema, the description covers the essential action and key side effects. It is nearly complete, though it could mention prerequisites such as whether the case must already exist or what happens on duplicate registration.

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%, so the schema already documents all three parameters, including case_id format, path, and evidence_type enum values. The description adds no parameter-level meaning beyond what the schema provides, which matches the baseline of 3 for fully covered schemas.

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?

The description states a specific verb ('Register') and resource ('a new piece of evidence in a forensic case'), making the action immediately identifiable. It distinguishes itself from sibling tools like get_evidence, list_evidence, and verify_evidence by focusing on registration of new evidence rather than retrieval or verification.

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

Usage Guidelines2/5

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

The description gives no explicit when-to-use guidance, prerequisites, or alternative tools. It implies registration is for adding new evidence, but does not say when to prefer it over verify_evidence or how to handle existing evidence, leaving usage conditions entirely to inference.

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

verify_evidenceVerify EvidenceA

Verify evidence integrity by re-computing its SHA-256 hash.

Compares the current file hash against the hash stored at registration. This is a critical forensic operation to detect evidence tampering.

ParametersJSON Schema
NameRequiredDescriptionDefault
evidence_idYesEvidence number (e.g. "EVD-001") or internal UUID.

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A3.7/5.0
Behavior3/5

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

With no annotations, the description carries the full burden. It discloses the core behavior (recompute hash, compare to the value stored at registration) and implies a non-destructive read, but never states permissions, whether the result is persisted or logged, or what happens on a mismatch.

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?

Three short sentences with the mechanism front-loaded and no filler. The phrase "critical forensic operation" is mildly editorial but harmless, so structure is strong though not perfect.

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

Completeness4/5

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

An output schema exists, so the return shape need not be explained, and the one parameter is fully covered. The description is sufficient to call the tool, though it leaves the mismatch behavior and read/write semantics implicit.

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 single evidence_id parameter is already fully documented in the schema (evidence number or UUID). The prose adds no parameter-level detail, so the baseline of 3 applies.

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?

The description gives a specific verb+resource (verify evidence) and even names the mechanism (re-computing its SHA-256 hash) plus the goal (detect tampering). This clearly distinguishes it from the read-only siblings get_evidence and list_evidence, which retrieve rather than validate.

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?

It implies usage ("critical forensic operation to detect evidence tampering"), which tells an agent the context in which it matters. However, it names no alternatives or preconditions, e.g. whether get_evidence must be called first or when verification is unnecessary.

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 7 tool updatesv0.1.0
    • First observedcreate_case
    • First observedget_case
    • First observedget_evidence
    • First observedlist_cases
    • First observedlist_evidence
    • First observedregister_evidence
    • First observedverify_evidence

TDQS

A3.6/5.0

Scored across 7 tools

Disambiguation5/5

Each tool targets a distinct resource (case vs. evidence) and action (list, create, get, register, verify). The purposes are clear and non-overlapping, with no ambiguity in selection.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern: list_cases, create_case, get_case, register_evidence, list_evidence, get_evidence, verify_evidence. This is predictable and easy to parse.

Tool Count5/5

Seven tools are well-scoped for a forensic case management server, covering essential operations without redundancy. Each tool earns its place in the set.

Completeness4/5

The surface covers core case and evidence lifecycle operations, including creation, retrieval, listing, and integrity verification. However, it lacks update and delete operations for cases and evidence, which are common CRUD needs that could be required for full lifecycle management.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Related MCP Connectors

Related MCP Servers