Skip to main content
Glama

Find identifier across captures

find_identifier
Read-onlyIdempotent

Locate capture files that mention an IMSI, MSISDN, IP address, SIP Call-ID, or Diameter Session-Id; returns hit counts, timestamps, and protocol breakdowns to pick the right file for pcap_info.

Instructions

Find which capture files mention an identifier. path is one capture or a directory inside the allowed roots (its .pcap/.pcapng/.cap files are scanned, not subdirectories). identifier is an IMSI, MSISDN, IPv4/IPv6 address, SIP Call-ID or Diameter Session-Id; kind is auto, imsi, msisdn, ip, call_id or session_id (auto searches digits as both IMSI and MSISDN). Returns one row per file with hits: hit count, first and last timestamp and a per-protocol breakdown, sorted by hits. At most max_files files are opened (capped by the server), each under the usual packet, size and time limits, and the whole call shares one time budget; files that could not be read are listed under errors. Use it to pick the file before pcap_info.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "path": "<path>",
      "identifier": "<identifier>"
    },
    "name": "find_identifier"
  }
}

Input Schema

NameRequiredDescriptionDefault
endNoSame forms as start
kindNoauto, imsi, msisdn, ip, call_id, session_idauto
pathYesAbsolute path of a capture file or a directory of captures
startNoISO 8601, epoch s, +Ns from start, -Ns from end
offsetNoRows to skip (next_offset)
redactNoReplace subscriber identifiers in this result with tokens; ids+ips hides every IP toooff
max_filesNoMost files read in this call
identifierYesIMSI, MSISDN, IP, Call-ID or Diameter Session-Id

Output Schema

NameRequiredDescriptionDefault
kindNo
noteNo
countNo
errorNo
filesNorows with keys: path, hits, first, last, protocols, truncated, truncated_reason, first_frame, last_frame
errorsNorows with keys: path, error, message
offsetNo
windowNo
droppedNo
has_moreNo
returnedNo
identifierNo
total_hitsNo
files_foundNo
next_offsetNo
total_foundNo
files_scannedNo
total_matchedNo
display_filterNo
files_with_hitsNo
packets_matchedNo
packets_scannedNo
files_not_scannedNo
partially_scannedNo
files_outside_windowNo
total_is_lower_boundNo
subdirectories_with_capturesNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.7/5.0
Behavior5/5

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

Annotations already declare readOnly/idempotent/non-destructive, and the description goes well beyond them: max_files is capped server-side, each file obeys packet/size/time limits, the whole call shares one time budget, unreadable files surface under `errors`, and results are sorted by hits. This is exactly the operational context an agent cannot get from annotations.

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

Conciseness5/5

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

Dense but disciplined: purpose first, then path semantics, then identifier/kind, then the return shape, then limits, then the pcap_info handoff. Every sentence carries distinct information with no restatement of the name or title.

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

Completeness5/5

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

Covers the full arc for an 8-parameter, non-trivial tool: what is scanned, what the identifier types are, how results are shaped and sorted, what resource caps apply, and how failures are reported. An output schema exists, yet the added row-level summary is still useful for planning.

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

Parameters4/5

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning: `kind`=auto "searches digits as both IMSI and MSISDN," and `path` scans a directory's .pcap/.pcapng/.cap files without recursing. It is silent on start/end/offset/redact, which the schema covers adequately.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb+resource: "Find which capture files mention an identifier." It immediately distinguishes itself from the sibling it could be confused with by closing with "Use it to pick the file before pcap_info," so an agent knows this is a file-selection step, not a detail-extraction step.

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

Usage Guidelines4/5

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

Gives a clear usage context (pick the file before pcap_info) and a scope rule (a directory's own captures are scanned, not subdirectories). It does not state when NOT to use it or name any alternative besides pcap_info, so it stops short of full routing guidance.

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