Agents & MCPInvestigator
Tool Reference
Every nano-investigator tool, MCP prompt, and MCP resource, with parameters and access level
Tool Reference
The server registers 69 tools across ten areas, plus five MCP prompts and a set of MCP resources. The Access column is one of:
- Read: queries the SIEM, no side effects
- Write: creates or modifies data
- Write-destructive: closes or removes data; the agent should confirm first
In the Key params column, parameters are required unless marked (opt).
Search & schema
Nine tools. search_sql is the primary search tool; it runs read-only ClickHouse SELECT queries (DROP/INSERT and SLEEP/HOSTNAME are blocked) and the backend caps results at 100k rows.
| Tool | Purpose | Key params | Access |
|---|---|---|---|
search_sql | Primary search. Read-only ClickHouse SELECT. | sql; start_time, end_time, limit (opt, default window -24h to now) | Read |
search | Run an nPL (piped, Splunk-style) query. Good for quick |stats / |timechart. | query, start_time; end_time, limit (opt, 100), source_type (opt) | Read |
get_schema | UDM column inventory by category plus observed ext JSON keys. Call once per session before writing SQL. | category (opt), include_ext (opt, true) | Read |
explain_query | Compile nPL to SQL without executing. | query, start_time; end_time (opt) | Read |
get_field_values | Top values (value, count, pct) for a field in a query scope. | field, start_time; query (opt, *), end_time (opt), limit (opt) | Read |
list_saved_searches | List saved searches. | none | Read |
get_saved_search | Fetch one saved search by id. | id | Read |
save_search | Save an nPL or SQL query. | name, query; query_mode (opt, piped/sql), visibility (opt, private/public/group) | Write |
create_shared_search | Build a shareable SIEM-UI URL for a query and time range. | query; query_mode (opt), time_range_type (opt, relative), time_range_start (opt), time_range_end (opt) | Write |
Alerts & triage
Three tools, all read-only. Alerts cannot be mutated; triage happens by adding an alert to a case (see Cases).
| Tool | Purpose | Key params | Access |
|---|---|---|---|
list_alerts | List alerts with filters. | all opt: status (new/acknowledged/closed), severity, rule_id, assigned_to, limit (50), offset | Read |
get_alert | Full alert detail, including matched events and ai_triage_hints. | id | Read |
get_alert_counts | Counts by severity and status. | none | Read |
Cases
Twelve tools. The read tools cover listing, detail, related cases, and stats; seven tools write. merge_cases is destructive.
| Tool | Purpose | Key params | Access |
|---|---|---|---|
list_cases | List cases with filters. | all opt: status[], severity[], assigned_to, search, tags[], limit, offset | Read |
get_case | Full case detail. | id | Read |
review_case | Composite read: case plus wall plus all linked notebooks (entries and refs, batched 5). First call when resuming a case. | id (id or case number) | Read |
get_case_stats | Counts by status and severity, plus average resolution. | none | Read |
get_related_cases | Historically similar cases (shared entities, rules, MITRE). | id | Read |
create_case | Create a case. | title, severity; description, priority, assigned_to, tags[] (opt) | Write |
update_case | Update case fields. | id; title / description / severity / tags (opt) | Write |
change_case_status | Change status, optionally with a disposition. | id, status (open/in_progress/pending/resolved/closed); disposition (opt, true_positive/false_positive/benign/inconclusive) | Write |
assign_case | Assign a case to a user. | id, user_id | Write |
add_alert_to_case | Link an alert to a case. | case_id, alert_id; is_primary (opt) | Write |
add_case_wall_entry | Post an entry to the case wall. | case_id, entry_type (comment/ai_analysis/action_taken), content; is_internal (opt) | Write |
merge_cases | Merge source cases into a target. Source cases are closed as merged. | target_case_id, source_case_ids[] | Write-destructive |
Notebooks
Nine tools. Four read, five write.
| Tool | Purpose | Key params | Access |
|---|---|---|---|
list_notebooks | List notebooks. | all opt: case_id, status (active/paused/closed/merged), limit, offset | Read |
get_notebook | Fetch one notebook. | id | Read |
get_notebook_entries | Fetch a notebook's entries. | id | Read |
find_notebooks_by_reference | Find notebooks referencing a given object. | reference_type (alert/detection/saved_search/case), reference_id | Read |
create_notebook | Create a notebook. | title; visibility (opt, private/shared/public) | Write |
add_notebook_entry | Append an entry. entry_type is one of manual_note, search_executed, ai_suggestion, ai_summary, entity_reference, ioc_marker, timeline_marker, investigation_timeline. | notebook_id, entry_type, content (object); source_url (opt) | Write |
add_notebook_reference | Add a reference to a notebook. | notebook_id, reference_type, reference_id; reference_name (opt) | Write |
update_notebook | Update notebook fields. | id; title, status (active/paused/closed), summary (opt) | Write |
share_notebook | Share a notebook. | id, visibility; group_ids[] (opt) | Write |
Detections & MITRE
Five tools, all read-only. The investigator reads detections; editing them stays in nanodac.
| Tool | Purpose | Key params | Access |
|---|---|---|---|
list_detections | List detection rules. | all opt: severity, mode (staging/live/alerting), enabled | Read |
get_detection | Full rule (nPL, MITRE, ai_triage_hints, schedule, stats). | id (UUID) | Read |
get_detection_matches | Recent matches for a rule. | id (UUID) | Read |
get_mitre_technique | ATT&CK data, optionally filtered to one technique. | id (opt, e.g. T1071) | Read |
get_mitre_coverage | Coverage and gaps of the detection library. | none | Read |
Entities & risk
Three tools, all read-only.
| Tool | Purpose | Key params | Access |
|---|---|---|---|
get_risky_entities | Top entities by risk. | all opt: window (24h/7d/all), entity_type, min_score, limit (20) | Read |
get_risk_overview | Counts by risk level (24h and 7d). | none | Read |
get_entity_risk_timeline | Risk over time for one entity. | entity; entity_type (opt) | Read |
Enrichment / IOC
Two tools, all read-only. IOC matching is applied at ingest into the ioc_matched / ioc_threat_type / ioc_confidence columns, so threat-intel hunting is done with search / search_sql on those columns rather than a lookup tool.
| Tool | Purpose | Key params | Access |
|---|---|---|---|
get_entity_context | Composite pivot: parallel GeoIP (IPs) and risk-timeline lookups for an entity. | entity_type (ip/user/host/domain/hash), value | Read |
lookup_ip | GeoIP plus ASN for an IP. | ip | Read |
Prevalence
Three tools, all read-only. get_prevalence accepts only hash or domain; passing an IP errors. get_rare_artifacts and get_new_artifacts do accept ip_address.
| Tool | Purpose | Key params | Access |
|---|---|---|---|
get_prevalence | How common an artifact is: host count, occurrences, first/last seen, is_rare. | type (hash or domain only; IP errors), value | Read |
get_rare_artifacts | Artifacts seen on few hosts. | all opt: type (hash_md5/hash_sha256/domain/ip_address), window, limit (50), offset | Read |
get_new_artifacts | Artifacts first seen recently. | all opt: type, since, limit (50), offset | Read |
System / org
Four tools, all read-only.
| Tool | Purpose | Key params | Access |
|---|---|---|---|
get_source_types | Available log source types. Call before using source_type filters. | none | Read |
get_org_context | Org profile: industry, compliance, internal IP ranges, critical assets, business hours. | none | Read |
health_check | ClickHouse and PostgreSQL connectivity. | none | Read |
get_audit_trail | Query the audit log, including the MCP key's own actions. | all opt: user_id, action, resource_type, start_time, end_time, limit (50) | Read |
Parsers
Nineteen tools for authoring log-source parsers (Vector VRL) and wiring their ingress. Most write; none is data-destructive, but deploy_log_source changes what Vector ingests and is best-effort (it can return success even if Vector failed to reload), so pair it with get_log_source_health. Open-edition — AI parser generation stays in the Enterprise wizard. See Build parsers for the workflow.
| Tool | Purpose | Key params | Access |
|---|---|---|---|
list_log_sources | List parsers (summary). | all opt: source_type, deployed, enabled, kind (log/enrichment) | Read |
get_log_source | Full parser: parser_vrl, metadata, validated/deployed flags. | id | Read |
validate_vrl | Compile-check VRL without saving. Returns valid, errors, and diagnostics (line/col + code). | vrl_code | Read |
test_parse_sample | Run VRL against one sample line; returns parsed output and extracted_field_count. | vrl_code, sample_log; extension_vrl (opt) | Read |
test_parse_live | Parse real recent events for a source_type, new vs currently-deployed VRL. Capped at 20 events. | vrl_code, source_type; current_vrl, limit (opt) | Read |
create_log_source | Save a new parser as a draft (validated, not deployed). | name, source_type, parser_vrl; description, namespace, timezone, category, vendor, product, source_config (opt) | Write |
update_log_source | Edit a parser. Editing VRL does not auto-deploy. | id; parser_vrl / name / source_type / metadata / enabled (opt) | Write |
deploy_log_source | Write the Vector config and reload. Best-effort — confirm with get_log_source_health. | id | Write |
undeploy_log_source | Take a deployed parser offline. | id | Write |
get_log_source_health | 24h/last-hour event counts, freshness, parse errors, health_status (healthy/stale/no_data/disabled/error). | id | Read |
get_log_source_deployments | Deploy/undeploy history with status and errors. | id | Read |
list_source_config_types | Transport drivers (HTTP, Kafka, S3, GCP Pub/Sub, Splunk HEC, Vector) with match_field presets. | none | Read |
list_source_configs | Configured ingress transports. | config_type, enabled (opt) | Read |
create_routing_rule | Map incoming events to a parser's source_type. | source_config_id, match_field, match_type (exact/prefix/suffix/regex/contains/default), target_source_type; match_value, priority (opt) | Write |
check_rule_reachability | Verify a candidate rule can deliver: config enabled + deployed, target parser exists, broker reachable (Kafka). | source_config_id, target_source_type, match_field, match_type, match_value | Read |
list_parser_repositories | Connected upstream parser libraries and sync status. | none | Read |
sync_parser_repository | Refresh the local cache from an upstream repo. | repository_id | Write |
list_repository_parsers | Browse prebuilt parsers in a repository. | repository_id; category, search (opt) | Read |
import_parser | Import a repo parser as a draft log source. | repository_id, path; source_type, import_type (linked/forked), ingestion_method (opt) | Write |
MCP prompts
The server registers five prompts. These are structured workflows the agent follows, not callable tools.
investigate_alert(args:alert_id;depthopt quick/standard/deep). Runsget_alert, thenget_detectionforai_triage_hints, assesses FP vs TP againstignore_when/suspicious_when, enriches entities (get_entity_context/lookup_*/get_prevalence), runs one or two searches for related activity, thenget_related_cases, and finishes with an FP / needs-investigation / TP recommendation. It does not go more than two levels deep without checking in;quickstops after step 3.hunt_entity(args:entityandentity_type;time_rangeopt -24h). Phase 1 gathers context (parallelget_entity_context,lookup_*,get_prevalence, and a search), Phase 2 presents an assessment before continuing, Phase 3 runs a type-specific deep dive (ip / user / host / hash / domain branches with nPL templates).hunt_campaign(args:description;time_rangeopt -7d). Plans withget_mitre_techniqueandget_source_typesplus three to five queries, builds and runs with refinement, enriches hits (get_prevalence, theioc_*columns, related alerts and cases), then writes a hunt report. Rule creation defers to nanodac.morning_briefing(arg:hoursopt 12). Runsget_alert_countsandlist_alerts(critical/high),get_case_stats,get_risky_entities(10),list_detectionsfor noise or silence, andhealth_check, ending in a shift-handoff briefing with prioritized actions.build_parser(args:source_type;sample_logopt). Scripts a validate-first authoring loop: read the VRL reference,list_log_sourcesto avoid duplicates, draft a generic parser,validate_vrluntil it compiles,test_parse_sampleagainst the sample,create_log_sourceas a draft,deploy_log_source, thenget_log_source_healthto confirm events flow. Presents the VRL and test output before saving and confirms before deploying.
MCP resources
The server registers these resources:
nano://sql-guide: SQL guidance forsearch_sqlnanosiem://schema/udm: the UDM schemananosiem://reference/npl: the nPL referencenanosiem://reference/vrl-parsers: the VRL parser authoring guide — input/output contract, the rules the validator enforces, forbidden functions, and skeletons (used bybuild_parser)nanosiem://reference/playbooks/{type}: investigation playbooks for seven types:brute_force,lateral_movement,data_exfil,malware,phishing,insider_threat,generic