Skip to main content
Glama
Sign In
nagameTW

mcp-server-malcolm

by nagameTW
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

List unique values of one field

arkime_unique
Read-only

List distinct values of a single Arkime field with optional per-value counts. Use to see what values a field holds, lighter than full aggregation.

Instructions

List distinct values of ONE Arkime field as plain text, optionally with counts.

    For distinct value COMBINATIONS across a tuple of fields use
    arkime_multiunique; for top values of one field plus a time-series graph
    use arkime_spigraph; to profile many fields in one call use
    arkime_spiview. Lighter than a full aggregation when you only need to see
    what values a field holds.

    Returns plain TEXT (one value per line, not JSON) — Arkime streams it
    directly. "(no values)" has TWO causes and this route cannot tell them
    apart: the window holds nothing, or the field name does not resolve.
    field="nosuch.field" over a window holding data answers HTTP 200 with
    a zero-byte body, exactly like a
    genuinely empty result — where every sibling is loud (arkime_multiunique
    says "Unknown expression", arkime_spigraphhierarchy answers 403,
    arkime_sessions_summary lists the name in ignored_fields). So check the
    spelling against arkime_field_search's exp column before assuming the
    window is wrong; only then pass time_from.

    A wide field is truncated silently at Arkime's aggregation ceiling of
    10,000 values, with no marker and no error. Treat a round 10,000 as
    "there are more", and scope
    with expression rather than reading it as the whole value set.

Input Schema

NameRequiredDescriptionDefault
fieldYesOne Arkime field expression, e.g. "ip.dst", "protocols", "http.host".
countsNoInclude a per-value occurrence count (default true). Turning it off drops the count from every line and is the right choice when you only need the value set itself — to paste into arkime_create_shortcut, for instance.
time_toNoEnd time as EPOCH SECONDS (NOT a dateparser string). Empty = now.
time_fromNoStart time as EPOCH SECONDS (NOT a dateparser string). Empty = Arkime's default recent window, which finds nothing in a capture older than it — pass a range to reach historical data.
expressionNoOptional Arkime expression syntax to scope the values, e.g. "protocols==dns". Empty = all sessions.

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv1.2.1
    • changedInput schema / properties / counts / description
      Previous value: -"Include a per-value occurrence count (default true). Turning it off cuts about a third of the characters (measured on v26.07.1: 91,033 down to 59,931 for one field over a 24-hour window) and is the right choice when you only need the value set itself — to paste into arkime_create_shortcut, for instance."New value: +"Include a per-value occurrence count (default true). Turning it off drops the count from every line and is the right choice when you only need the value set itself — to paste into arkime_create_shortcut, for instance."
  2. Changed3 schema fields changedv1.0.2
    • changedInput schema / properties / counts / description
      Previous value: -"Include a per-value occurrence count (default true)."New value: +"Include a per-value occurrence count (default true). Turning it off cuts about a third of the characters (measured on v26.07.1: 91,033 down to 59,931 for one field over a 24-hour window) and is the right choice when you only need the value set itself — to paste into arkime_create_shortcut, for instance."
    • addedInput schema / properties / time_from
      Added value: +{
+  "default": "",
+  "description": "Start time as EPOCH SECONDS (NOT a dateparser string). Empty = Arkime's default recent window, which finds nothing in a capture older than it — pass a range to reach historical data.",
+  "title": "Time From",
+  "type": "string"
+}
    • addedInput schema / properties / time_to
      Added value: +{
+  "default": "",
+  "description": "End time as EPOCH SECONDS (NOT a dateparser string). Empty = now.",
+  "title": "Time To",
+  "type": "string"
+}
  3. Addedv0.3.2
  4. Removedv0.2.0
  5. First observedv0.1.0

TDQS

A4.8/5.0
Behavior5/5

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

Annotations cover only the safety profile (readOnly/openWorld/non-destructive), and the description adds substantial behavioral context beyond that: the ambiguous "(no values)" result with two indistinguishable causes, the HTTP 200 zero-byte body for an unresolvable field, silent truncation at Arkime's 10,000-value aggregation ceiling with no marker or error, and a contrast with how siblings fail loudly. 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.

Conciseness4/5

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

Front-loads the one-line purpose and the sibling routing before the caveats, so the essential content is at the top. It is long and the truncation point is restated ("no marker and no error" then "Treat a round 10,000 as 'there are more'"), but nearly every sentence carries operational information.

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?

An output schema exists, so return-value documentation is not required, yet the description still clarifies that output is plain text, one value per line, not JSON. Combined with the routing guidance, the empty-result ambiguity, and the truncation caveat, an agent has everything needed to call and interpret this tool.

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

Parameters4/5

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

Schema description coverage is 100%, so the baseline is 3, but the description adds real meaning on top: the field-name resolution caveat tied to arkime_field_search, the instruction to scope with expression when the 10,000 ceiling is hit, and the note that time_from is only worth passing once spelling is verified. It does not restate parameter syntax already in the schema.

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

Purpose5/5

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

States a precise verb+resource+scope ("List distinct values of ONE Arkime field as plain text, optionally with counts") and explicitly names three siblings it is not: arkime_multiunique for combinations, arkime_spigraph for top values plus graph, arkime_spiview for multi-field profiling. An agent can route correctly without opening any schema.

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

Usage Guidelines5/5

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

Gives explicit when-to-use alternatives (tuple of fields -> arkime_multiunique; top values + time series -> arkime_spigraph; profile many fields -> arkime_spiview) plus the condition that selects this tool ("Lighter than a full aggregation when you only need to see what values a field holds"). It also tells the agent when NOT to trust an empty result and to check the field name against arkime_field_search's exp column first.

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

Deploy Server

Other Tools