Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@ransomware-live-mcp What are the latest ransomware victims and their IOCs?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An MCP server exposing the ransomware.live PRO threat-intelligence API to any MCP client: ransomware groups and their TTPs, victims, IOCs, YARA rules, ransom notes, leaked negotiation chats, press coverage, SEC 8-K cyber disclosures, and national CSIRT contacts.
25 tools, all read-only. Every tool maps to a documented GET endpoint on
https://api-pro.ransomware.live.
Built for defensive use: threat hunting, detection engineering, incident response, third-party risk and tabletop exercises.
Works on macOS, Linux and Windows.
git clone https://github.com/abdulbrown/ransomware-live-mcp.git
cd ransomware-live-mcp
uv venv
uv pip install -e ".[dev]"
cp .env.example .env # then paste your key into .envThen register it with your MCP client.
Full detail below.
Related MCP server: SeldomMaster
Python 3.10+
An MCP client — Claude Code, Claude Desktop, or any other
A free ransomware.live PRO API key
The key is free. Every user needs their own — keys are personal and should never be shared or committed.
Go to my.ransomware.live.
Register with an email address and confirm it. The confirmation link activates the account; the key will not authenticate until you do this.
Sign in to the dashboard and generate / copy your API key. It looks like
a UUID (36 characters, in the form
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx).
Paste it into .env — see step 3 below.
Verify it is enabled before wiring it into a client:
<PYTHON> scripts/selftest.pyA working key prints [ok] API key valid: followed by the account
identifier tied to it. You can also check it directly:
curl https://api-pro.ransomware.live/validate -H "X-API-KEY: your-key-here"
# {"status": "valid", "client": "you@example.com"}Once registered, the key is authenticated by sending it as an X-API-KEY
header on every request — this server handles that for you.
ransomware.live offers several tiers. This server targets API PRO:
Tier | Auth | Limit | Used here |
API v1 | none | deprecated | no |
API v2 | none | 1 req/min per endpoint | no |
API PRO |
| 500,000 calls/month | yes |
API PRO+ | key | in development | no |
PRO is free but key-gated, and is the only tier exposing group intelligence (TTPs, CVEs), negotiations, YARA rules and ransom notes. A fair use policy applies; exceeding the quota returns HTTP 429, which this server retries with backoff.
23 of the 25 tools call the API and require the key. Only build_victim_id and
decode_victim_identifier work offline. If the key is missing or invalid,
every API tool returns one clear error message and the server stays running —
it does not crash the session.
git clone https://github.com/abdulbrown/ransomware-live-mcp.git
cd ransomware-live-mcp
# with uv (recommended):
uv venv
uv pip install -e ".[dev]"
# or with plain venv + pip:
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"Your Python interpreter is at .venv/bin/python.
git clone https://github.com/abdulbrown/ransomware-live-mcp.git
cd ransomware-live-mcp
# with uv (recommended):
uv venv
uv pip install -e ".[dev]"
# or with plain venv + pip:
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e ".[dev]"Your Python interpreter is at .venv\Scripts\python.exe.
Throughout this README,
<PYTHON>means the interpreter path for your platform:.venv/bin/pythonon macOS/Linux,.venv\Scripts\python.exeon Windows.
Verify the install before going further — this works without an API key:
<PYTHON> -m pytest -qExpect 32 passed.
Copy the example file and paste your key into it:
# macOS / Linux
cp .env.example .env# Windows
Copy-Item .env.example .envEdit .env:
RANSOMWARE_LIVE_API_KEY=your-key-here.env is gitignored and will never be committed. The server resolves it
relative to its own install location, not the working directory, so it works no
matter where your MCP client launches it from.
Confirm the key works:
<PYTHON> scripts/selftest.pyExpected output ends with [ok] full self-test passed. If you have not added a
key yet it exits cleanly and tells you so, rather than failing cryptically.
Every MCP client spawns the interpreter directly, so you must use an absolute path to the venv Python. Get it with:
# macOS / Linux
echo "$(pwd)/.venv/bin/python"# Windows
(Resolve-Path .\.venv\Scripts\python.exe).Path# macOS / Linux
claude mcp add ransomware-live --scope user -- /ABSOLUTE/PATH/TO/ransomware-live-mcp/.venv/bin/python -m ransomware_live_mcp.server# Windows
claude mcp add ransomware-live --scope user -- C:\ABSOLUTE\PATH\TO\ransomware-live-mcp\.venv\Scripts\python.exe -m ransomware_live_mcp.server--scope user makes it available in every project; drop the flag to scope it to
the current project only.
Confirm it connected:
claude mcp listYou should see ransomware-live: ... - ✓ Connected. The tools become available
in new sessions, so restart any session you already have open.
To remove it later: claude mcp remove ransomware-live --scope user
Edit your claude_desktop_config.json:
Platform | Location |
macOS |
|
Windows |
|
You can also reach it from the app: Settings → Developer → Edit Config.
{
"mcpServers": {
"ransomware-live": {
"command": "/Users/you/code/ransomware-live-mcp/.venv/bin/python",
"args": ["-m", "ransomware_live_mcp.server"]
}
}
}Backslashes must be escaped in JSON:
{
"mcpServers": {
"ransomware-live": {
"command": "C:\\Users\\you\\code\\ransomware-live-mcp\\.venv\\Scripts\\python.exe",
"args": ["-m", "ransomware_live_mcp.server"]
}
}
}Restart Claude Desktop completely after editing — quit the app, don't just close the window. The tools appear under the tools icon in the chat input.
The server speaks MCP over stdio. Point your client at:
command: the absolute path to <PYTHON>
args: ["-m", "ransomware_live_mcp.server"]
.envAny client that supports an env block can supply the key directly:
{
"mcpServers": {
"ransomware-live": {
"command": "/absolute/path/to/.venv/bin/python",
"args": ["-m", "ransomware_live_mcp.server"],
"env": { "RANSOMWARE_LIVE_API_KEY": "your-key-here" }
}
}
}.env is usually preferable — it keeps your key out of client config files,
which are easy to sync, screenshot or share by accident.
<PYTHON> -m ransomware_live_mcp.serverIt will sit and wait for a client on stdin. That is correct behaviour, not a hang.
Symptom | Cause and fix |
| Wrong interpreter path. It must be the absolute path to the venv Python, not |
Every tool returns "No API key configured" |
|
| Key is wrong or inactive. Verify at my.ransomware.live. |
| The client is using a different interpreter than the one you installed into. Re-check the absolute path. |
Tools don't appear in Claude Code | They only load in new sessions. Restart the session. |
Tools don't appear in Claude Desktop | Quit and relaunch the app entirely; closing the window is not enough. |
Windows: | PowerShell execution policy. Use |
Tool | Endpoint | Purpose |
|
| Confirm the key is active |
|
| Victim/group/press totals and last update |
|
| All tracked groups with victim counts |
|
| Full profile: TTPs, CVEs, tools, leak sites |
|
| Valid |
|
| 100 newest victims |
|
| Free-text search on name/website |
|
| Exact filter by group/sector/country/date |
|
| One enriched victim record |
| — | Offline: names → Base64 victim ID |
| — | Offline: Base64 victim ID → names |
|
| Groups holding IOCs, by type |
|
| IOC values for a group |
|
| Groups with YARA rules |
|
| Full YARA rule text |
|
| Groups with ransom notes |
|
| Note identifiers |
|
| Note content |
|
| Groups with leaked chats |
|
| Chats + ransom amounts/outcome |
|
| Full message thread |
|
| 100 newest cyberattack press entries |
|
| Press by year/month/country |
|
| SEC 8-K Item 1.05 / 8.01 cyber disclosures |
|
| National CERT/CSIRT contacts |
All 25 are annotated readOnlyHint, so clients can auto-approve them without
prompting on every call.
Once registered, ask your client in plain language. The examples below are grouped by what the API key actually unlocks, with real figures observed against the live API.
"What's the current ransomware landscape summary?" "Which groups have been most active this month?"
Tools: get_stats, list_groups, get_recent_victims
A single get_stats call is the cheapest freshness check — it returns total
victims, tracked groups, press entries and the timestamp of the most recent
leak-site listing. list_groups returns every tracked group with a victim
count, which is also how you resolve the exact group name other tools expect.
"Profile the Akira ransomware group — TTPs, exploited CVEs, and tooling." "Which ransomware groups exploit vulnerabilities in my edge devices?"
Tools: get_group
The richest endpoint. For one group you get a full MITRE ATT&CK mapping (Initial Access → Impact), the CVEs that group is known to exploit with CVSS scores, categorised tooling (RMM abuse, exfiltration, credential theft), and known leak-site URLs.
This turns a patch backlog into a threat-informed queue: Akira's list includes
SonicWall CVE-2024-40766, Veeam CVE-2024-40711 and Fortinet
CVE-2022-40684 — all CVSS 9.8, all internet-facing. Cross-reference against
your own edge inventory and the patch order writes itself.
"Pull YARA rules and hash IOCs for Qilin and write them to ./rules/." "Get Akira's IP indicators for my blocklist."
Tools: list_yara_groups, get_yara_rules, list_ioc_groups,
get_group_iocs
get_yara_rules returns complete .yar rule text ready for a scanner.
get_group_iocs returns indicators grouped by type — use the ioc_type
filter (md5, sha256, ip, domain, email, btc, tox, session) to
keep responses small, since some groups hold hundreds of hashes.
Check coverage before you pull: list_ioc_groups shows the per-type breakdown,
so you can see that a group is hash-heavy and network-light before assuming an
IP blocklist gives you meaningful coverage.
"Have any of these vendors appeared on a leak site? [domain list]" "Show UK healthcare ransomware victims from the last year."
Tools: search_victims, filter_victims, list_sectors, get_victim
search_victims substring-matches both the organisation name and the
website domain, so you can paste a vendor domain list straight in.
filter_victims does exact-match slicing by group, sector, country and date —
filtering to UK healthcare returns 65 victims, paginated.
Use list_sectors first to get valid sector values; it also returns victim
counts per sector, which is a quick relative-risk picture on its own.
"I found a ransom note called README0apt on a host — which group is this?" "Who do I notify for a ransomware incident in Germany?"
Tools: list_ransomnote_groups, list_group_ransomnotes,
get_ransomnote, get_csirt_contacts, get_group
Ransom notes give you attribution from an artefact you'd actually recover from
a compromised machine. Once attributed, get_group tells you that actor's
typical initial access and exfiltration tooling — i.e. where else to look.
get_csirt_contacts returns national CERT/CSIRT contacts from ENISA and FIRST.
Worth resolving before you need it, not during an incident.
"Analyze Akira's negotiation history — what do victims actually pay?"
Tools: list_negotiation_groups, list_group_negotiations,
get_negotiation
The most unusual dataset here: leaked negotiation transcripts with ransom amounts and outcomes. Aggregating Akira's 76 chats:
Metric | Value |
Confirmed paid | 27 / 76 (36%) |
Median discount off initial demand | 57% |
Median initial demand | $400,000 |
Median settled amount | $140,000 |
Largest demand observed | $10,000,000 |
Longest negotiation | 170 messages ($1.7M → $225k) |
list_group_negotiations gives amounts and outcomes without pulling every
message, so prefer it for aggregate analysis; use get_negotiation when you
want the actual transcript for a tabletop.
Interpret with care: this is only the subset of negotiations that leaked, which skews toward cases that went badly or public. Treat the payment rate as a property of that sample, not a market-wide figure.
"Which public companies filed SEC 8-K Item 1.05 cyber disclosures in 2025?" "What ransomware activity hit our sector this quarter?"
Tools: get_sec_8k_filings, get_recent_press, search_press,
list_sectors
get_sec_8k_filings covers SEC Form 8-K cyber disclosures — Item 1.05
(Material Cybersecurity Incidents, mandatory since December 2023) and Item 8.01.
Set include_item_801=false for mandatory material incidents only. Each result
carries company, ticker, CIK, filing date and a direct EDGAR link.
Press endpoints add journalistic coverage cross-linked to leak-site victims where the domain matches, which is useful for the "has this become public yet?" question.
The live API departs from its own documentation in two ways this server
smooths over, both confirmed against api-pro.ransomware.live:
Envelopes. Every response is a wrapper dict ({client, count, victims},
{client, count, groups}, {client, filters, count, forms}, ...), not the
bare list the docs imply. Tools unwrap it, and drop the client field that
echoes your account identity back on every single response.
Two spellings for victim fields. /victims/recent returns victim /
group / attackdate, while /victims/search and /victim/{id} still
return the legacy post_title / group_name / published. Everything is
normalised to the modern names, so all tools report one schema.
Victim and press listings can run to thousands of records, so those tools paginate and slim by default:
limit defaults to 50, max 200. Page onward with the next_offset value the
response hands back.
Pass full=true for the enrichment fields (screenshot URL, infostealer data,
press link, permalink). When omitted, the response still flags
has_infostealer_data / has_press_coverage / has_screenshot.
GET responses are cached in memory for 5 minutes, and HTTP 429 / 5xx are
retried with exponential backoff honouring Retry-After.
get_group and unfiltered get_group_iocs return large payloads and are not
paginated. A single group profile can run to several thousand tokens; some
groups hold hundreds of hashes. Use the ioc_type filter to narrow.
Upstream data quality is uneven and passed through faithfully: some group
entries are artefacts (e.g. .git), ransom amounts appear as "N/A", ""
or null in the same field, and country is sometimes blank.
There is no monthly quota tracking. The cache reduces repeat calls but is per-process and does not survive a restart.
Variable | Default | Meaning |
| — | Required. PRO API key |
|
| API base |
|
| Cache lifetime, seconds ( |
|
| Per-request timeout, seconds |
Precedence: real environment variables > .env in the working directory >
.env beside the package.
<PYTHON> -m pytest -q # 32 offline tests, no key needed
<PYTHON> scripts/launch_check.py # stdio JSON-RPC handshake
<PYTHON> scripts/selftest.py # key validation + a few live calls
<PYTHON> scripts/live_check.py # all 25 tools against the live APIlaunch_check.py spawns the server as a real subprocess from an unrelated
working directory and speaks raw MCP JSON-RPC to it, proving both the transport
and the .env resolution work independently of any client library.
live_check.py goes through MCPServer.call_tool, covering argument schemas
and validation as well as the HTTP layer.
Only pytest runs without an API key; the other three make live calls.
The API's WAF returns 403 {"message": "Invalid API key"} — not a 429 or a
block page — for requests carrying the default python-httpx/* User-Agent,
even with a valid key. The client always sends its own User-Agent.
The server exits on stdin EOF, which is correct MCP behaviour. Test harnesses
using subprocess.communicate() will close stdin and abort any in-flight tool
call; hold stdin open instead.
Raise ToolError, never a bare exception. The SDK wraps an unrecognised
exception as UnexpectedToolError, which tears down the stdio session — one
failing call costs the client all 25 tools. The readonly_tool decorator
converts ApiError to ToolError centrally, so a missing key or a 404
returns one actionable message and the session stays up. Any new failure mode
should go through ApiError.
This targets MCP SDK 2.x, where FastMCP was renamed MCPServer. Most
tutorials still show the 1.x import.
.env is gitignored and no key is committed to this repository.
The server is strictly read-only — it issues GET requests and exposes no
tool that writes, deletes, or sends data anywhere.
Responses may contain ransom note text, leaked negotiation transcripts and victim organisation names. Handle accordingly.
MIT — see LICENSE.
Data is supplied by ransomware.live under its own terms; observe its fair use policy. This project is not affiliated with or endorsed by ransomware.live.
Construct the Base64 victim ID for get_victim from the two names.
Offline helper; makes no API call. The names must match the API's values
exactly, so prefer reusing an id from a listing when you have one.
Args:
victim_name: Victim organisation name as listed (the victim field).
group_name: Ransomware group name (the group field).
| Name | Required | Description | Default |
|---|---|---|---|
| group_name | Yes | ||
| victim_name | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds valuable behavioral context: it is an offline helper making no API call, and it is sensitive to exact name matching. This goes beyond the annotations without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact, front-loaded with the core purpose, and uses a clean Args list. Every sentence earns its place and there is no redundant restatement of the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple offline helper with two string parameters, an output schema, and safety annotations already present, the description fully covers purpose, constraints, and parameter semantics. Nothing essential is missing for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although schema description coverage is 0%, the description's Args block explicitly defines both parameters: victim_name is the victim organisation name as listed (the `victim` field), and group_name is the ransomware group name (the `group` field). This gives the agent semantic meaning beyond the schema's bare field titles.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The first sentence says exactly what the tool does: it constructs a Base64 victim ID for get_victim from two names. The phrase 'Offline helper; makes no API call' further distinguishes it from API-calling siblings like get_victim or search_victims.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit usage guidance: use it to build an ID from two names, but prefer reusing an `id` from a listing when available. It also warns that names must match the API's values exactly, which tells the agent when the tool is appropriate and when it is not.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Decode a Base64 victim ID back into its victim and group names.
Offline helper; makes no API call.
Args: victim_id: Base64-encoded victim ID.
| Name | Required | Description | Default |
|---|---|---|---|
| victim_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true and destructiveHint=false. The description adds 'makes no API call,' which is extra context beyond the annotations and clarifies that this is a pure, side-effect-free operation. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and front-loaded with the core purpose, followed by the key usage note. Every sentence earns its place with no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool is a simple decode operation, the description covers the essential aspects: what it does, the parameter format, and the offline nature. An output schema exists, so return values are not required to be explained. It could mention the inverse tool, but that is optional.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides no description for 'victim_id' (0% coverage), so the description must compensate. It does so by specifying 'Base64-encoded victim ID,' which is essential and adds meaning beyond the schema's basic type. This fully explains the expected format for the single parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Decode'), a resource ('Base64 victim ID'), and the output ('victim and group names'). This clearly distinguishes it from its inverse sibling 'build_victim_id'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly notes 'Offline helper; makes no API call,' which tells an agent when to use this tool (i.e., when a local, network-free decode is needed). It does not explicitly name alternatives, but the offline constraint is a clear and sufficient guideline.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| date | No | discovered | |
| full | No | ||
| year | No | ||
| group | No | ||
| limit | No | ||
| month | No | ||
| offset | No | ||
| sector | No | ||
| country | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
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.
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.
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.
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.
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.
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.
Get national CSIRT/CERT incident-response contacts for a country.
Sourced from ENISA (EU) and FIRST (global). Use this to find who to notify when triaging a confirmed incident.
Args: country: ISO 3166-1 country code, alpha-2 ("FR") or alpha-3 ("FRA").
| Name | Required | Description | Default |
|---|---|---|---|
| country | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds provenance (ENISA/FIRST) and the lookup nature, but does not describe edge-case behavior such as invalid country codes or empty results.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very compact, with no filler. The purpose, usage context, and parameter format are all conveyed in a few short sentences, and the parameter documentation is efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter read-only lookup with an output schema, this is complete: it states what is returned, where the data comes from, when to use it, and how to format the country parameter.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description fully compensates by specifying the ISO 3166-1 format and giving alpha-2 and alpha-3 examples ('FR'/'FRA'). This adds critical meaning beyond the bare 'string' schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'Get national CSIRT/CERT incident-response contacts for a country.' It clearly distinguishes itself from the unrelated sibling tools about victims, groups, press, and filings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states when to use the tool: 'Use this to find who to notify when triaging a confirmed incident.' It also provides source context (ENISA/FIRST) that helps an agent judge applicability, though it does not mention when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a full intelligence profile for one ransomware group.
Includes background description, first/last seen dates, victim count, known leak-site URLs (Tor and clearweb), MITRE ATT&CK TTPs, exploited CVEs with CVSS scores, tools and malware used, and flags for whether negotiation chats and ransom notes are on file.
Args: group_name: Group name, case-insensitive (e.g. "lockbit3", "blackcat", "clop").
| Name | Required | Description | Default |
|---|---|---|---|
| group_name | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already characterize it as read-only and non-destructive, and the description adds useful disclosure about what the profile contains, including flags reflecting whether negotiation chats and ransom notes exist. It does not describe rate limits or error behavior, but the safety profile is already supplied by annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Every line earns its place: the first sentence states the purpose, the middle enumerates returned data, and the Args block documents the only parameter. It is front-loaded and readable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter read tool with an output schema and clear annotations, the description is complete. It covers the input semantics, the breadth of the response, and the safety profile without requiring an agent to inspect schemas.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description compensates for the single required parameter by naming it, stating it is case-insensitive, and giving concrete examples. This is sufficient for a one-argument lookup, though it does not explain how to discover valid group names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Get a full intelligence profile for one ransomware group.' It then enumerates the profile's contents, making the tool's scope unmistakable and distinguishing it from list-style siblings like list_groups and get_group_iocs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives clear context: use this when a single group's full profile is needed, as opposed to listing groups. It does not explicitly name alternatives or state when not to use it, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get indicators of compromise for one ransomware group, grouped by type.
Args: group: Group name, e.g. "lockbit3". ioc_type: Return only this type (md5, sha256, ip, domain, email, btc, url) to keep the response small.
| Name | Required | Description | Default |
|---|---|---|---|
| group | Yes | ||
| ioc_type | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful response-shaping behavior (grouping by type, optional filtering to keep responses small), but does not disclose any other side effects or runtime behavior. With annotations present, this is adequate but not exceptional.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The main action is front-loaded in one clear sentence, followed by a compact Args block. There is no filler or repetition of schema information; every line adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, annotations covering safety, and both parameters semantically explained, the tool is largely complete for a simple read operation. It would be slightly improved by pointing to list_ioc_groups for discovering valid group names, but this is a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and neither parameter has enums, so the description carries the full burden for parameter meaning. It explains 'group' with a concrete example ('lockbit3') and fully documents 'ioc_type' by listing all accepted values and its purpose of keeping the response small.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get') with a precise resource ('indicators of compromise for one ransomware group') and adds 'grouped by type', clearly communicating what the tool returns. It is distinguishable from siblings like list_ioc_groups or get_yara_rules by naming a single group and IOC types.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for fetching IOCs for a specific named group and explains how to narrow results with ioc_type, but it never states when to prefer this over related tools such as list_ioc_groups or how to discover valid group names. Usage context is inferred rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the full message thread and ransom metadata for one negotiation chat.
These threads can be long. Prefer list_group_negotiations first to read
ransom amounts and outcomes without pulling every message.
Args:
group: Group name, e.g. "lockbit3".
chat_id: Chat ID from list_group_negotiations, e.g. "20240517".
| Name | Required | Description | Default |
|---|---|---|---|
| group | Yes | ||
| chat_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and destructiveHint, covering the safety profile. The description adds behavioral context by noting that full threads can be long and that the tool returns the complete message thread plus ransom metadata, which is useful beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact, front-loaded with purpose, and each sentence earns its place. The args section is short but meaningful, with no filler or redundant restatement of the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter read operation with output schema and readOnly annotations, the description provides everything needed: purpose, alternative routing, parameter examples, and the caveat about long threads. No critical operational context is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description fully compensates. It explains group with a concrete example and specifies that chat_id should come from list_group_negotiations, giving the agent both format and provenance guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses a specific verb and resource: 'Get the full message thread and ransom metadata for one negotiation chat.' It clearly differentiates from the sibling list_group_negotiations by emphasizing the full thread versus summary data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly names the preferred alternative: 'Prefer list_group_negotiations first to read ransom amounts and outcomes without pulling every message.' It also warns that threads can be long, giving the agent clear context for choosing between the tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the full text of one ransom note.
Args:
group: Group name, e.g. "lockbit3".
note_name: Note identifier from list_group_ransomnotes, without
file extension.
| Name | Required | Description | Default |
|---|---|---|---|
| group | Yes | ||
| note_name | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool as read-only and non-destructive. The description adds useful behavioral context by emphasizing 'full text' and 'one', clarifying that the tool returns the complete content of a single note. No contradiction with annotations exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: one clear purpose sentence followed by terse, useful argument definitions. No fluff or redundant content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with an output schema, annotations, and detailed parameter semantics, the description is nearly complete. It includes the prerequisite workflow via the sibling reference and an example, though it does not explicitly state all possible edge cases or non-use conditions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries full responsibility. It fully compensates by explaining 'group' with a concrete example ('lockbit3') and by specifying that 'note_name' is an identifier from a sibling tool and should be given without a file extension. Both parameters are well clarified.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a specific verb+object pair: 'Get the full text of one ransom note.' It clearly distinguishes from the sibling 'list_group_ransomnotes' by focusing on fetching a single note's full text, and it names both required parameters.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the proper workflow by stating that note_name is 'a note identifier from `list_group_ransomnotes`'. This tells the agent that listing must precede getting, but it does not explicitly contrast with alternatives or state when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the 100 most recent tracked cyberattack press entries.
Entries are enriched with infostealer data and linked to a ransomware victim record where the domain matches.
Args:
country: ISO 3166-1 alpha-2 country code to narrow before taking the top 100.
limit: Max records to return (1-200).
offset: Skip this many records; use next_offset from a prior call.
full: Include all enrichment fields.
| Name | Required | Description | Default |
|---|---|---|---|
| full | No | ||
| limit | No | ||
| offset | No | ||
| country | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context: records are enriched with infostealer data, linked to ransomware victims by domain match, and limited to the most recent 100 before filtering. It does not detail pagination edge cases or rate limits, but the added context is valuable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: the core behavior is in the first sentence, followed by enrichment context and a clear Args list. Every sentence earns its place, and the structure is easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has an output schema, so return values need not be explained. The description covers the main behavior, enrichment, and all parameters. It does not mention whether `next_offset` is returned in the output schema, but the output schema likely covers that; overall it is complete enough for an agent to call correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries the full burden for parameter meaning. It explains country (narrow before top 100), limit (max records 1-200), offset (skip records, use next_offset), and full (include all enrichment fields). This adds real semantics beyond the bare schema types and defaults.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Get'), a precise resource ('100 most recent tracked cyberattack press entries'), and adds enrichment context (infostealer data, ransomware victim linking). It is clearly distinguishable from siblings like search_press and get_recent_victims.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the default behavior (top 100) and how to paginate using `next_offset`, which gives clear usage context. It does not explicitly name alternatives or when-not-to-use, but the sibling list and the tool's specific scope make the intended use clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the 100 most recent active ransomware victims.
Args:
order: "discovered" (when ransomware.live first saw the leak-site
listing) or "attacked" (estimated attack date).
limit: Max records to return (1-200).
offset: Skip this many records; use next_offset from a prior call.
full: Return every enrichment field (screenshot URL, infostealer data,
press link, permalink) instead of the slimmed core fields.
| Name | Required | Description | Default |
|---|---|---|---|
| full | No | ||
| limit | No | ||
| order | No | discovered | |
| offset | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, non-destructive, open world). The description adds useful behavioral context about ordering (discovered vs attacked), pagination (offset and next_offset), and the full parameter for enrichment fields. However, it does not disclose what 'active' means, how results are sorted by default, or any edge cases like rate limits, so coverage is partial.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with a clear one-line purpose followed by a structured Args block. The structure is easy to parse, but the first sentence's fixed '100' is inconsistent with the limit parameter, introducing minor confusion that could have been avoided by wording it as 'recent' without a hard number.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has an output schema (not shown) and safety annotations, so the description need not repeat return types. It covers parameter semantics well and mentions pagination via offset and next_offset. However, it fails to clarify the meaning of 'active', the actual default record count (description says 100 but default is 50), and any nuances about result ordering stability, leaving some gaps for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema description coverage at 0%, the description compensates excellently by explaining each parameter: order with two enum meanings, limit range (1-200), offset semantics with next_offset reference, and full switching between slim and enriched output. This adds substantial meaning beyond the raw schema and enables correct usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves recent active ransomware victims, with a specific scope (100 most recent). However, it does not differentiate this from sibling tools like search_victims or filter_victims, and the fixed '100' contradicts the configurable limit parameter (default 50, max 200), which could confuse an agent.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as search_victims or filter_victims. It implies it is for browsing recent data, but lacks explicit when-to-use or when-not-to-use instructions, leaving the agent to infer the selection logic.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get SEC Form 8-K filings disclosing cybersecurity incidents.
Covers Item 1.05 (Material Cybersecurity Incidents, mandatory since Dec 2023) and Item 8.01 (Other Events, used for such disclosures before that).
Args:
ticker: Stock ticker, uppercase, e.g. "MSFT".
cik: SEC CIK code, e.g. "0001234567".
year: 4-digit filing year, e.g. "2025".
month: 2-digit filing month, e.g. "06". Requires year.
include_item_105: Include Item 1.05 filings.
include_item_801: Include Item 8.01 filings.
limit: Max records to return (1-200).
offset: Skip this many records; use next_offset from a prior call.
| Name | Required | Description | Default |
|---|---|---|---|
| cik | No | ||
| year | No | ||
| limit | No | ||
| month | No | ||
| offset | No | ||
| ticker | No | ||
| include_item_105 | No | ||
| include_item_801 | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate the tool is read-only and non-destructive, and the description adds substantial behavioral context beyond that: the regulatory cutoff, the distinction between Item 1.05 and Item 8.01, configurable item filters, and pagination behavior via `next_offset`. There is no contradiction with the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficient and well-structured: a one-sentence purpose, a short contextual note about items and timing, and a compact Args list. Every sentence earns its place, and the most important identification cues are front-loaded. The length is justified by the need to document eight parameters.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists and annotations cover the safety profile, the description is complete for an agent to select and invoke this tool correctly. All eight parameters are semantically documented, pagination is explained, and the tool's narrow scope is clear. No critical operational detail is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage and provides only types and defaults, so the description carries the full burden. The Args section thoroughly documents every parameter with format examples, constraints (e.g., uppercase ticker, 4-digit year, 1-200 limit), and dependencies (e.g., month requires year). This far exceeds the baseline for an uncovered schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Get'), a specific resource ('SEC Form 8-K filings'), and a clear scope ('disclosing cybersecurity incidents'). It further distinguishes itself by naming the exact SEC items covered, making it easy for an agent to understand what this tool does and how it differs from unrelated siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for use: it covers Item 1.05 and Item 8.01 filings, explains the regulatory timeline, and gives a conditional rule ('month requires year'). It does not explicitly name alternatives, but no sibling appears to be an alternative, so the lack of a when-not-to-use clause is not a meaningful gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get platform-wide totals: victim count, tracked group count, press entry count, and the timestamp of the most recently discovered victim.
Useful as a cheap freshness check before running larger queries.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, covering the safety profile. The description adds the 'cheap' performance hint and clarifies it returns aggregate counts and a timestamp, which is useful context. No contradictions; the description doesn't disclose additional behavioral traits beyond annotations, but that's acceptable given the annotations are comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loads the purpose, and the usage note is a single clause. No fluff or redundant content; every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a no-parameter, read-only tool with an output schema, the description fully conveys what it returns and when to use it. The presence of an output schema handles return values, so nothing an agent needs to call it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline is 4. The description doesn't need to explain parameters; it's a no-argument call. Schema coverage is 100% (vacuously), so nothing is missing.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves platform-wide totals: victim count, tracked group count, press entry count, and latest victim timestamp. It distinguishes from siblings by being a global summary, not specific to any entity. The verb 'Get' and resource 'platform-wide totals' are specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear use case: 'cheap freshness check before running larger queries.' It implies when to use it (before expensive queries) but doesn't explicitly name alternatives or when-not scenarios. No exclusions are stated, but the context is clear enough for an agent to decide.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the full enriched record for one victim by its Base64 ID.
The ID is Base64 of "victim_name@group_name" and appears as the id field
in every victim listing. If you only have the names, use
build_victim_id first. Returns 404 if the listing was taken down.
Args:
victim_id: Base64-encoded victim ID from a listing's id field.
| Name | Required | Description | Default |
|---|---|---|---|
| victim_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds meaningful behavioral context beyond annotations by noting the tool 'Returns 404 if the listing was taken down' and that the returned data is a 'full enriched record,' which helps the agent understand failure modes without needing to call the tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: purpose first, then ID format, then the alternative tool, then the 404 behavior, and finally an Args section. Every sentence contributes distinct information without redundancy or fluff, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter read tool, the description covers the ID source and format, the prerequisite tool for building an ID, the key error condition, and the enriched nature of the output. The presence of an output schema means return-value details are not needed in the description, so nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries full responsibility for explaining `victim_id`. The Args section explicitly defines it as 'Base64-encoded victim ID from a listing's `id` field,' and the earlier paragraph reveals the format (Base64 of 'victim_name@group_name'), giving the agent everything needed to construct or recognize a valid parameter value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The first sentence states a specific verb and resource: 'Get the full enriched record for one victim by its Base64 ID.' It clearly distinguishes this from listing, searching, and filtering sibling tools by targeting a single victim via a unique ID, and even references the companion `build_victim_id` as an alternative path.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit guidance: 'If you only have the names, use `build_victim_id` first,' and explains that the ID appears in every victim listing, which tells the agent when the ID is readily available. It does not explicitly enumerate when-not-to-use cases for other sibling tools like search_victims or filter_victims, but the single-record-by-ID scope makes the usage context clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get every YARA rule for a group, each with filename and full rule text.
The returned content is ready to feed to a YARA scanner.
Args: group: Group name, e.g. "lockbit3", "blackcat".
| Name | Required | Description | Default |
|---|---|---|---|
| group | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare `readOnlyHint: true` and `destructiveHint: false`, so the safety profile is covered. The description adds useful behavioral context beyond that: the output includes `filename` and full rule text, and the returned content is 'ready to feed to a YARA scanner.' It does not discuss error behavior, but the read-only nature lowers the bar.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: the core purpose appears in the first sentence, followed by a useful output note and a minimal Args section. Every sentence earns its place with no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has a single required parameter, clear annotations, and an output schema, the description covers the essential behavior well. It does not mention how to obtain valid group names or what happens for unknown groups, but these are minor omissions for a simple read-only retrieval tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate for the undocumented `group` parameter. It does add meaning with examples ('lockbit3', 'blackcat') and clarifies group is a group name. However, it does not explain how to discover valid groups or whether the value must match a known YARA group from `list_yara_groups`, leaving a partial gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Get every YARA rule for a group.' It also states the exact returned fields (`filename` and full rule text), making the tool's function unambiguous and distinct from sibling tools like `list_yara_groups` or `get_group_iocs`.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The usage context is implied: use this when you need all YARA rules for a given group. However, it does not explicitly mention alternatives, prerequisites, or that valid group names likely come from `list_yara_groups`. No exclusions or when-not guidance are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List negotiation chats for a group with ransom and outcome metadata.
Each entry carries id (pass to get_negotiation), message_count,
initialransom, negotiatedransom, and paid.
Args: group: Group name, e.g. "lockbit3".
| Name | Required | Description | Default |
|---|---|---|---|
| group | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the operation as readOnlyHint=true and destructiveHint=false, so the description does not need to restate safety. It adds context by listing the metadata fields each entry carries and cross-references get_negotiation, but it does not disclose behavior for unknown groups, empty results, pagination, or ordering.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded, with the core action stated in the first sentence. The metadata breakdown and argument documentation each serve a clear purpose, and there is no filler or redundant content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter, read-only tool with an existing output schema, the description covers the purpose, the argument, and the key output fields. It does not elaborate on error cases or empty results, but those are not critical given the low complexity and the annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries the full burden for parameter meaning. It defines 'group' as 'Group name' and provides a concrete example ('lockbit3'), which is sufficient for an agent to construct a valid call. No further format constraints are needed for this single free-text parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'List negotiation chats for a group with ransom and outcome metadata.' This makes the tool's purpose clear and distinct at a glance. However, it does not explicitly differentiate itself from sibling tools such as list_negotiation_groups or get_negotiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a useful parameter example ('lockbit3') and notes that the returned id should be passed to get_negotiation, which provides some downstream routing. It does not state when to use this tool versus list_negotiation_groups or other list-related siblings, nor does it mention prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the ransom note identifiers available for one group.
Pass a returned name to get_ransomnote to read its content.
Args: group: Group name, e.g. "lockbit3", "clop".
| Name | Required | Description | Default |
|---|---|---|---|
| group | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful scoping ('for one group') and output semantics ('identifiers'), but does not disclose availability, rate limits, or other behavioral details. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short, front-loaded with the primary action, and every sentence earns its place: what it lists, how the output is consumed, and the argument definition. There is no redundant prose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a low-complexity, single-parameter tool with a read-only annotation and an output schema, the description is complete. It explains the purpose, the argument semantics, and the intended follow-up call, which is all an agent needs to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description carries the full burden for the single parameter. It defines group as a 'Group name' and gives concrete examples ('lockbit3', 'clop'), making the required string actionable. This is exactly the compensation needed for a schema that only provides the title 'Group'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and object: 'List the ransom note identifiers available for one group.' It clearly scopes the tool to one group and distinguishes it from the content-reading sibling get_ransomnote by noting that the output is identifiers, not content.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a clear downstream instruction—feed a returned name to get_ransomnote—and implicitly defines the use case: enumerate IDs for a group. However, it does not explicitly contrast with the sibling list_ransomnote_groups or say when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all tracked ransomware groups alphabetically with victim counts.
Each entry has group (the lowercase name used by every other tool),
altname, and victims. Call this to resolve a group name before using
get_group, get_group_iocs, get_yara_rules and similar.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| offset | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only and non-destructive behavior, and the description does not contradict that. It adds useful behavioral context beyond the annotations: results are alphabetical, each entry includes victim counts, and the returned group value is the canonical lowercase name used across other tools. It does not mention pagination behavior, but the annotation coverage lowers that burden.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well structured: purpose first, then return-field details, then usage guidance. Every sentence adds information, and there is no filler or redundancy with the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return-value details are covered elsewhere, and the read-only annotations handle safety. The description is complete for the core use case of resolving group names before calling sibling tools, but it leaves pagination behavior implicit, which is a minor gap for a tool whose only parameters are limit and offset.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries responsibility for explaining limit and offset. The description never mentions these parameters or how pagination works; the names and defaults are self-explanatory, but the agent is not told that offset pages through the alphabetical list or that the default limit truncates results.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb ('List'), a specific resource ('all tracked ransomware groups'), and includes useful scope details (alphabetical order, victim counts). It also distinguishes this master group-list from the many sibling group-specific tools by noting that it returns the lowercase group name used by every other tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit guidance: call this to resolve a group name before using get_group, get_group_iocs, get_yara_rules, and similar tools. This tells the agent both when this tool is appropriate and what alternatives it feeds into.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List ransomware groups that have IOCs on file, with per-type counts.
Common IOC types: md5, sha256, ip, domain, email, btc, url.
Args: ioc_type: Only return groups holding this IOC type, e.g. "ip".
| Name | Required | Description | Default |
|---|---|---|---|
| ioc_type | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful context about per-type counts and that only groups with IOCs are returned, but does not add substantial behavior beyond that. No contradiction exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences with zero filler. The main purpose is front-loaded, supported by a compact list of common IOC types and a clearly formatted Args section.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list tool with one optional parameter, the description fully supports correct invocation. The output schema exists to cover return shape, annotations cover safety, and the description covers filtering semantics and example values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must carry the meaning of ioc_type. It does: 'Only return groups holding this IOC type, e.g. "ip"' plus a list of common values. This gives the agent the semantics and an example, though it does not explicitly state that omitting the parameter returns all groups.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description states a specific verb and resource: 'List ransomware groups that have IOCs on file, with per-type counts.' This clearly distinguishes the tool from siblings like list_groups or list_yara_groups by scoping to groups with IOCs and adding count behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool: to list ransomware groups with IOCs, optionally filtered by ioc_type. It does not explicitly name alternatives or exclusions, but the optional parameter guidance and examples make the intended usage unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List ransomware groups with leaked negotiation chat logs, and chat counts.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish that this is read-only, open-world, and non-destructive. The description adds useful behavioral context by specifying the filtering criterion and that chat counts are included, which is beyond what annotations state.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no filler. It front-loads the verb and resource and immediately states the distinguishing qualifier.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter listing tool with an output schema and read-only/open-world annotations, the description is sufficient. No pagination, return-value, or parameter details are necessary here.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and schema description coverage is 100%, so there are no parameter semantics to clarify. Baseline 4 applies for a no-parameter tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb (List) and a specific resource (ransomware groups) with a clear qualifier: only those with leaked negotiation chat logs. This distinguishes it from sibling tools like list_groups (all groups) and list_group_negotiations (negotiations for a group).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The qualifier 'with leaked negotiation chat logs' provides clear context for when the tool should be used. It does not explicitly name alternatives or exclusion conditions, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List ransomware groups that have ransom notes on file, with note counts.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds the specific detail that results include note counts, which is minor but useful. It does not contradict annotations and provides a small amount of behavioral context beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence with no filler. Every word earns its place: it identifies the resource, the filter condition, and the output detail. Perfectly concise for a no-parameter tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a no-parameter read-only list operation with an output schema available, the description fully covers what an agent needs to decide whether to call it and what to expect. There are no hidden requirements or edge cases mentioned, but none are apparent given the simplicity of the operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters and the schema coverage is 100% (empty schema). Since there are no parameters to document, the baseline is 4 per the rubric. The description adds nothing about parameters, but none are needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('List'), a clear resource ('ransomware groups'), and a distinguishing qualifier ('that have ransom notes on file, with note counts'). This immediately differentiates it from sibling tools like list_groups (all groups) and list_group_ransomnotes (notes for a specific group). The purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool (when you need groups that have ransom notes and their counts), but it does not explicitly mention alternatives or exclusion criteria. With many sibling tools that differ by entity type (IOCs, YARA, negotiations), the routing is implied rather than spelled out.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List every victim sector/industry value with a victim count per sector.
The sector values returned here are the valid inputs for the sector
filter on search_victims and filter_victims.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds meaningful behavioral context: the tool returns every sector value with a victim count and that the results are authoritative for filter inputs. This goes beyond what the annotations express, though it does not cover sorting or exact response structure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no filler. The first sentence states the action and output; the second immediately explains the practical downstream use. The key information is front-loaded and every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-param tool with an output schema and clear annotations, the description is complete. It tells the agent what it will get (all sectors with counts) and how to use that result (as filter inputs). Nothing essential is missing for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so parameter semantics are trivially irrelevant. The description correctly does not mention any parameters, and the schema coverage is 100% by default. No additional param documentation is needed or possible.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and resource ('victim sector/industry value') and clarifies the output includes a count per sector. It also explicitly differentiates itself by stating these values are the canonical inputs for the `sector` filter on `search_victims` and `filter_victims`, distinguishing it from other list tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies when to use this tool: when the agent needs valid sector values for filtering victims. It names the dependent tools (`search_victims`, `filter_victims`) and explains the relationship. It does not explicitly state when not to use it or mention alternatives, but the context is strong enough to guide selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List ransomware groups that have YARA detection rules, with rule counts.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare this a read-only, non-destructive operation. The description adds useful behavioral context by specifying that results include rule counts, which helps set expectations beyond the bare readOnlyHint without contradicting it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. Every word contributes to indicating scope, selection criterion, and the nature of the returned data.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple parameterless listing tool with an output schema and safety annotations, the description is complete. It tells the agent what the tool returns, what subset it covers, and that counts are included.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so there is nothing for the description to explain. Per the baseline for parameterless tools, the description does not need to add parameter-level detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'List ransomware groups that have YARA detection rules'. It clearly distinguishes this tool from siblings like list_groups, list_ioc_groups, and get_yara_rules by tying the listing specifically to YARA rule availability and including rule counts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description makes the selection condition explicit: it is for ransomware groups that have YARA detection rules, not all groups or groups with IOCs. It does not name alternatives or exclusions explicitly, but the context is clear enough for an agent to choose it appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search all tracked cyberattack press entries by year, month and country.
Results are sorted newest first.
Args:
year: 4-digit year, e.g. "2024".
month: 2-digit month, e.g. "03". Requires year.
country: ISO 3166-1 alpha-2 country code, e.g. "FR".
limit: Max records to return (1-200).
offset: Skip this many records; use next_offset from a prior call.
full: Include all enrichment fields.
| Name | Required | Description | Default |
|---|---|---|---|
| full | No | ||
| year | No | ||
| limit | No | ||
| month | No | ||
| offset | No | ||
| country | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, and the description is consistent with them. It adds valuable behavioral details beyond the annotations: results are sorted newest first, month requires year, offset should reuse next_offset from a prior call, and limit is constrained to 1-200. These details meaningfully shape how the tool behaves.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with a one-sentence purpose, followed by a concise sort-order note and a compact Args list. Every line adds necessary information, with no fluff or repetition of schema defaults. The length is appropriate for six parameters that need semantics.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has six parameters, a rich output schema, and annotations that cover safety, so the description only needs to cover calling conventions. It fully explains parameter formats, dependencies, sorting, and pagination. The pointer to 'use next_offset from a prior call' is especially practical. Nothing an agent needs to invoke the tool correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must fully compensate for missing parameter documentation. It does so by explaining every parameter with concrete formats and examples: year as '2024', month as '03', country as an ISO 3166-1 alpha-2 code, limit with a numeric range, offset with pagination semantics, and full as an enrichment toggle. This is complete and goes beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Search'), a clear resource ('all tracked cyberattack press entries'), and the filtering dimensions (year, month, country). This makes the tool's purpose immediately obvious. However, it does not explicitly distinguish itself from the sibling tool get_recent_press, which likely serves a similar but more recent-focused use case, so it does not earn a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as get_recent_press or search_victims. It explains how to call the tool but not which scenarios it is best suited for. There are no explicit exclusions or mentions of sibling tools, so an agent must infer usage context from the parameter list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Free-text search across victim organisation names and website domains.
q is matched case-insensitively as a substring of both the victim name
and the website. The other filters narrow further with AND logic.
Args:
q: Keyword, e.g. "hospital", "university", "acme".
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", "FR", "DE".
order: Sort by "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.
| Name | Required | Description | Default |
|---|---|---|---|
| q | No | ||
| full | No | ||
| group | No | ||
| limit | No | ||
| order | No | discovered | |
| offset | No | ||
| sector | No | ||
| country | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond the readOnlyHint/openWorldHint annotations by explaining that q is matched case-insensitively as a substring of both victim name and website, and that all filters combine with AND logic. It also discloses pagination semantics via next_offset and the meaning of the full flag. This gives the agent a clear model of how the tool behaves at call time.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose and then provides a compact, structured Args list. Every sentence adds value: matching behavior, filter logic, parameter details, and pagination. There is no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 8 optional parameters, no schema descriptions, and an output schema present, the description is complete. It covers search semantics, filtering, sorting, pagination, and the full flag, while the output schema handles return-value details. Nothing an agent needs to invoke this correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description carries full responsibility for parameter documentation, and it succeeds. Every parameter is explained: q with examples, group/sector with references to list endpoints, country with ISO format, order with enum values, limit with a 1-200 range, offset with pagination guidance, and full with its effect. This is exemplary compensation for an otherwise bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Free-text search across victim organisation names and website domains.' It clearly defines the tool's scope and differentiates it from sibling tools like search_press and filter_victims by naming the searched entity (victims) and the two searchable fields (name and domain). The Q parameter and matching behavior further clarify the intended use.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context: use this tool for free-text search over victim names/websites, with optional structured filters combined via AND logic. It also instructs on exact values by referencing list_groups and list_sectors, and explains pagination using next_offset. It does not explicitly contrast with filter_victims or get_recent_victims, but the described behavior is enough to infer appropriate use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check that the configured RANSOMWARE_LIVE_API_KEY is valid and active.
Returns the client identifier tied to the key. Run this first when any other tool reports an authentication failure.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the description correctly doesn't repeat those. It adds value by specifying the check's semantics (valid and active) and the return (client identifier), plus the operational guidance to run first on auth failures. This is useful context beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero filler. The core purpose and condition are front-loaded, and the return value is included. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-param tool with an output schema, the description explains what it does, what it returns, and when to use it. Nothing an agent needs to invoke it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has zero parameters, so the schema already covers everything. The description correctly doesn't waste space on parameter details. Baseline 4 for zero-param tools is appropriate; no compensation needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Check') and resource ('RANSOMWARE_LIVE_API_KEY'), and explains the purpose: validity and activity. It also notes the return value (client identifier), distinguishing it from all sibling tools, none of which handle authentication validation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: 'Run this first when any other tool reports an authentication failure.' This gives clear context for ordering and troubleshooting, and implies it's a diagnostic first step. No exclusions needed since there are no alternative validation tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0build_victim_iddecode_victim_identifierfilter_victimsget_csirt_contactsget_groupget_group_iocsget_negotiationget_ransomnoteget_recent_pressget_recent_victimsget_sec_8k_filingsget_statsget_victimget_yara_ruleslist_group_negotiationslist_group_ransomnoteslist_groupslist_ioc_groupslist_negotiation_groupslist_ransomnote_groupslist_sectorslist_yara_groupssearch_presssearch_victimsvalidate_api_keyScored across 25 tools
Each tool targets a distinct resource and action, with clear list/get navigation pairs for victims, IOCs, YARA rules, ransom notes, and negotiations. A couple of names are near-permutations (list_ransomnote_groups vs list_group_ransomnotes; list_negotiation_groups vs list_group_negotiations), so an agent could misselect without reading the descriptions.
All tool names are verb-first snake_case (validate, get, list, search, filter, build, decode), giving a predictable overall style. Minor deviations include 'id' vs 'identifier' between build_victim_id and decode_victim_identifier, and the swapped noun order in the list_<type>_groups / list_group_<type> pairs.
25 tools is at the heavy end, but the server spans many distinct intelligence domains (victims, groups, IOCs, YARA, ransom notes, negotiations, press, SEC filings, CSIRT contacts), so the count is justified. It feels slightly over-packed rather than redundant.
The tool surface gives complete read-only coverage of the exposed domain: every artifact type has listing plus retrieval, with navigation helpers (build/decode victim ID, sector/group enumerations) that avoid dead ends. Since this is an intelligence/retrieval API, write operations are not an expected part of the lifecycle.
Enrich, search, assess, and manage threat intelligence through 80+ typed MCP tools.
Read-only MCP access to a documented IT fleet: state, changes, posture. 15 tools.
Read-only MCP: free OpenAI security evidence ledger (55 fields) + SaaSDossier release register.
Read-only DERO blockchain MCP: 33 tools (12 composites) incl. TELA discovery + bundled docs.
