mcp-server-malcolm

by nagameTW

Overview Schema Related Servers Score Discussions

Python

Local

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v1.1.1
Disambiguation3/5
The 51 tools cover many overlapping search and aggregation paths (arkime_sessions vs malcolm_search vs search_dsl, arkime_unique vs malcolm_field_values). Each tool has a documented niche, but the sheer number of similar query tools creates selection ambiguity. Some pairs like malcolm_alerts and malcolm_alerting_alerts are explicitly differentiated, but names alone don't make their distinct roles obvious.
Naming Consistency4/5
Most tools follow a consistent `<prefix>_<noun>` pattern (malcolm_*, arkime_*), and related tools share stems (arkime_session_*, malcolm_field_*, malcolm_alerting_*). However, there is no consistent verb_noun convention: some are verbs (search_dsl, list_indices), some are nouns (arkime_spigraph, malcolm_ping), and mixed styles like malcolm_saved_objects vs malcolm_dashboard_export exist.
Tool Count2/5
51 tools is far beyond the typical well-scoped count; it reflects a very broad read-only API surface. While each tool fills a niche, the number creates cognitive load and suggests insufficient consolidation (e.g., many Arkime field-analysis variants, multiple file/hash retrieval tools).
Completeness3/5
The surface covers read-only querying well: search, aggregation, status, field discovery, file metadata, dashboards, alerts, anomalies, NetBox. But write operations are missing entirely, despite descriptions referencing tools like malcolm_create_alert, arkime_create_view, and arkime_create_hunt that are not present. This creates dead ends when an agent needs to create or modify resources.
Average 4.8/5 across 51 of 51 tools scored.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 63 commits in the last 12 weeks
- Last stable release on August 14, 2026
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
This repository includes a glama.json configuration file.
This server has been verified by its author.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds behavioral context beyond that: returns 'trimmed rows', includes 'matched' count that is 'usually far more than are returned', and highlights that each row's id is needed for drill-down. This enriches the agent's understanding of the return envelope and its relationship to other tools.
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 description is compact and front-loaded with the core purpose, then expands on uniqueness, alternatives, and return envelope. Each sentence adds value, though the multi-paragraph structure could be tightened slightly. It avoids redundancy and is readable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity and the rich output schema (not shown but available), the description covers the essential context: what it returns, why it matters, and how it differs from siblings. It does not repeat return-value details already in the output schema, and it addresses when to use alternatives. Slightly more could be said about default time behavior, but that is in the parameter schema.
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 coverage is 100%: every parameter has a detailed description. The description itself adds minimal parameter-specific meaning beyond the schema, but it does clarify that 'expression' uses Arkime syntax and that the result is scoped to session ids. Baseline 3 is appropriate when the schema carries the full semantic load.
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 description states clearly 'Search Arkime sessions by expression; returns trimmed rows each carrying a session id.' This gives a specific verb and resource, and explicitly distinguishes it as 'the ONLY search returning a session id' compared to siblings like arkime_session_detail and arkime_sessions_csv.
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?
The description gives explicit when-to-use and alternatives: 'For one session's own row use arkime_session_detail; for its PCAP bytes/metadata use arkime_session_pcap. To search with Malcolm filter dicts and dateparser times... use malcolm_search.' It also notes arkime_sessions_csv for larger results in the schema description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description discloses that the returned row is 'narrower than the document behind it' with specific measured examples, and notes that missing ids return 'a sentence rather than an error.' This adds valuable behavioral context beyond 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?
The description is long but well-structured with a front-loaded purpose, followed by limitations, alternatives, and edge-case behavior. Every sentence provides distinct information, though a more concise version could be imagined.
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?
With a single parameter, output schema, and annotations, the description covers the tool's purpose, return shape, limitations, missing-id behavior, and sibling alternatives. It is fully adequate for an agent to select and invoke correctly.
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?
The schema already fully describes session_id as 'One Arkime session id from arkime_sessions results,' so the description adds little to parameter meaning. The mention of id instability across re-indexing is contextual but not needed for parameter semantics, hence baseline 3.
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 description opens with 'Fetch the session Arkime holds under one id — a point lookup, not a search,' which clearly identifies the verb, resource, and scope. It directly contrasts with search siblings, making its purpose unambiguous.
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 explicitly directs users when a field is missing: 'read the document itself with malcolm_search, or with search_dsl...' and lists arkime_session_pcap, arkime_session_payload, arkime_unique/arkime_spiview for other needs. This gives clear when-to-use vs alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark readOnlyHint=true and destructiveHint=false, but the description goes far beyond: 'The bytes never enter the response and nothing is written to disk', returned hashes are computed over served bytes for completeness verification, found:false is a successful answer rather than error, and bodies over 100 MB are refused. These are non-obvious operational behaviors that an agent needs to know.
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 description is front-loaded with the core purpose, then systematically covers alternatives and behavioral caveats in distinct paragraphs. It is a bit verbose with repeated 'measured on Malcolm v26.07.1' (also present in the schema), but every sentence carries meaningful information, so it earns a 4 rather than a 3 or 5.
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?
Given the tool's complexity, the description covers all needed context: session scoping, metadata-only response, found:false semantics, 100 MB limit and url_only workaround, and alternative tools for different scenarios. An output schema exists to document return fields, so the description doesn't need to repeat those details.
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?
The input schema covers 100% of parameters with detailed descriptions (e.g., file_hash explains md5/sha256 formats and the cross-session 'no match' gotcha; session_id explains its role in scoping). The description adds no additional parameter-specific meaning beyond the schema, so the baseline 3 is appropriate.
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 description opens with a specific verb+resource+scope statement: 'Fetch the file one NAMED session carried, by content hash; returns METADATA ONLY.' It clearly differentiates from siblings arkime_file_by_hash (session-scoped vs most-recent-across-sessions) and malcolm_extract_file (Zeek-carved files), making the tool's unique role unmistakable.
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?
Explicit guidance is provided: 'Prefer this whenever you hold a session id' and 'Use malcolm_extract_file instead when Zeek carved the file to disk.' It also explains why this tool beats arkime_file_by_hash with a concrete measured example (served the body for all three sessions vs found:false).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, but the description adds substantial behavioral detail: empty results are successful with zero totals, ignored_fields is returned for fields Arkime declines to break down, and the response format includes specific fields (totals, breakdowns, first/last timestamps). It also warns about the time_from default window on historical captures. This far exceeds the baseline and does not contradict 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?
The description is front-loaded with the core purpose and usage, then details the return format and edge cases. It is longer than typical but each sentence carries meaningful content, including a concrete measurement example to illustrate empty behavior. Slightly verbose but well-structured.
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?
For a moderately complex read-only tool with four parameters and a rich output schema, the description is complete. It covers purpose, usage, return structure, empty-result semantics, ignored fields, and the default window pitfall. The output schema exists, so the detailed return description is a bonus, not a requirement.
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 coverage is 100%, so the baseline is 3. The description does not directly expand on parameter syntax; its only parameter-related additions are behavioral (e.g., ignored_fields behavior, expression matching nothing). These are more about output semantics than parameter meaning, so the description adds little beyond 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?
The description opens with a specific verb: 'Total sessions, bytes and packets for an expression, plus per-field breakdowns.' It clearly distinguishes this tool from siblings by naming alternatives: 'For the matching sessions themselves use arkime_sessions, and for a value distribution without the totals use arkime_unique or arkime_spiview.' This makes the purpose unmistakable.
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?
The description explicitly states when to use this tool ('before something expensive acts on it'), explains why it is preferable to count ('count means a dialect switch, and neither count nor arkime_sessions reports bytes or packets'), and names alternatives with precise conditions. This is exemplary usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds substantial behavioral context: hierarchy levels are nested per-parent not global, each level is capped at top 20 (with a version-specific measurement), and an empty tree with no time range usually indicates data predates the default window. This goes well beyond the annotations and is highly informative.
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 description is longer than average but every sentence provides value: purpose, differentiation, behavior, and troubleshooting. It is well-structured with clear topic shifts, but could be slightly tightened without losing information. A strong 4.
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?
Given the tool's complexity, the presence of an output schema, and rich annotations, the description is fully complete. It covers return type (raw spigraph-hierarchy response), hierarchical semantics, limits, and a common failure mode with a remedy. Nothing important appears 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 the baseline is 3. The description reinforces the 'fields' parameter meaning (hierarchy order) and explains how nesting works, but it does not add new parameter-level syntax or formats beyond what the schema already provides. It meets the baseline without exceeding it.
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 description states a specific action: building a nested top-N hierarchy across Arkime fields, explicitly naming it a treemap/drill-down. It distinguishes itself from malcolm_aggregate's flat buckets, arkime_multiunique's flat tuples, arkime_spigraph for single-field+time, and arkime_connections for source/destination, making its purpose clear and unique.
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?
The description explicitly says when to use this tool (for nested hierarchy/drill-down) and identifies alternatives for flat aggregations, single-field+time, and connections. It also provides a practical tip (pass time_from when empty tree) and clarifies the tool's fixed top-20 behavior, giving concrete usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses plain-text streaming (one value per line, not JSON), the ambiguous '(no values)' response with two indistinguishable causes, silent truncation at Arkime's 10,000-value ceiling, and measured behavior on specific versions (e.g., zero-byte body for invalid field). This adds substantial context beyond the readOnlyHint and destructiveHint 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?
The description is longer than average but each paragraph earns its place: the first sentence states the core purpose, the second gives alternative-tool guidance, and subsequent paragraphs cover critical caveats (empty result ambiguity, truncation). It is front-loaded and structured logically, though the measurement details could be trimmed without losing key warnings.
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?
Given the tool's complexity (5 params, potential edge cases), the description is remarkably complete. It covers return format, ambiguous empty results with troubleshooting advice, silent truncation with scoping suggestions, and notes about historical data windows. Since an output schema exists, it need not explain return values, yet it still covers all operational pitfalls.
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?
The schema already provides 100% parameter coverage with detailed descriptions (e.g., counts default true and its performance impact, time_from explanation, expression example). The description adds minimal parameter-specific meaning beyond reinforcing that only ONE field is accepted and suggesting expression for scoping, so it stays at the baseline.
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 opening sentence clearly states the tool lists distinct values of ONE Arkime field as plain text with optional counts. It distinguishes from sibling tools by naming arkime_multiunique (value combinations), arkime_spigraph (top values with time-series), and arkime_spiview (multi-field profiling), making the purpose unambiguous.
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?
Explicitly directs users to alternative tools for value combinations, top values with time-series, and multi-field profiling, and notes it is lighter than full aggregation for simple value inspection. This directly tells when to use this tool versus alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark this as read-only and non-destructive; the description adds that views are per-user/per-role, so results reflect the configured account rather than the whole server, and that returned objects carry owner and roles fields. This goes beyond annotations and helps set expectations.
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 description is longer than minimal, but each sentence adds value: purpose, usage, alternatives, scope limitation, and output schema pointer. It could be trimmed slightly, but the structure is clear and front-loaded.
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?
With annotations, output schema, and a single well-documented parameter, this description fully equips an agent to select and invoke the tool: it covers what, when, why, scope, and provides pointers to related tools. No gaps remain.
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?
The only parameter, limit, is fully documented in the schema (type, default, min, max, description), so the description does not need to add more. Baseline 3 applies due to high schema coverage; no additional param semantics are provided, but none are necessary.
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 description opens with a specific verb+resource: 'List the saved search views this Arkime holds, with each one's expression.' It further distinguishes from arkime_shortcuts, arkime_field_search, and arkime_create_view, making the purpose unmistakable.
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 explicitly states when to use: 'Use this to find the queries the human team already curated before writing your own' and names specific alternatives for different needs, along with a noted prerequisite for arkime_create_view. This is direct when-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite annotations already indicating safe read-only behavior, the description adds substantial critical context: it takes no time arguments, applies no default window, and a bare call counts all documents held by the index—potentially millions. It also warns about the different query_dsl shape compared to search_dsl, which is not conveyed 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and front-loaded with purpose, but it is slightly verbose in places; for example, 'without returning the documents' and 'not the documents themselves' are redundant. Still, all information is relevant and organized clearly.
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?
Given the tool's moderate complexity, the description fully covers usage, gotchas, alternatives, and safety considerations. An output schema exists, so return format details are not required. It is complete for an agent to select and invoke the tool correctly.
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?
Input schema covers both parameters with full descriptions (index default, query_dsl format and example), so baseline is 3. The description adds minimal parameter-specific guidance beyond pointing to the schema, so no higher score is warranted.
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 description begins with a specific verb and resource: 'Count documents matching a DSL query clause, without returning the documents.' This clearly distinguishes it from sibling search_dsl by emphasizing count-only behavior, making the purpose unambiguous.
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?
Explicitly states when to use this tool: 'Use this instead of search_dsl when you only need the number of matches, not the documents themselves.' It also names alternatives (malcolm_search, arkime_sessions_summary) and clarifies when they are preferable, such as when a human-readable time range or byte/packet totals are needed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, and destructiveHint, but the description adds significant behavioral context beyond that: it warns about the 'note' key indicating a monitor cannot fire, discloses that 'Raises if no monitor has that id', and describes internal details like mustache placeholders. This goes well beyond the annotation safety profile and covers edge cases.
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 description is longer than two sentences but is well-structured and front-loaded: the first sentence gives the core purpose, followed by usage context and detailed behavioral notes. Every paragraph adds value (the loopback monitor example illustrates the query format), but it is somewhat verbose and could be tightened without losing critical 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?
Given the tool's complexity (nested inputs/triggers, the 'note' key, error behavior), the description covers all essential aspects: what is returned, what is intentionally not described in the output schema, how to interpret the note key, and error conditions. The output schema exists, so return value details are not needed, and the description fills all remaining contextual gaps.
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?
The input schema already provides full coverage (100%) with a clear description, example value, and disambiguation ('Not the monitor name'). The tool description only repeats 'Take the id from malcolm_alerting_monitors' without adding new semantic meaning, so it meets the baseline but does not exceed 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?
The description opens with a specific verb and resource: 'Read one alerting monitor in full: the query it runs and the conditions that fire it.' It clearly distinguishes itself from sibling tools by explicitly contrasting with malcolm_alerting_monitors and malcolm_alerting_alerts, making the tool's unique purpose obvious.
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?
The description states exactly when to use this tool ('Use this to decide whether a monitor's SILENCE means anything') and explains why alternatives are insufficient (malcolm_alerting_monitors cannot show query/triggers). It also provides workflow guidance: 'Take the id from malcolm_alerting_monitors' and directs users to malcolm_alerting_alerts for raised alerts, explicitly covering alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
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 that 'This is catalogue metadata only' and that the output JSON is {"total", "showing", "objects"}. It also discloses the unusual quirk that malcolm_dashboard_export 'answers 200 with an embedded 404' for non-dashboard ids, which is valuable behavioral context.
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 description is well-structured with a clear topic sentence, followed by usage guidance, cross-tool references, and a note on return format. At roughly 150 words it is longer than strictly necessary but every sentence provides useful context, and the front-loaded purpose makes it easy to scan.
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?
The tool has an output schema, and the description supplements it by noting the JSON envelope and why panel layout is absent. It covers the tool's purpose, usage context, exclusions, and related tools, making it a self-contained guide for an agent.
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?
The input schema already provides complete, rich descriptions for all three parameters (limit, search, object_type), including wildcard behavior and case-insensitivity, so schema coverage is 100%. The description does not add new parameter semantics beyond what the schema already states; it relies on 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?
The description opens with 'Find the dashboards, visualizations and saved searches this Malcolm ships,' which names the specific resource (pre-built saved objects) and verb (find). It further distinguishes itself from siblings by pointing to malcolm_saved_object_detail for query details, malcolm_dashboard_export for dashboard structure, and malcolm_search for traffic.
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?
Explicitly says 'Use this to discover what pre-built analysis already exists before building a query by hand' and draws clear boundaries: 'This searches the Dashboards catalogue, NOT network traffic: for traffic use malcolm_search, and for the field names behind a visualization use malcolm_field_search.' Also directs to sibling tools for different object types.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses several critical behaviors beyond annotations: that no session data is returned, that the upstream service returns 200 with an error field on parse failures, that query_dsl must be serialized to a string for search_dsl, and that the resolved index reveals empty-window cases. These are non-obvious and highly valuable, going well beyond the basic readOnlyHint and openWorldHint 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?
Although longer than typical, every sentence earns its place. The structure front-loads the core distinction (not a search), then covers usage contexts, handoff details, and edge-case gotchas. The warnings about serialization and error handling are essential for correct invocation. The formatting with a 'Do NOT' warning and explicit 'Returns JSON' section makes it scannable despite the length.
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?
The description is complete for a tool of this complexity. It explains when to use it, what it returns, how to hand off to search_dsl, how the index resolves, and how errors manifest. It also covers the empty-window case and the size override, leaving no major questions for an agent. The output schema exists, but the description adds necessary behavioral context that would not be inferable from schema alone.
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?
The input schema already provides 100% parameter coverage with detailed descriptions, including epoch-second expectations, examples, and empty-expression behavior. The tool description adds no additional parameter-specific semantics, so the baseline score of 3 is appropriate. It does clarify how the compiled query interacts with the time window, but that's more about output behavior than parameter syntax.
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 opening sentence 'Translate an Arkime expression into the OpenSearch DSL it compiles to, without running it' uses a specific verb ('translate') and resource ('Arkime expression to OpenSearch DSL'), and immediately distinguishes it from running a search. It also contrast with sibling tools like search_dsl and arkime_sessions, making the tool's role clear.
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?
The description provides explicit guidance: 'Do NOT use this to run a search' and 'Come here only when the DSL itself is the goal.' It names alternatives ('send it straight to arkime_sessions...'), recommends follow-up tools (search_dsl, count), and even notes when an expression is better sent directly elsewhere. This is exemplary when-versus-alternative guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds behavioral details beyond annotations: disabled queries are included, and an empty deployment returns a plain sentence rather than an empty list. It also explains how cron queries stamp tags, providing context. This goes beyond the annotation baseline, though it could mention the openWorldHint implication.
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?
The description is front-loaded with a clear one-sentence purpose, then structured into usage guidance and edge-case behavior. Every sentence contributes value, and the length is justified by the need to differentiate from many sibling tools.
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?
With no parameters, an output schema, and clear annotations, the description fully covers purpose, usage, alternatives, edge cases (disabled queries, empty deployment), and points to the output schema for fields. It is complete for an agent to select and invoke the tool correctly.
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?
The tool has zero parameters, so the description needs no parameter explanation. The empty input schema is fully covered, and the baseline for 0 params is 4. The description correctly uses the space for usage and behavior instead.
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 description clearly states 'List Arkime's cron queries — saved expressions that re-run on a schedule' with a specific verb and resource. It explicitly distinguishes from sibling tools by noting this is the only tool that answers 'where a tag came from' and contrasts with arkime_views, arkime_shortcuts, and malcolm_field_values.
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?
The description provides explicit when-to-use guidance: 'Use this for two questions' and names alternatives: 'For saved searches nobody schedules use arkime_views, for named value lists (IOC sets) use arkime_shortcuts, and to see the tags actually present in the data use malcolm_field_values.' It also explains 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.
Behavior5/5
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 interpretation beyond that: packets_dropped is a cumulative counter not a rate, dropped_per_sec is the interval rate, and the warning key marks active loss. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized and front-loaded: the first sentence gives the core purpose, the second provides usage guidance, and the third clarifies field semantics. Every sentence earns its place without redundancy.
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?
For a simple health-check tool with one parameter and an output schema, the description covers purpose, usage, field interpretation, and points to the schema for per-node details. It fully addresses the decision context and sibling differentiation.
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?
The only parameter 'node' is already fully described in the input schema (substring matching, default empty meaning every node). With 100% schema description coverage, the description adds no additional parameter semantics, so baseline 3 is appropriate.
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 description states a specific verb+resource: 'Report each Arkime capture node's health: drops, disk, memory, queues.' It clearly distinguishes from siblings by explicitly noting the capture-side scope and naming alternatives like malcolm_service_status and cluster_health.
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?
Explicitly provides when to use: 'Use this to decide whether the data can be trusted before concluding anything from an absence,' and gives clear alternatives: 'For whether the Malcolm services are up at all use malcolm_service_status, and for OpenSearch cluster state use cluster_health.' This fully covers usage guidance and exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true and destructiveHint=false; the description adds context about intervals with no captured packets and warns that different nodes overlap in time, which is valuable for interpretation.
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?
The description is structured into three focused paragraphs: purpose, usage, and behavior, with no redundant sentences. It's appropriately sized for the tool's complexity.
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?
For a simple read-only list tool with one parameter, the description covers purpose, differentiation, and a key analytical insight. The presence of an output schema means return values don't need to be explained.
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 coverage is 100% with a single optional `limit` parameter described as 'Max files to return.' The description doesn't add parameter-specific semantics but points to the output schema for per-file field units, so baseline 3 applies.
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 description clearly states 'List the PCAP files Arkime has indexed, with each file's coverage,' specifying the verb, resource, and scope. It also differentiates from siblings by calling it the 'file-level view' versus malcolm_data_coverage and arkime_sessions.
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?
Explicitly says 'Use this to answer...' and provides alternatives: 'for the dataset-level view... use malcolm_data_coverage, and to search the sessions themselves use arkime_sessions.' Also gives nuanced guidance about gap detection and node comparisons.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint, openWorldHint), the description adds critical behavioral context: it is a live outbound PTR query, not a read of captured data, and may signal interest to adversarial controllers. It also cites a concrete example with a version number, enhancing transparency without contradicting 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?
Every sentence in the description serves a purpose: it states the operation, provides usage context, warns about outbound behavior, gives a measured example, and points to the output schema for details. Despite being longer than average, it is well-structured, front-loaded, and free of redundant 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?
Given the tool's one parameter, clear annotations, and presence of an output schema, the description is fully complete. It explains the live nature, the meaning of results (via output schema pointer), and contextualizes when this tool is appropriate, leaving no significant gaps for the agent.
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 coverage is 100% with a detailed description in the schema itself ('One IPv4 or IPv6 address... Not a hostname, not a CIDR range'). The main description reinforces 'one IP address' but does not add substantive new meaning beyond the schema, so a baseline score of 3 is appropriate.
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 description clearly states the specific action: 'Resolve one IP address to its PTR hostname, using Arkime's resolver.' It distinguishes itself from siblings by explicitly contrasting with malcolm_netbox_lookup and malcolm_search, making the tool's unique scope evident.
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?
The description provides explicit guidance on when to use this tool versus alternatives: use for external addresses, avoid for internal assets (favor malcolm_netbox_lookup), and use malcolm_search for names observed in capture. This directly addresses when/when-not and names alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds valuable behavioral context: scoping by the requesting user's roles, API-level filtering of visibility, and the expectation that a fresh deployment returns an empty list. This goes beyond the annotations to explain real-world behavior and a known pitfall.
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?
The description is a bit long but every sentence provides useful context. It is front-loaded with a clear one-line summary, followed by usage guidance, scoping behavior, and an explicit note about output schema fields. No filler is present.
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?
Given the tool's simplicity (1 optional parameter, no nested objects) and the presence of an output schema, the description is complete. It covers what the tool returns, user-scoping caveats, sibling tool distinctions, and a deployment-specific expectation. Nothing critical 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?
The schema covers the single 'limit' parameter 100%, so the description doesn't need to explain it. The description does not add parameter-specific meaning for the input; it focuses on output schema fields like 'use_in_expression' (which is output, not input). Thus, the baseline of 3 applies.
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 description clearly states the tool 'List Arkime's named value lists (IOC sets) and what each one contains.' It uses a specific verb (list) and resource (value lists), immediately distinguishing it from sibling tools by mentioning arkime_views, arkime_crons, and arkime_create_shortcut.
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?
The description gives explicit when-to-use guidance: 'Use this before writing an expression so you reference a list that exists and know what is in it.' It also names alternatives (arkime_views for saved queries, arkime_crons for scheduled queries, arkime_create_shortcut for adding lists) and notes the permission requirement for creating lists.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare readOnlyHint=true and destructiveHint=false, which the description does not contradict. The description adds significant behavioral context beyond annotations: it explains the raw response format, the meaning of sum_other_doc_count, the fact that a field key always appears with an empty bucket list on no aggregate, and how recordsFiltered distinguishes field-name errors from time-range problems. These are non-obvious traits that materially affect how an agent interprets results.
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?
The description is well-structured and front-loaded: the first paragraph states purpose and alternatives, the second covers response traits, and the third gives a concrete measured example to disambiguate error cases. Every sentence earns its place, and the multi-paragraph format improves readability for complex behavioral details. It is appropriately sized for the tool's complexity.
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?
Given the tool's complexity (multi-field aggregation with subtle edge cases) and the presence of an output schema, the description covers all critical context: what the response contains, how to interpret empty results, and how to distinguish failure modes. The examples with measured values add empirical grounding. Nothing significant is left unexplained for an agent to invoke and evaluate the result correctly.
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?
The input schema already documents all four parameters with 100% coverage and rich descriptions, including the spi storage-path syntax, examples, and epoch-second format for time bounds. The tool description does not add material parameter-level information beyond what the schema provides, so the baseline of 3 applies. It does reinforce the behavior of the count suffix but that is 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?
The description clearly states the tool's function: 'Profile top values across SEVERAL Arkime fields at once, each with counts.' It specifies the resource (Arkime fields) and the action (profile top values), and distinguishes it from siblings by explicitly naming alternative tools for different use cases. The verb+resource construction is precise and immediately understandable.
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?
The description provides explicit when-to-use and when-not-to-use guidance: 'For a single field use arkime_unique (plain text) or arkime_spigraph (adds a time graph); for distinct field-tuple combinations use arkime_multiunique; for a nested drill-down hierarchy use arkime_spigraphhierarchy.' It also explains the performance benefit ('lighter than running one aggregation per field'), giving the AI agent clear decision criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds critical behavior: returns raw /mapi/agg response, reports correct field name when an aggregated field isn't indexed, and defaults to LAST 24 HOURS. This goes well beyond the annotation 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tightly written paragraphs: purpose, usage, and behavioral caveats. Every sentence provides actionable information; no filler or repetition.
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?
For a tool with 6 parameters, output schema, and sibling complexity, the description covers purpose, selection criteria, edge cases (empty buckets, time window), and return format. An agent can correctly invoke it without additional context.
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?
All six parameters have schema descriptions covering 100% of the schema. The description adds the time_from default context, but this is also in the schema. Baseline 3 is appropriate since 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 description opens with 'Aggregate network traffic into top-N value buckets for one or more fields', which is a specific verb+resource+scope. It clearly differentiates from sibling tools by stating when to use malcolm_search and malcolm_field_values instead.
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?
Explicit guidance: 'Use this to count distinct values (top talkers, protocol distribution) rather than fetch documents — for the documents themselves use malcolm_search. For distinct values of a single field with less setup, malcolm_field_values is simpler.' Also warns about the 24-hour default window and how to avoid empty results.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description discloses important nuances: 'a disabled monitor is silent in exactly the way a healthy one is,' the active_alerts count only includes ACTIVE state rather than COMPLETED history, and the response behavior when all monitors are disabled. This adds significant behavioral context.
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?
The description is organized into two paragraphs, front-loaded with a clear purpose. Each subsequent sentence serves to differentiate from siblings, explain usage, or disclose behavior. There is no fluff or redundancy, and the length is justified by the need to navigate the many related tools.
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?
The description covers the tool's scope (what it returns, what it does not), identifies related tools for complementary needs, and clarifies edge cases like active_alerts state filtering and pagination. It references the output schema and offers enough context for an agent to decide when to invoke it. Nothing critical 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 coverage is 100% with a single parameter 'limit' that is self-descriptive ('Max monitors to return'). The description adds only peripheral mention of 'the page returned,' which implies pagination but does not directly elaborate on the parameter's behavior. Baseline 3 is appropriate.
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 clearly states the action and object: 'List OpenSearch alerting monitors, what each watches, and whether any have fired.' It explicitly distinguishes itself from siblings by noting what it stops at and pointing to malcolm_alerting_monitor_detail and malcolm_alerting_alerts for deeper details.
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?
Provides explicit usage context: 'Use this to find the standing detections someone already configured, and to check they are actually running.' It also gives clear alternatives for related purposes: monitor_detail, alerting_alerts, malcolm_alerts, and malcolm_create_alert, each with a rationale.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint and destructiveHint annotations, the description adds critical context: it reads detector configuration rather than traffic, counts anomalies across detectors (not detector runs), and warns that zero recorded_anomalies can mean a detector never started. This proactively addresses interpretation pitfalls.
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?
The description is multi-sentence but every sentence adds distinct value: purpose, usage context, sibling differentiation, output shape, and an important zero-value caveat. It is well-structured and front-loaded, with no 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?
Given the output schema exists and the tool has a single well-documented parameter, the description covers all necessary context: what is returned, what is intentionally excluded, how it relates to sibling tools, and how to interpret edge-case results. Nothing critical 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?
The input schema fully describes the single 'limit' parameter with a clear description ('Max detectors to return.'), so schema coverage is 100%. The description adds no additional parameter semantics, but the baseline of 3 applies because the schema already handles this.
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 description clearly states what the tool does: lists OpenSearch anomaly detectors, what each models, and whether anomalies exist. It distinguishes itself from siblings by explicitly naming malcolm_anomaly_results for per-detector results, malcolm_search for underlying documents, and malcolm_alerts for signature-based alerts.
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?
Explicit guidance is provided: use this to see machine-learning baselines and their anomaly outputs; when to use alternatives is clearly stated (e.g., take an id to malcolm_anomaly_results for entity-level scoring, use malcolm_search for traffic, use malcolm_alerts for Suricata alerts). This offers strong when/when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
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 critical behavioral depth: it discloses that non-dashboard ids return an embedded 404 in a normal response body rather than rejecting the request, so the agent must inspect the body. It also reveals size variability with concrete numbers (5 KB–130 KB, 20 KB median) and advises budgeting for the tail. This goes well beyond the annotations and 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but every sentence earns its place: it covers the core action, the prerequisite tool, the type restriction, the error-handling nuance, the alternatives, the return value, and performance guidance. It's front-loaded with the main purpose and avoids filler, making it efficient despite its length.
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?
This tool has subtle behavior (embedded 404, large variable-sized exports) and the description addresses all of it: how to obtain valid ids, what happens with invalid types, what the output contains, and realistic size ranges. Even with an output schema present, the description provides essential context about panel layout and size characteristics, making it contextually complete.
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?
The schema description for dashboard_id is thorough (100% coverage): it defines the type, explains the source (malcolm_saved_objects row with type 'dashboard'), and explicitly warns about embedded 404 behavior for other types. The tool description reinforces this same information but adds little beyond what the schema already provides, so the baseline 3 applies.
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 description opens with 'Export one OpenSearch Dashboards dashboard as its full saved-object JSON,' which clearly identifies the verb (export), resource (dashboard), and output format. It also distinguishes itself from siblings by explicitly stating it returns panel layout that no other tool returns, and contrasts with malcolm_saved_object_detail and malcolm_search.
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?
The description gives explicit when-to-use guidance: 'Use this after malcolm_saved_objects — the only tool here that lists the ids this takes.' It also provides when-not-to-use direction by recommending malcolm_saved_object_detail for visualization/saved-search/index-pattern ids and malcolm_search for network traffic, covering both prerequisites and alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, but the description adds substantial behavioral context beyond that: dual record types (Zeek transfer vs Strelka scan verdict), meaning of scan_hits, the extracted field as an argument for malcolm_extract_file, note rows, and the no-match sentence behavior. This is exactly the kind of contextual disclosure that helps an agent anticipate tool output.
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?
Though longer than two sentences, each sentence earns its place: purpose, alternatives, dual-record caveat, scan_hits semantics, extracted/note distinction, and no-match behavior. It is front-loaded with the core purpose and then expands logically. No filler or redundant content.
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?
Given the tool has 7 parameters, no required params, a rich output schema, and many sibling tools, the description covers the essential nuances: what record types are included, how scan_hits behaves, how to use extracts, what no-match returns, and how this tool relates to alternatives. It is complete enough for an agent to select and invoke it correctly.
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 the baseline is 3. The description does not add parameter-level detail beyond what the schema already provides (e.g., file_hash semantics, executables_only shortcut). It does mention that field names are in the output schema, but this is not parameter-specific. The schema itself carries the parameter documentation burden, so a 3 is appropriate.
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 description starts with a specific verb+resource+scope: 'List the files Zeek saw cross the wire, with their hashes and scan verdicts.' It clearly states what the tool does and distinguishes it from siblings by explicitly naming alternatives (malcolm_search, search_dsl, arkime_file_by_hash) and their different purposes.
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 gives explicit when-to-use guidance ('Use this for any file-centric question') and explicitly names alternatives for other record types, substring/wildcard matching, and hash-based byte retrieval. It also explains the dual-row behavior and when one might see two rows per file, which is crucial for usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly/destructive annotations, the description discloses key behavioral traits: the 'most recent session' selection caveat, that raw bytes are never placed in the MCP response, the 100 MB refusal, and that a 'no match' is not proof of absence. It also includes version-specific measurement context, adding significant transparency.
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 description is front-loaded with the core purpose and then lists caveats, but it is somewhat verbose with multiple clauses and version-specific asides. Every sentence adds information, though a tighter structure would improve readability without losing value.
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?
Given the output schema exists and the tool has moderate complexity, the description adequately covers all needed aspects: return type (metadata only), important limitations (most-recent, no-match caveat), file size limit, and alternatives. 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.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description supplements parameter meaning by specifying hash formats (md5/sha256), source fields (http.md5/http.sha256), and how they relate to malcolm_search vs arkime_session_detail. It also clarifies url_only's role in the large-file case, going beyond the schema's basic descriptions.
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 description clearly states the action ('Extract the transferred file matching a content hash across sessions') and the output scope ('returns METADATA ONLY'). It also distinguishes itself from the sibling 'arkime_session_file_by_hash' by noting the session-scoped alternative, making the purpose unambiguous.
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?
The description provides explicit usage guidance: 'Use this to find out whether a known-bad hash appeared at all' and directly names the alternative tool for pinning to a session. It also advises using url_only for >100 MB files and points to arkime_session_pcap for entire packets, offering clear when-to-use and when-not-to-use context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint=true, openWorldHint=true, destructiveHint=false), the description discloses that it only reads /arkime/api/hunts, that it lists both UI-queued and API-queued hunts, that active_only=true never shows finished jobs (so a disappearing hunt is not an error), and that a never-used deployment returns an empty data list as a valid answer. It also mentions the raw response format, adding substantial behavioral context.
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 description is longer than typical but every sentence adds value: the opening one-liner summarizes purpose, then detailed usage, availability, edge cases, and return format follow logically. It is front-loaded with the core statement and organized into readable segments, though it could be tightened slightly without losing 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?
For a simple two-parameter read-only list tool with an output schema, the description covers all necessary context: what it returns, how to poll, how to cancel via the ID, availability regardless of write classes, the two-list active/history behavior, and the empty-data edge case. Nothing needed for correct invocation is missing.
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?
The schema already provides full descriptions for both parameters (100% coverage), but the description adds meaningful context: it explains the semantic split between active and finished hunts for active_only, and warns that pairing a large limit with active_only=false should be deliberate for full history. This enhances the bare schema definitions, moving beyond the baseline.
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 opening sentence states 'List Arkime hunt jobs with their progress, match counts and status.', clearly identifying the verb, resource, and included fields. It also distinguishes this from creating/cancelling hunts and from other list tools by focusing specifically on hunt jobs, so there is no ambiguity against siblings.
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?
The description explicitly says 'Use this to see what packet-payload searches this Arkime is running or has run' and provides concrete scenarios: polling for job completion, reading an `id` before passing to arkime_cancel_hunt, and noting that active_only=true vs false shows separate lists. It also contrasts with create/cancel tools, making when-to-use guidance unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the plain TEXT return format (not JSON), the meaning of '(no values)' with no time range (data predates the default recent window, suggesting time_from), and specific measured performance characteristics (22,548 lines for a 2-field tuple, 50,817 for a 3-field tuple, ~2 MB). These go beyond the readOnlyHint/destructiveHint annotations and provide actionable behavioral context.
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 description is front-loaded with a clear one-sentence summary and then organized into focused paragraphs. While slightly verbose with performance data and troubleshooting, every sentence serves a purpose and there is no filler. The structure aids readability, though a bit more conciseness would make it perfect.
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?
Given the tool's complexity (tuple combinations, plain-text output, scalability concerns), the description covers all essential aspects: purpose, alternatives, return format, an edge-case interpretation, and scoping advice. The presence of an output schema is indicated, and the description clarifies the text return format that the schema may not fully convey. It is complete for practical use.
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?
The input schema already covers all 5 parameters with detailed descriptions (100% coverage), so the baseline is 3. The description adds value by giving an example tuple (source.ip,destination.port), explaining the time_from workaround for missing data, and warning that adding fields multiplies rows. This supplements the schema meaningfully, justifying a 4.
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 description states it 'List distinct value COMBINATIONS across a tuple of Arkime fields as plain text', which is a specific verb+resource+scope. It explicitly distinguishes from arkime_unique (single field), arkime_connections (source/destination graph), and arkime_spigraphhierarchy (nested hierarchy), making the purpose unambiguous.
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?
Provides explicit usage guidance: 'For a single field use arkime_unique; for a source/destination graph use arkime_connections; for a nested hierarchy use arkime_spigraphhierarchy'. It also gives example use cases (spotting a host scanning many ports) and advises scoping with expression or sizing with arkime_sessions_summary, which clarifies when and how to use the tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses important behavioral traits beyond the readOnly/openWorld annotations: it reports detector run state alongside anomalies, returns an empty result as a sentence explaining what the detector's state implies, rejects seconds-shaped values rather than forwarding them, and passes through entity bucket keys unrenamed because they vary per detector. It also specifies real-time only and the 500 error for historical queries.
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 description is longer than average but well-structured and front-loaded with the core purpose. Each paragraph earns its place: sibling differentiation, time-unit warning, return format, and real-time limitation. It is dense but not padded, though some details repeat the schema.
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?
Given the tool's moderate complexity (5 params), annotations, output schema, and sibling tools, the description covers everything needed: what it returns, how empty results behave, detector state implications, time-unit pitfalls, and how to distinguish it from alternatives. The output schema handles the exact shape, so the description doesn't need to repeat it.
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?
The schema already covers all parameters with descriptions, so the baseline is 3, but the description adds meaningful usage context: the epoch-milliseconds warning, the instruction to multiply arkime_* timestamps by 1000, and the explanation that seconds values become a 1970 window indistinguishable from clean traffic. This goes beyond the schema's parameter descriptions.
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 description opens with a specific verb and resource: "Read which entities one anomaly detector scored as anomalous in a window, worst first." It clearly distinguishes itself from malcolm_anomaly_detectors (single count per detector), malcolm_alerts, and malcolm_alerting_alerts by framing itself as the machine-learning baseline.
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?
Explicit usage guidance is provided: use it after malcolm_anomaly_detectors to resolve ambiguity between 'ran and found nothing' versus 'never started.' It names alternatives for signature-based detection (malcolm_alerts, malcolm_alerting_alerts) and states that real-time results only are supported, with historical requests resulting in a 500.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, but the description adds substantial behavior: the output format as 'value (N docs)' lines, the '-' placeholder for absent fields, and the default last-24-hours window with a concrete Malcolm v26.07.1 example. This goes well beyond the structured annotations and is consistent with them.
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 description is front-loaded with purpose and usage in the first two sentences, then organized into clear caveats. The measured example about network.protocol is informative but makes the description slightly longer than strictly necessary. Overall, every sentence earns its place and the structure is logical.
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?
For a read-only enumeration tool with moderate complexity, the description covers purpose, when to use alternatives, output format, edge-case placeholder behavior, default time window, and a practical warning. Combined with the 100% schema coverage and presence of an output schema, the agent has a complete and unambiguous picture.
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?
The input schema already covers all 5 parameters at 100%, so the baseline is 3. The description adds value by explaining the '-' placeholder meaning, the default time-window consequence, and the need to pass time_from, which supplements the schema's brief parameter descriptions. It does not need to restate limit/filters since those are well documented 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?
The description opens with 'List a single field's distinct VALUES with per-value document counts', which names a specific verb, resource, and unique output. It further distinguishes itself from siblings by explicitly naming malcolm_field_search, malcolm_field_profile, and malcolm_aggregate for different use cases.
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 explicitly states when to use the tool: 'Use this to see what values a field actually holds before filtering on it, so you don't invent values.' It names exact alternatives for other needs and provides a clear directive about the time window: 'Pass time_from before concluding a value is not in this Malcolm.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare readOnlyHint, openWorldHint, and destructiveHint. The description adds substantial behavioral context beyond that: the graph is built from a bounded slice of sessions, not all, and the bound is not a parameter. It gives a concrete measured example (6M sessions produced 10 nodes/8 links) and warns that nothing in the response marks the shortfall. It also documents that expression names are rejected with HTTP 403/500. This goes far 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is longer than average, but every paragraph earns its place: purpose, field-naming rule, alternatives, return type, and a safety caveat about bounded slices. It is front-loaded with the main action and then details. Slightly dense, but not wasteful; a 4 is appropriate given the complexity it must convey.
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?
For a read-only graph tool with an output schema, the description covers all essential context: what the tool returns, how to select fields correctly, what to avoid, and a significant hidden limitation (bounded slice) with a measured example. It also names sibling tools for alternative result shapes. This is exceptionally complete given the tool's complexity and schema/annotation richness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds critical meaning: it explains the src/dst fields take Arkime *db* names or dotted storage paths, and explicitly rejects expression names like ip.src/port.dst. It provides measured equivalences (srcIp/dstIp vs source.ip/destination.ip) and explains the effect of choosing dstPort. This is valuable semantic guidance beyond the schema's field descriptions.
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 description states a specific verb+resource: 'Build a source/destination connection graph of who talked to whom. Returns nodes and links between two fields.' It also distinguishes from siblings by naming arkime_multiunique and arkime_spigraphhierarchy as alternatives for different output shapes. This is clearly differentiated and purposeful.
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?
Explicit use cases are given: 'useful for tracing lateral movement or mapping which hosts a suspect IP communicated with.' It directly names when-not-to-use: 'For distinct field-tuple pairs as text rather than a graph use arkime_multiunique; for a nested top-N hierarchy use arkime_spigraphhierarchy.' The description also warns about the bounded slice caveat, guiding the user to narrow with expression and time window.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description discloses that the tool returns raw CSV text (not JSON), that `limit` bounds rows exactly, and that an invalid `fields` name can cause a hang rather than an error, with timeout indicating a fields problem. These are non-obvious behaviors that materially affect invocation and result interpretation.
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?
The description is compact yet information-dense: starts with purpose, then usage guidance with alternatives, then return type and behavioral quirks. Every sentence contributes a distinct piece of information, and no filler is present.
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?
Given the tool's simple CSV-export purpose and the rich annotations and output schema, the description covers all essential aspects: output format, cost/token advantage, exact row limit, and failure mode. No critical information is missing for an agent to select and invoke it correctly.
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?
Input schema covers 100% of parameter descriptions, including detailed notes on field naming conventions and time formats. The tool description adds useful context about `limit` exactness and the timeout behavior linked to `fields`, which complements the schema without redundancy.
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 description opens with a specific verb+resource+format: 'Export many sessions as a compact CSV table, one row each.' It clearly distinguishes the tool from close siblings by stating that arkime_sessions is used when a session id is needed and arkime_connections for a who-talked-to-whom summary.
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?
Explicitly states when to use this tool ('when you want a lot of sessions cheaply') and provides direct alternatives with rationale: arkime_sessions for drilling into a session id (none returned by CSV) and arkime_connections for a summary. This is model guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint=true, destructiveHint=false), it discloses detailed behavioral quirks: bucket width is Arkime's choice with measured values per range, empty items list returns HTTP 200, and recordsFiltered distinguishes field-name errors from time-range problems. This gives the agent crucial diagnostic knowledge for interpreting responses.
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 description is long but well-structured. The first paragraph front-loads the core purpose and alternatives, while later paragraphs provide essential behavioral and failure-mode details. Each sentence carries useful information, but the length (especially the measured example details) could be trimmed slightly without losing value.
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?
Given the output schema exists (so return values are externally documented), the description covers all critical usage context: purpose, alternatives, parameter quirks, time-range behavior, field-name resolution pitfalls, and diagnostic interpretation of empty results. It is exceptionally complete for a complex tool with subtle failure modes.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already has 100% coverage, but the tool description adds significant extra meaning: explains that `field` uses storage path, not exp column, with concrete measured examples of success and failure; clarifies `time_from` empty means Arkime's recent-only default; and notes `size` bounds distinct values, not time buckets. This goes beyond the schema's own descriptions.
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 opening sentence states exactly what it does: 'Return top values of ONE Arkime field plus a per-value time-series graph.' It uses a specific verb ('return') and resource ('Arkime field'), and immediately distinguishes itself from siblings by naming arkime_unique, arkime_spigraphhierarchy, and arkime_spiview as alternatives.
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?
The description explicitly says when to use it ('Use for top talkers or spotting a value that spikes over time') and gives clear alternative tools for different use cases: 'For distinct values of one field without the graph use arkime_unique; for a nested multi-level hierarchy use arkime_spigraphhierarchy; for many fields profiled at once use arkime_spiview.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds meaningful behavioral context beyond annotations: it discloses the return value ('Returns the raw OpenSearch _cluster/health document'), a limitation ('every shard allocated says nothing about whether packets are still being captured or parsed'), and even provides expected steady-state values from a specific version ('Measured on Malcolm v26.07.1... steady state is green with number_of_nodes=1 and unassigned_shards=0, so treat yellow as something to explain rather than as normal'). This goes well beyond the readOnlyHint/openWorldHint 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?
The description is three paragraphs but every sentence contributes: the first gives the core purpose, the second gives alternatives and return format, the third gives limitations and expected values. There is no jargon, no repetition, and it is logically structured from purpose to guidance to caveats.
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?
For a zero-parameter health check, the description is exceptionally complete: it states the exact purpose, scope, return value, limitations, expected cluster state, and directly links to five related tools for adjacent queries. The output schema is mentioned, and the description covers all likely user needs without requiring additional lookups.
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?
The tool has zero parameters, so the schema is trivially complete. The baseline for 0 params is 4; the description doesn't need to add parameter semantics. It implicitly confirms no arguments are needed by describing the tool's scope. No deduction needed.
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 description opens with a specific verb and resource: 'Report OpenSearch cluster health: green/yellow/red status plus node and shard counts.' It clearly states the scope (cluster-wide storage backend) and differentiates from siblings by naming malcolm_ping, malcolm_service_status, and list_indices for other use cases.
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?
Explicit when-to-use guidance is provided: 'This checks the storage backend (OpenSearch) itself, cluster-wide.' It names alternatives with specific contexts (malcolm_ping for API reachability, malcolm_service_status for service readiness, list_indices for per-index status, malcolm_data_coverage for data arrival, arkime_node_stats for packet drops). This fully addresses when to use vs alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true and destructiveHint=false, but the description adds substantial behavioral detail: it returns the raw OpenSearch _mapping response, non-existent index yields an error in the body, wildcard returns multiple blocks each repeating the schema with cost implications, and it explains the distinction between OpenSearch types and Malcolm's names. This goes far beyond the annotation 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and front-loaded with the core purpose, followed by practical usage guidance and caveats. Every sentence carries information: alternatives, return format, error behavior, wildcard cost, and type naming distinction. No filler or redundancy.
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?
The description is fully complete for the tool's complexity. It covers the return type (raw _mapping), edge cases (non-existent index, wildcard), performance considerations (megabyte-scale response), relationships to sibling tools, and the type system mismatch. Given annotations, schema, and output schema, no critical aspect is missing.
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?
The input schema already covers the index parameter well (name, pattern, wildcard support). The description adds semantic value by explaining the consequences of using a wildcard (one mapping block per index, repeated schema, large payload) and advising to name one index unless absolutely necessary. This enriches understanding beyond the schema's basic field description.
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 description opens with a specific verb+resource+scope: 'Return one index's field mapping: every field name and its OpenSearch type.' This clearly states what the tool does and immediately distinguishes it from siblings by naming alternatives (list_indices, malcolm_field_search).
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?
Explicit guidance is given: 'Use this to learn what fields an index holds and how they are typed before writing a DSL query against it.' It also provides clear when-not-to-use instructions, naming list_indices for discovering indices and malcolm_field_search for Malcolm's field names, plus a warning against wildcard usage unless needed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes far beyond the readOnly/destructive annotations, revealing that the tool reads OpenSearch's index list directly, returns internal Malcolm indices, that traffic lives only in arkime_sessions3-* indices, that new indices are empty, and that patterns matching nothing return an empty array. It even clarifies the meaning of 'health' and points to malcolm_data_coverage for capture freshness. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is longer than average but every sentence earns its place, covering purpose, usage, alternatives, return format, data source caveats, and edge-case behavior. It is well-structured, front-loaded with the core function, and uses paragraphs to separate distinct concepts without fluff.
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?
For a tool with one optional parameter and an output schema, the description is exceptionally complete. It explains the return format, how to interpret results (e.g., using docs.count over names), what not to expect (health vs. capture freshness), and directs to related tools for complementary data, fully equipping an agent to use it correctly.
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?
The schema already describes the pattern parameter well (100% coverage), so the baseline is 3. However, the description adds valuable behavioral semantics about the parameter: 'A pattern matching nothing returns an empty array, not an error' and explains that a specific pattern skips internal indices, enriching the schema's meaning.
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 description opens with a specific verb+resource: 'List indices with their health, status, and document count.' It clearly distinguishes itself from siblings by explicitly naming index_mapping for field schemas and cluster_health for cluster-wide health, making the tool's unique scope unambiguous.
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?
Explicit usage guidance is provided: 'Use this to discover which indices exist before querying one.' It also states when not to use it, directing to index_mapping and cluster_health for different needs, fulfilling the when/when-not/alternatives criterion perfectly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite annotations already indicating readOnly/openWorld/non-destructive, the description adds critical behavioral details: unknown alertState/severity return 200 with an empty list rather than 400 (measured on v26.07.1), and an empty list is a successful, common answer. This prevention of false-negative interpretation goes well 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is longer than average, but each sentence earns its place: purpose, sibling differentiation, validation caveat, return format, and empty-list explanation are all essential. It is front-loaded with the core purpose and structured in readable paragraphs, though it could be tightened by removing the explicit 'Returns JSON' sentence since an output schema exists.
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?
Given the tool has 4 optional parameters, 100% schema coverage, an output schema, and annotations, the description adds all necessary context: return format, empty-list semantics, validation quirk, and clear sibling differentiators. The agent has everything needed to select and invoke this tool correctly, including edge cases that could cause false empty results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Though schema description coverage is 100%, the description enriches the parameters: severity means the human-set level on the trigger (not a computed score), monitor_id must use the `id` returned by malcolm_alerting_monitors (not the name), and alert_state is explained with lifecycle meanings (e.g., DELETED means alert outlived monitor). This added context prevents misuse.
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 description opens with a specific verb+resource: 'Read what OpenSearch alerting monitors have actually fired, in any state.' It clearly distinguishes this tool from siblings by contrasting with malcolm_alerting_monitors (standing rules, ACTIVE only) and malcolm_alerts (Suricata IDS), so the agent knows exactly which tool matches which intent.
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?
The description gives explicit usage context: 'Use this for "what fired overnight"' and then spells out what each sibling tool does instead. It also mentions when a monitor never fires (empty results when monitors disabled), and directs to malcolm_alerting_monitor_detail for rule details, covering both when-to-use and when-not-to-use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the read-only annotation, the description discloses key behavioral traits: error handling per sub-section with fallback to raising only if all fail, and the critical time-range scoping nuance (applies only to counts, not liveness or index count). This adds valuable context not captured by annotations alone.
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?
The description is well-structured with a clear summary sentence, usage guidance, and a behavioral note. Every sentence contributes essential information, with no redundancy or filler. It is appropriately detailed for the tool's complexity.
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?
The description covers all essential aspects: purpose, usage timing, alternatives, error behavior, and the precise semantics of the time range. Since an output schema exists, it does not need to explain return values, making this complete for an agent to select and invoke correctly.
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?
With 100% schema coverage, the parameters are already well documented. The description adds meaningful nuance by clarifying that the time range only affects per-dataset counts and that sensor liveness and index count ignore it, which is not obvious from the schema descriptions alone.
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 description opens with a clear verb and resource: 'Summarize what data exists: feeding sensors, freshness, and per-dataset volume.' It also explicitly differentiates from sibling tools by naming malcolm_service_status and malcolm_field_values as alternatives for different use cases.
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 exactly when to use the tool ('before a hunt') and what it reveals. It also gives direct exclusions: 'For overall service/stack health... use malcolm_service_status' and 'For distinct values... use malcolm_field_values,' making the selection unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Even with readOnlyHint and destructiveHint annotations already present, the description adds crucial behavioral details: bytes never enter the response, nothing is written to disk, the 100 MB streaming cap, refusal of larger files before read, url_only behavior, sha256 computation over served bytes, and the 404 → found:false mapping. This goes well beyond the annotations and helps an agent anticipate edge cases.
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?
The description is multi-paragraph but every sentence earns its place. It is front-loaded with the core purpose, followed by usage/alternative guidance, then safety and error semantics. Nothing is redundant, and the structure mirrors how an agent would want to evaluate the tool: what it does, when to use, what to expect.
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?
Given the tool's complexity and the existence of an output schema, the description is remarkably complete. It covers the execution chain (after malcolm_file_scans), safety, size limits, stream behavior, hash verification, and the distinction between 404 and other errors. An agent could invoke this tool confidently without further clarification.
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%, and the schema already explains both parameters fully. The description adds relational context: the filename comes from malcolm_file_scans, and url_only is connected to the size cap. Slight extra value over the schema, but not a heavy lift; hence a 4 rather than a baseline 3.
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 description opens with a specific verb + resource: 'Fetch one Zeek-extracted file from Malcolm's extracted-files server; returns METADATA ONLY.' This clearly distinguishes the tool from siblings: it returns metadata only, deals with a single carved file, and is tied to Malcolm's server. The explicit contrast with arkime_file_by_hash and arkime_session_pcap reinforces the unique scope.
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?
The description gives explicit usage direction: 'Use this after malcolm_file_scans, which supplies the filename.' It also names alternatives and their exact conditions: 'Use arkime_file_by_hash instead when you hold a content hash but no Zeek file record, and arkime_session_pcap for a session's packets rather than one carved file.' This is textbook when-to-use/when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Even though annotations already declare readOnlyHint=true and destructiveHint=false, the description adds substantial behavioral context: it resolves the name against the index mapping, aggregates over event.dataset, and describes three distinct outcomes including 'not found' with suggestions and 'exists but no documents.' It also discloses the default 24-hour time window and its implications, and states that output is plain text, not JSON. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the main purpose and uses a clear 'Behavior:' section to organize outcomes. Every sentence provides necessary information—purpose, usage, edge cases, and return format. It is detailed yet efficient, with no wasted words.
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?
Given the tool's moderate complexity (3 params, output is plain text), the description fully covers selection and invocation. It explains the three possible outcomes, the time-window caveat, and how to handle historical data. The existing output schema (plain text) means the description needn't enumerate return values, and the description already describes the types of messages. It is complete for an agent to use appropriately.
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 the baseline is 3. The description adds value by providing a concrete example for the 'field' parameter ('zeek.ssl.server_name') and explaining why it matters (only present in SSL records). It also clarifies the behavior of time_from/time_to in context, though the schema already describes the defaults. Overall, it enriches but does not fully replace the schema documentation.
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 description starts with a specific verb and resource: 'Show which event.dataset types actually contain a given field, with doc counts.' It clearly distinguishes this from sibling tools by focusing on profiling a field across datasets, and explicitly mentions using it to learn where a field lives before scoping a query.
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?
Provides explicit usage guidance: 'Use this to learn where a field lives...' and explicitly names alternatives for related tasks: 'To confirm the field NAME first, use malcolm_field_search; to list its distinct VALUES, use malcolm_field_values.' Also covers when to use time_from/time_to for historical data.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint, openWorldHint, destructiveHint), the description adds substantial behavioral context: per-lookup summary sections, independent error handling per lookup, all-failing results as an error, and the ambiguity of found=false due to NetBox being an optional subsystem with readiness key in malcolm_service_status. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the primary purpose in the first sentence, followed by usage guidance, return/error behavior, and the NetBox-readiness nuance. Each sentence earns its place; no wasted words, well-structured for readability and decision-making.
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?
The tool has an output schema and the description explains return structure, error semantics, and the critical ambiguity around found=false, referencing malcolm_service_status. Combined with schema and annotations, it is fully self-contained for an agent to select and invoke correctly, including alternatives and prerequisites.
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 descriptions already fully cover the individual parameters with examples (100% coverage), so baseline is 3. The description adds the 'Pass at least one of ip/device/prefix' constraint and clarifies that each supplied parameter becomes a lookup section, enriching the meaning beyond the schema alone.
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 description opens with a specific verb and resource: 'Resolve an IP, device name, or prefix to its NetBox asset (role, site, tenant).' It clearly distinguishes from siblings by naming malcolm_netbox_query and malcolm_netbox_sites as alternatives for other endpoints, and characterizing this tool as the 'fast path for the three common NetBox lookups.'
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?
Explicit guidance on when to use this tool ('to tell whether observed traffic involves a known asset and where it sits') and when to use alternatives ('For any other NetBox endpoint... use malcolm_netbox_query; to list sites use malcolm_netbox_sites'). It also instructs to pass at least one of ip/device/prefix, and references malcolm_service_status for disambiguating found=false.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint, destructiveHint, openWorldHint), the description discloses path validation ('path is validated to a NetBox app/model shape before proxying'), return format ('raw NetBox JSON response'), pagination behavior ('count, next, previous and results, with limit and offset accepted in params'), and the optional nature of NetBox as a subsystem. These details add significant behavioral context not captured in 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?
The description is appropriately sized for a generic endpoint-query tool. Every sentence earns its place: it covers purpose, alternatives, validation, return format, pagination, and deployment dependency in a logical flow without redundancy. The structure front-loads the primary action and then builds context efficiently.
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?
Given the tool's complexity as a generic endpoint query with pagination and optional subsystem dependencies, the description is complete. It explains return values (raw NetBox JSON, paginated lists), error behavior (bad path fails locally), and how to interpret empty results via malcolm_service_status. The presence of an output schema further reduces the burden, but the description covers essential context thoroughly.
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% for both parameters, so baseline is 3. The description adds extra semantics by noting that 'limit and offset' can be passed via the params object for pagination, and clarifies the path validation behavior ('bad path fails here rather than upstream'). It also reinforces the schema's examples with contextual use cases, providing more value than the schema alone.
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 description clearly states the tool queries any NetBox REST endpoint via a read-only GET proxy. It distinguishes itself from the sibling tools malcolm_netbox_lookup and malcolm_netbox_sites by positioning itself as the general escape hatch for endpoints those shortcuts don't cover, with specific examples like services, VLANs, interfaces, VMs, and contacts.
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?
The description gives explicit when-to-use guidance: use for endpoints not covered by shortcuts, prefer malcolm_netbox_lookup for common ip/device/prefix lookups, and use malcolm_netbox_sites to list sites (while noting this tool can return a site's full record via 'dcim/sites/'). It also mentions checking malcolm_service_status to determine if NetBox is deployed, which is valuable contextual guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint, but the description adds substantial behavioral context: it returns a 'condensed view' keyed by site id with only display, name, and slug, omitting status/tenant/counts. It also explains how to distinguish an empty directory from an absent NetBox subsystem via malcolm_service_status, going well beyond the annotation safety hints.
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?
The description is front-loaded with a clear one-sentence purpose, then provides usage guidance, return format, and operational context in a logical flow. Every sentence adds distinct value: it explains what the tool returns, what it deliberately omits, and how to handle the optional NetBox subsystem. Despite being longer than typical, it is dense and free of fluff.
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?
With an output schema present and a relatively simple zero-parameter list operation, the description is exceptionally complete. It explains the return object shape, the fields included, the limitations, the path to get full records, and the distinction between empty and unavailable systems. No missing context is evident.
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?
There are zero parameters, so the baseline is 4. The description does not need to add parameter-specific semantics, and it appropriately omits any parameter discussion. The schema coverage is 100% by virtue of having no parameters, and the description's focus on the result format is more relevant here.
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 description opens with a specific verb and resource: 'List the NetBox site directory: the physical or logical locations assets sit in.' It explicitly differentiates from siblings by directing users to malcolm_netbox_lookup for device/IP/prefix resolution and malcolm_netbox_query for other NetBox endpoints, making the tool's unique role clear.
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?
The description provides explicit when-to-use guidance ('Use this to learn which sites exist before drilling into a specific asset') and names concrete alternatives for follow-up actions. It also states when to use a different tool for full site records, offering clear decision-making guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only and non-destructive hints, but the description adds rich behavioral context: the exact response format, error handling for unreachable API, and the specific meaning of a pass including authentication validation and what it does not guarantee. This goes well beyond 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?
The description is front-loaded with the core purpose and then provides structured details in separate sentences. Every sentence earns its place, providing distinct pieces of information: endpoint, usage guidance, alternative tools, response format, error behavior, and limitations. No redundancy.
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 being a simple ping tool, the description covers everything needed: what it does, when to use it, what the response looks like, how errors are reported, and what the results do and do not prove. The output schema is present, so the raw response format need not be separately documented.
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?
There are no parameters, so the schema provides no information. With zero parameters, baseline is 4. The description adds the request method and endpoint (GET /mapi/ping) and explains the response, which is useful context even though not parameter-specific.
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 description opens with a specific verb and resource: 'Quick liveness check that the Malcolm API answers (GET /mapi/ping).' It clearly distinguishes this tool from siblings by explicitly naming alternative tools and explaining what this tool does not cover.
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?
Provides explicit 'when to use' guidance: 'Use this as the cheapest reachability probe.' It then gives alternative tools for related but distinct purposes (malcolm_service_status, cluster_health) and clarifies the exact meaning of a pass, which helps the agent decide when this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses non-obvious behaviors: runs two independent searches, 'limit caps EACH side separately', independent failures with 'direct_error'/'related_error' keys, and no time filtering (unlike some other tools). These go well beyond the basic safety hints provided by annotations and offer critical operational nuance.
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?
Although lengthy, every sentence contributes a distinct piece of information: purpose, usage guidance, alternative tools, behavioral caveats, and return format. The structure with paragraph breaks makes it scannable, and the key points are front-loaded in the first sentence.
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?
Given the tool's complexity (dual searches, independent failures, no time filter), the description covers all behavioral aspects an agent needs to invoke it correctly and interpret results. It even explains the return structure and error key handling, which is sufficient even without an output schema.
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. Description adds context by providing an example UID format and explicitly differentiating Zeek UIDs from Arkime session IDs. It also clarifies that limit applies per side, which reinforces the schema description but adds the dual-side emphasis.
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 description opens with 'Correlate one Zeek UID across sessions via both direct and cross-reference matches,' using a specific verb and resource. It clearly distinguishes this tool from siblings by explaining it queries both zeek.uid and rootId, which is a unique dual-key behavior.
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?
Explicitly states when to use (pivot from a single connection UID), when not to use (Arkime session id, plain single-field queries), and names alternatives (arkime_session_detail, malcolm_search). The sentence 'This tool earns its place only where one connection is recorded under two different keys' provides clear exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnly, openWorld, and non-destructive. The description adds substantial behavioral detail: it resolves three indirections (string JSON, reference NAME, two query shapes), explains error behavior ('Raises if nothing has that type and id'), and discusses environment-specific behavior (index-pattern id being the pattern vs a UUID). This goes beyond the annotations' safety hints and reveals internal mechanics.
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?
Although long, the description is densely informative with zero filler. It is front-loaded with the core purpose, then follows a logical flow from usage, to technical indirections, to field semantics, to error behavior. Every sentence contributes unique knowledge needed for correct invocation, and it is well-structured with paragraphs breaking ideas.
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?
With an output schema present, the description doesn't need to list return fields. It covers critical context that is not in the schema: when to use which sibling, what internal transformations happen, why `query` needs careful reading, and what errors occur. For a tool with hidden complexity, this description is exceptionally complete.
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 baseline is 3. The description enriches parameter understanding by explaining that 'Ids are not unique across types', how object_type affects resolution, and the linkage to malcolm_saved_objects. It also clarifies the semantic meaning of `query` and `language` in the context of the output, adding value over the schema's literal property descriptions.
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 description opens with a specific verb+resource: 'Read one saved object with its query, filters and index pattern already resolved.' It clearly distinguishes itself from siblings like malcolm_saved_objects (which only lists) and malcolm_dashboard_export (which only handles dashboards), making it unmistakable what this tool uniquely does.
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?
Provides explicit when-to-use guidance with named alternatives: use for saved searches and visualizations, not for dashboards (use malcolm_dashboard_export), and for traffic use malcolm_search or search_dsl. It also states that for saved-search ids this is the only route, giving strong usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite annotations already declaring readOnlyHint and non-destructive intent, the description adds substantial behavioral context: partial failure handling ('One probe failing adds an `errors` entry and keeps the rest; both failing is reported as an error'), version-specific key counts ('measured on Malcolm v26.07.1, 15 keys'), and how optional subsystems surface in the readiness map. This goes well beyond the annotation's baseline.
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?
The description is moderately lengthy but every sentence earns its place: purpose, usage timing, alternatives, output structure, error behavior, and a cross-tool caveat. It is front-loaded with the main purpose and flows logically.
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?
For a no-parameter status tool with an output schema present, the description is complete: it explains what the JSON summary contains, how partial failures are represented, and even notes version-specific behavior. It also warns about interpreting empty answers from malcolm_netbox_lookup or malcolm_file_scans, giving the agent necessary cautionary context.
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?
The tool has zero parameters, so the baseline is 4. The description compensates by clarifying the output structure (malcolm_version, mode, opensearch_health, per-service readiness map, 'N/total ready') and error entries, which adds meaningful context beyond the empty 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?
The description states the tool 'Report[s] readiness of each Malcolm service plus Malcolm version and OpenSearch health' – a specific verb and resource. It explicitly names sibling tools (malcolm_ping, cluster_health, malcolm_data_coverage) and explains how they differ, so it is clearly distinguished from alternatives.
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?
The description gives explicit when-to-use guidance: 'Call this before a hunt to confirm the whole stack is up.' It then names precise alternatives for other use cases: malcolm_ping for a bare API-alive check, cluster_health for OpenSearch green/yellow/red detail, and malcolm_data_coverage for data freshness/counts. It also warns against misinterpreting sibling results if the readiness map indicates a subsystem is not deployed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds valuable behavior: aggregations honor the DSL time filter, input guards reject malformed query_dsl and path metacharacters, and the tool returns the raw _search response. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but every sentence earns its place: purpose, usage, behavior, guards, and integration. It is front-loaded with the main purpose and flows logically without redundancy.
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?
Given the tool's complexity, annotations, output schema, and many siblings, the description covers all essential aspects: what it returns, when to use it, error behavior, and how to interoperate with arkime_build_query. Nothing critical is missing.
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. The description adds extra context beyond the schema—such as serializing the query_dsl object from arkime_build_query and noting the index guard—but most parameter meaning is already in the schema. Small added value justifies a 4.
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 description opens with a specific verb and resource: 'Run a raw OpenSearch DSL query and return its hits plus aggregations.' It also names sibling alternatives (count, malcolm_search, arkime_build_query), clearly distinguishing this tool's role.
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?
Provides explicit when-to-use ('Use this for full DSL control') and when-not-to-use guidance with named alternatives ('use count', 'use malcolm_search', 'use arkime_build_query'). This is exemplary usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only state readOnlyHint=true and destructiveHint=false. The description adds substantial behavioral detail beyond that: the returns format ('exp | db | type | group'), the per-parameter spelling decision, the existence of a third storage-path spelling, encountered error behavior (HTTP 403/500 cases), and pagination behavior ('... and N more'). This is entirely consistent with the annotations and enriches them.
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?
The description is lengthy but highly structured and front-loaded with the key purpose. It uses bullet-like sections for the three field spellings (exp, db, third spelling), with tables of examples and error cases. Every sentence carries substantive information or measurement evidence. The complexity of the tool justifies the length; there is no 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?
The description is exceptionally complete for a field-discovery tool. It covers the return format, the central naming ambiguity, per-parameter routing rules, error behavior, pagination, and the recommendation to use group filtering. With an output schema present and three fully described optional parameters, no critical aspect is left unexplained. It even provides concrete measurements and examples to illustrate behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although the input schema already has 100% coverage and descriptions for all three parameters, the tool description adds significant behavioral context for 'group' and 'limit'. It mentions the deployment has 192 groups and that narrowing by group is preferable to raising limit, and that the list often stops at limit with '... and N more'. These details clarify how to use the parameters effectively beyond their raw schema definitions.
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 description opens with a specific verb and resource: 'Discover the field names Arkime's routes accept — call before writing one.' This clearly states what the tool does. It also distinguishes itself from the sibling malcolm_field_search by explicitly noting this is the field-discovery tool for every arkime_* tool, parallel to malcolm for malcolm_* tools.
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?
The description gives direct usage guidance: 'call before writing one' and explains exactly when to use this tool (before writing any Arkime expression). It differentiates from malcolm_field_search and provides detailed routing rules for which field spelling each arrow parameter expects. It also advises narrowing with group instead of raising limit when results are truncated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and destructiveHint=false, but the description adds substantial behavioral context beyond annotations: the output is plain text with [src]/[dst] markers, two empty-result scenarios return sentences rather than failures, responses are capped at 200,000 characters, and oversized renders are refused with a way through. It also warns that payload can be hostile. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single well-structured paragraph, front-loaded with the core purpose, then systematically addressing siblings, output format, empty-result cases, size cap, and parameter-specific advice. Every sentence adds new information, avoiding redundancy or bloat despite being relatively long.
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?
Given the tool's complexity (payload content, variable output, edge cases, security implications) and the richness of the schema and annotations, the description is complete. It covers return format, distinguishing empty cases, size limits, safety warnings, and parameter behavior. The presence of an output schema further reduces the need to detail return structure, but the description still explains the plain-text rendering.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although schema coverage is 100%, the description enriches parameter understanding beyond the schema. It explains the practical effect of 'packets' (coalescing, handshake consumption, cost scaling), warns that invalid 'base' values are rejected and would otherwise silently fall back to ASCII, clarifies 'node' behavior (empty means lookup, unknown name returns an input error due to Arkime's 200 response), and elaborates on session_id spellings. This is substantive parameter guidance, not just schema repetition.
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 description opens with a specific verb and resource: 'Read the decoded payload of one Arkime session — the bytes that crossed the wire.' It immediately distinguishes itself from sibling tools by stating 'This is the only tool here that returns payload CONTENT' and explicitly names what siblings do instead, making the tool's purpose unmistakable.
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?
The description provides explicit guidance on when to use this tool vs alternatives: 'Use those when you need provenance or a hash; use this when the question is what was said — the HTTP request, the Modbus function code, the cleartext credential.' It also warns about hostile content and explains when results are empty rather than errors, giving clear usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark it readOnly and non-destructive, but the description adds substantial behavioral details beyond that: returns metadata only and never raw bytes, nothing is persisted to disk, downloads over 500 MB are refused, and multiple session ids are merged with the size ceiling applied to the total. These are non-obvious traits not present in 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded: the first sentence immediately delivers the key behavior ('returns METADATA ONLY'), and each subsequent sentence adds essential context (size limit, session id source, sibling distinctions) without redundancy. It earns its length by covering necessary operational details and exclusions.
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?
The description is self-sufficient: it explains return semantics, size limits, url_only bypass, session id provenance, merge behavior, and explicitly differentiates from three related sibling tools. Even without relying on an output schema, an agent has enough context to select and invoke the tool correctly in the appropriate scenario.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although the schema describes both parameters at 100% coverage, the description adds meaningful semantics not present in the schema: 'Several ids are merged into one combined PCAP, and the size ceiling applies to that merged total rather than to each session' and 'url_only=True is the way through, and the way to hand the URL to something outside this agent.' This enriches understanding beyond the basic property types.
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 description starts with 'Fetch and validate the PCAP for one or more Arkime sessions; returns METADATA ONLY,' which is a specific verb+resource statement. It clearly distinguishes the tool from siblings by explicitly contrasting it with arkime_session_detail, arkime_session_payload, and arkime_session_file_by_hash.
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 provides direct when-to-use and when-not-to-use guidance, naming alternatives: 'For a session's parsed fields rather than its packets use arkime_session_detail; for the bytes that crossed the wire... use arkime_session_payload.' It also states a prerequisite (session id only from arkime_sessions) and how to handle large sessions via url_only=True.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes far beyond annotations by disclosing the automatic event.dataset=alert filter, the substring search resolution against 500 common values, the 24-hour time limit on the pre-scan versus full history search, and the raw /mapi/document return format. No contradiction with readOnlyHint=true and destructiveHint=false.
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?
Although longer than typical, every sentence provides essential value: purpose, differentiation, behavior, and return type. The 'Behavior:' section is clearly structured and front-loads the most important usage guidance. No fluff or repetition.
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?
For a tool with 10 optional parameters and many sibling tools, this description covers all necessary aspects: what it does, when to use it, how it differs from siblings, behavioral quirks, and return format. The presence of output schema makes further return details unnecessary. It is fully self-contained for correct selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed parameter descriptions, but the tool description adds critical behavioral semantics not in the schema: how signature/category substring matching works, the 500-value pre-scan, and the interaction between time_from and the pre-scan window. This goes beyond mere parameter enumeration.
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 description begins with 'Search Suricata alerts with structured parameters, no field knowledge needed', which is a specific verb+resource statement. It explicitly differentiates from malcolm_search by stating 'Use this instead of malcolm_search when hunting Suricata alerts' and names sibling alert-related tools to avoid confusion.
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?
Provides explicit guidance on when to use this tool over alternatives ('Use this instead of malcolm_search when hunting Suricata alerts') and clarifies the difference between this and other alert mechanisms (malcolm_alerting_monitors, malcolm_alerting_alerts, malcolm_anomaly_detectors, malcolm_create_alert). It also explains the field-mapping advantage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the read-only/destructive annotations, the description discloses key behaviors: arguments narrow (AND) and never widen, results are capped at 100 printed names while the header counts all matches, and the field-type values are non-OpenSearch names. This provides meaningful context the annotations alone cannot convey.
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?
The description is front-loaded with its core purpose and then packs in high-value caveats and examples. While longer than typical, every sentence adds necessary operational detail, and there is no redundancy or 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?
Given the tool's complexity—interaction with sibling tools, non-standard field names, result truncation, and AND semantics—the description is remarkably complete. It covers return format, limits, exclusions, and parameter behavior, so an agent has everything needed to invoke it accurately.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Though the schema already documents all three parameters, the description adds substantial extra semantics: examples for prefix and keyword, an explanation that arguments narrow results in an AND fashion, and the precise allowed field_type values (string, integer, float, date, ip, geo) along with a warning that OpenSearch type names like 'keyword' will not match. This goes far beyond 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?
The description clearly states the tool's purpose: discovering field NAMES in Malcolm's index by keyword, prefix, or type. It explicitly distinguishes itself from sibling tools by naming malcolm_field_values for values, malcolm_field_profile for datasets, and arkime_field_search for Arkime-specific spellings.
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?
Provides explicit guidance: 'Use this first, before any query, to confirm a field name exists.' It also gives exclusions ('Do NOT source an arkime_* argument from here') and names the correct alternative tools for different needs. This is a model of when-to-use and when-not-to-use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Even though annotations mark readOnlyHint and non-destructive, the description adds valuable behavioral context: default time range covers ALL history (unlike malcolm_aggregate), filter values are matched exactly (no wildcards), and missing indexed fields report the correct field name above the response. These are critical operational nuances not in 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?
The description is dense yet well-organized: purpose first, alternatives second, defaults and edge behaviors third. Every sentence serves a purpose—no filler. It packs substantial guidance into a compact form without being verbose.
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?
For a search tool with an output schema and zero required parameters, the description covers all needed aspects: return format (raw /mapi/document response), field validation behavior, default time range, exact matching semantics, and explicit distinctions from sibling tools. The agent is fully equipped to select and invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description enriches parameters well beyond schema descriptions. It explains the filters parameter compiles to a terms query with exact matching, provides examples for exclusion (!), OR lists, and existence checks (!field:null), and clarifies time_from defaults. This is significant added value.
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 description opens with a specific verb+resource: 'Search Malcolm's indexed network traffic using Malcolm's simple filter dict.' It clearly distinguishes from siblings by explicitly naming arkime_sessions and search_dsl as alternatives for different cases.
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?
Provides explicit when-to-use guidance: 'Use this for field-based filtering with human-readable time ranges.' It names alternatives directly: arkime_sessions for Arkime syntax/session id, search_dsl for raw DSL, malcolm_field_search for field name confirmation. This goes beyond vague hints.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

Copy to your README.md:

[![mcp-server-malcolm MCP server](https://glama.ai/mcp/servers/nagameTW/mcp-server-malcolm/badges/card.svg)](https://glama.ai/mcp/servers/nagameTW/mcp-server-malcolm)

Score Badge

Copy to your README.md:

[![mcp-server-malcolm MCP server](https://glama.ai/mcp/servers/nagameTW/mcp-server-malcolm/badges/score.svg)](https://glama.ai/mcp/servers/nagameTW/mcp-server-malcolm)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/nagameTW/mcp-server-malcolm'

If you have feedback or need assistance with the MCP directory API, please join our Discord server