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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.