ransomware-live-mcp

filter_victims

Read-only

Filter ransomware victim records by group, sector, country, and date with AND logic to get exact-match slices for analysis or reporting.

Instructions

Filter the full victim database by group, sector, country and date.

At least one filter is required, and all filters combine with AND logic. year cannot be used alone: the API rejects it unless month is also set. Use this rather than search_victims when you want an exact-match slice (e.g. every LockBit victim, or all US healthcare victims in June 2024).

Args: group: Exact group name, case-insensitive (see list_groups). sector: Exact sector name (see list_sectors). country: ISO 3166-1 alpha-2 country code, e.g. "US". year: 4-digit year, e.g. "2024". Must be paired with month. month: 2-digit month, e.g. "06". Requires year. date: Which date field to filter on, "discovered" or "attacked". limit: Max records to return (1-200). offset: Skip this many records; use next_offset from a prior call. full: Include all enrichment fields.

Input Schema

TableJSON Schema

Name	Required	Default
`date`	No	discovered
`full`	No
`year`	No
`group`	No
`limit`	No
`month`	No
`offset`	No
`sector`	No
`country`	No

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Sep 19, 2026

TDQS

A5/5.0

Behavior5/5

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

While annotations already declare readOnlyHint=true and destructiveHint=false, the description adds crucial behavioral details: the requirement of at least one filter, AND logic across filters, and the mandatory year-month pairing. These go beyond the annotations and inform the agent of API constraints that could otherwise cause errors.

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 front-loaded with the core purpose and usage guidance, followed by a clear and concise parameter list. Each sentence serves a purpose, with no fluff, making it easy for an agent to parse the critical information quickly.

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?

For a tool with 9 parameters and an output schema, the description covers all necessary usage aspects: filter requirements, logic, parameter formats, pagination, and sibling differentiation. It does not need to describe return values since an output schema exists, so it is fully complete for correct invocation.

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

Parameters5/5

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

With 0% schema description coverage, the description fully compensates by explaining every parameter in detail: formats (e.g., ISO 3166-1 alpha-2 for country), constraints (year/month pairing), pagination via `next_offset`, and the meaning of `full`. It adds substantial meaning beyond the bare schema.

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 explicitly states 'Filter the full victim database by group, sector, country and date', giving a specific verb and resource. It further differentiates from the sibling `search_victims` by positioning itself for exact-match slices, making its purpose unmistakable.

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?

It provides explicit when-to-use guidance: 'Use this rather than `search_victims` when you want an exact-match slice', and also notes the constraint that `year` cannot be used alone. This clearly directs the agent to the appropriate tool without ambiguity.

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