Skip to main content
Glama
Sign In
nagameTW

mcp-server-malcolm

by nagameTW
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

Size a session set before acting on it

arkime_sessions_summary
Read-only

Summarize Arkime session totals, bytes, and packets for an expression, with per-field breakdowns, to size a result set before running an expensive query.

Instructions

Total sessions, bytes and packets for an expression, plus per-field breakdowns.

    Sizes a result set in one call, before something expensive acts on it.
    It is what arkime_create_hunt's total_sessions wants, in one call and
    in the same dialect — count means a dialect switch, and neither count
    nor arkime_sessions reports bytes or packets. For the matching sessions
    themselves use arkime_sessions, and for a value distribution without
    the totals use arkime_unique or arkime_spiview.

    Returns JSON {"totals", "breakdowns"}: totals carry sessions, bytes,
    dataBytes, packets and the first/last packet timestamps (Arkime's empty
    histogram scaffolding is dropped); each breakdown carries its field name
    and its top values with per-value session/byte/packet counts. An
    expression that matches nothing is a successful answer, not an error:
    the totals read 0 and every field asked for still comes back as a
    breakdown with an empty `data` list. A field Arkime declined
    to break down is listed in ignored_fields rather than passed over in
    silence, since upstream reports it the same way as a field with no
    values.

Input Schema

NameRequiredDescriptionDefault
fieldsNoComma-separated fields to break the totals down by, one breakdown each, e.g. "protocols,ip.dst". Arkime expression names ("ip.src") and dotted ECS names ("source.ip") both work; a db name ("srcIp") is silently ignored upstream and is reported back in ignored_fields. Cannot be empty — Arkime rejects the request without it — so an empty value falls back to protocols.protocols
time_toNoEnd time as EPOCH SECONDS (NOT a dateparser string). Empty = now.
time_fromNoStart time as EPOCH SECONDS (NOT a dateparser string). Empty summarises Arkime's default recent window, which on a historical capture reports zero and looks like a broken tool.
expressionNoArkime expression syntax scoping what is counted, e.g. "protocols == http && ip.dst == 203.0.113.5". Empty counts every session in the window.

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv1.0.2

TDQS

A4.6/5.0
Behavior5/5

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

Annotations already establish readOnlyHint=true and destructiveHint=false, yet the description still adds substantive behavior: an expression matching nothing is a successful zero-total answer (not an error), empty histogram scaffolding is dropped, and Arkime-declined fields surface in ignored_fields rather than being silently omitted. This is meaningful context beyond the safety profile.

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?

The headline and the sizing purpose are front-loaded, and every paragraph carries signal (routing, return shape, empty-result semantics). The middle section is somewhat dense and could be tightened, but nothing is filler.

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?

Despite an output schema existing, the description still sketches the return contract ({totals, breakdowns}, which totals keys, per-value counts), which is the right level for a tool whose empty-result behavior is non-obvious. Combined with full param coverage and clear routing, 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.

Parameters3/5

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

Schema description coverage is 100%, so fields, time_from/time_to (epoch seconds), and expression are already fully documented in the schema. The description adds the dialect point ('same dialect — count means a dialect switch') but otherwise relies on the schema. Baseline 3 when the schema does the heavy lifting.

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

Purpose5/5

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

The first sentence states the specific verb and resource (totals of sessions/bytes/packets for an expression, plus per-field breakdowns) and the second reframes it as sizing a result set. The definition then explicitly distinguishes itself from arkime_sessions, arkime_unique, arkime_spiview, count and arkime_create_hunt, so an agent can place it precisely.

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

Usage Guidelines5/5

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

It states the when ('before something expensive acts on it', feeds arkime_create_hunt's total_sessions) and names the alternatives with the conditions that select them ('for the matching sessions themselves use arkime_sessions', 'for a value distribution without the totals use arkime_unique or arkime_spiview', 'count means a dialect switch'). The routing guidance is explicit rather than inferred.

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