Netmon (demo)

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: BLOCKING latency with a 120s timeout, no recursive tree in one shot, Windows-only operation, devices permission requirement, and a safety note that write paths are on a permanent deny-list. This goes far beyond what the annotations convey.

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 dense and well-organized: purpose, required parameters, drill-down pattern, safety, latency, permissions, platform constraints, and an example. Every section earns its place and the core purpose is front-loaded in the first sentence.

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 no output schema, the description supplies the essential return semantics ('immediate-children size breakdown'), a recursion strategy, latency expectations, and platform constraints. It is complete enough for correct invocation, though the exact response fields and units are left implicit rather than stated.

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 schema already documents device_id and path. The description adds concrete value by clarifying JSON escaping with an explicit counter-example ('pass "D:\\" not "D:\"') and providing a full example call, which reduces the risk of malformed paths.

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 names a specific verb and resource: 'disk usage report' that 'returns the immediate-children size breakdown for the given path'. It also anchors the purpose with a concrete question ('D: drive is at 95%, what's eating it?') and clearly distinguishes it from generic agent tools by tying it to GETFOLDERUSAGEPATH.

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 gives an explicit drill-down usage pattern: start at the drive root, identify the largest child, and recurse. It also states when not to use it — Linux/macOS hosts have no agent-side equivalent — and emphasizes the deliberate non-recursive latency cap, so an agent knows not to expect a one-shot full tree.

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 it's a live read, has a 60s server-side timeout, returns 400 for offline/unenrolled devices, and the return shape depends on agent version. This is rich behavioral context that annotations alone don't provide.

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 purpose, then provides technical details, diagnostic patterns, limitations, and an example. Every sentence adds value with no redundancy; it's efficient and 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?

Despite having no output schema, the description covers return format ('rows as reported by GETPS'), error conditions, timeout, and usage examples. It provides everything an agent needs to call 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?

Schema description coverage is 100%, so the parameter is fully documented in the schema. The description adds a usage example (agent_processes({device_id: 42})) but no new semantic meaning beyond what the schema already states.

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 lists running processes on an agent-managed device, with a specific verb ('List') and resource. It also distinguishes itself by noting the process-kill endpoint is not exposed, and mentions pairing with sibling tools like agent_services, so it's easy to tell apart.

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 diagnostic patterns (pair with agent_services, correlate with eventlog_search) and states a when-not (kill endpoint not exposed). This gives clear guidance on 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 it read-only, idempotent, safe, but the description adds substantial behavioral context: live WMI read, 60s server timeout, 400 response for offline/unenrolled devices, and the wrapped API endpoint with permission scope. 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 purpose is front-loaded in the first sentence, and each subsequent sentence adds distinct value (endpoint, permission, use case, constraints, latency, errors, example). No filler or restating of the tool name.

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 one-parameter read-only endpoint with rich annotationsaced and no output schema, the description covers success shape, expected fields, failure modes, latency expectation, and a concrete call example. Nothing needed to invoke it correctly 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% (device_id described in schema) so the baseline applies. The description adds only modest semantic value: it frames device_id as the agent-managed host to query and gives an example call. No enum or conditional behavior to clarify.

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 Windows services on an agent-managed device'), a live-read semantics statement, and the wrapped endpoint. It is unambiguous and clearly distinct from siblings like agent_processes or agent_disk_usage.

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?

'Use this to answer is service X running on host Y' gives an explicit when-to-use. 'Service-control endpoints are deliberately NOT exposed' gives a clear when-not-to-use, preventing calls to a tool that can't start/stop services.

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 readOnly, idempotent, and non-destructive hints, but the description adds critical operational context: the upstream 500-row cap, meta.upstream_cap reporting, severity_label added server-side, pagination over post-filter results, and Laravel-enforced tag-scope. This goes beyond annotations and fully discloses the tool's constraints and server-side behavior.

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 lengthy, the description is tightly structured into labeled sections (default mode, drill-down, filters, caps, pagination, permissions, examples) with no fluff. Every sentence adds operational value, and the critical constraints are front-loaded before the examples. This is appropriate for a tool with 11 parameters and two distinct modes.

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 output schema, the description carries the burden of explaining return structures, and it does so thoroughly: default mode returns per-incident lifecycle timestamps plus aggregated outlet_types[], dispatch_count, failed_count, and computed status; drill-down returns the per-outlet dispatch ledger. It also covers pagination, caps, and filtering semantics, leaving no critical gap for correct usage.

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 still adds significant semantic value: it explains that incident_id switches to drill-down mode and is alert_history.id not alert_id, that hours applies against last_event_at, that status is computed from resolved_at, and that filters are AND-combined. These details are not present in the schema's per-field descriptions, making the description indispensable for correct invocation.

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 it is an authoritative stream of alert incidents with a default listing mode and a drill-down mode for per-outlet dispatch logs. It names the underlying tables and distinguishes itself from the sibling alerts_list by describing the incident lifecycle and aggregation, so an agent can tell them apart without opening the schema.

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 explains when to use default mode versus drill-down mode (e.g., 'Use this for did the email actually go follow-ups'), lists filters, and notes the upstream 500-row cap so the agent can warn users about truncation. It effectively guides the agent to the right mode and parameter combinations for common questions.

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 well beyond the read-only/idempotent annotations, disclosing client-side filtering/pagination, the source discriminator and synthetic id, the absence of throttle/renotify semantics for modern alerts, and class-dependent meaning of last_result_count and last_evaluated_at. It even warns against incorrect claims such as flap-damping, which is a valuable behavioral guardrail.

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 front-loaded: purpose, endpoints, output shape, behavioral caveats, filters, pagination. Given 8 optional parameters, two alert axes, and no output schema, the length is justified; slight redundancy and prose density keep it from a perfect score.

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 output schema, the description carries the full burden of explaining return values, and it does: row shape, id/raw_id, discriminator, class-specific fields, meta pagination fields, permission requirement, and a concrete example. An agent has enough context to invoke and interpret results 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?

Even though schema coverage is 100%, the description adds critical semantics: filters are AND-combined, scope defaults to 'all', class/device_id are silently ignored on the opposite axis, severity meaning differs by axis/class, and pagination is client-side with post-filter meta fields. This transforms parameter definitions into an operational contract.

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 (list alert definitions) and scopes it to both axes of the rule engine, naming all modern classes and the legacy view. It clearly distinguishes this from alerts_history by noting the latter covers what actually fired, preventing confusion with the sibling tool.

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 explains when to use this tool versus alerts_history ('For what actually fired and was delivered, use alerts_history') and provides an example call. It also clarifies filter scoping (class ignored on legacy, device_id ignored on modern) so an agent can select appropriate filters, though it does not enumerate all alternative tools or 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 already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint: false, so the safety profile is covered. The description adds useful behavioral context by revealing that a network interface is automatically selected and that the tool also returns the list of all suitable interfaces found. It 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 two sentences with no filler. The core action and purpose are front-loaded, and the second sentence adds a relevant behavioral detail without unnecessary elaboration.

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 single-parameter, annotation-covered tool, the description is mostly adequate, but no output schema exists and the description does not specify the response format or error behavior. It also does not state what happens if no suitable interface is found or if the MAC address cannot be resolved, which an agent would need to handle failures 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 has 100% coverage for the single parameter target_ip, and the description's mention of 'Local IP' essentially repeats the schema description. The description adds no new semantic detail beyond what the structured schema already provides, so the baseline score 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?

Description states a specific verb and resource: performs an ARP lookup for a Local IP to find its MAC address. It also adds a distinguishing behavior (automatic interface selection) and clearly separates it from broader sibling tools like arp_table by focusing on single-address lookup.

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?

No when-to-use or when-not-to-use guidance is provided. It never mentions alternatives such as arp_table or ping, nor does it state conditions like 'use this for a single local IP instead of the full ARP table.' The usage context must be inferred entirely from the name and 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?

Discloses behavioral details not visible in structured data: the tool wraps POST /api/getArpTable, returns a collapsed view of arptable + _dns, deduplicates by IP keeping the latest entry, and has a security-relevant quirk — it ignores subnet-level/tag-level scoping and shows the whole LAN. It also documents permission requirements and scope implications. Beyond this, the annotations already mark it readOnly/idempotent/destructive=False, so the description's disclosure of the collapse, dedup, and tag-scoping behavior goes well beyond what annotations provide. Anthropic's 'beyond annotations' bar is satisfied.

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-organized with a clear lead sentence, explicit differentiation, a structured row definition, and examples. Everything earns its place.

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?

Covers endpoint wrapper, filtering semantics, output shape, permission implications, and usage patterns. With annotations carrying the read-only profilehb, nothing needed to call it correctly is missing.

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

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

Schema covers 100% of params. The description adds usage color: hours defaults to 24, search is substring ILIKE across ip/mac/hostname, and the examples show real combinations. Description enriches the schema without repeating 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 clearly states the specific action ('Lists hosts observed on the local LAN(s) via ARP table') and scopes it with 'what devices have we seen recently?' It also introduces the resource (ARP table) and distinguishes it from the sibling `arp_lookup` by contrasting historical vs. current single-IP resolution. The row structure is explicitly listed, and the example usage further anchors the purpose. No ambiguity remains about which tool is which.

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 differentiates from sibling `arp_lookup` by naming it and contrasting single-IP MAC resolution with the historical multi-host view. Provides concrete example calls with different filters, making it clear when and how to use the tool. This is a model example of 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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: the upstream endpoint refreshes status from netmond's IPC for active captures, making counters live, and it returns the same row shape as capture_list. It also explains why the chunks endpoint is excluded. Minor gap: it doesn't describe error behavior or what happens if the capture id doesn't exist, but the added context is strong.

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: it opens with the core purpose, then explains the live-refresh behavior, return shape, exclusions, permission, and an example. Every sentence earns its place, and the exclusions are clearly separated from the main behavior.

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 single-parameter read-only tool with rich annotations and a 100% schema-covered parameter, the description is complete. It covers the endpoint, live behavior, return shape, exclusions, permission, and an example. There is no output schema, but the description explicitly states the return shape matches capture_list rows, which is sufficient for an agent to understand the result.

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% and the only parameter (id) is already described as 'Capture id (captures.id).' The description adds a concrete example (capture_get({id: 17})) and clarifies that the id refers to a capture row, which reinforces the schema. Since the schema fully documents the parameter, the description's added value is modest but sufficient.

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 ('read-only single-capture detail'), names the wrapped endpoint (GET /api/captures/{id}), and distinguishes it from capture_list and capture_stop/delete/download. It clearly identifies the resource and scope, making it easy for an agent to know what this tool does.

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 (single-capture detail, live counters for active captures) and what it is NOT for: capture_stop, capture_delete, capture_download, and the chunks endpoint are not wrapped. It also gives a permission note and a concrete example, so an agent has clear selection and invocation 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, and the description reinforces this with 'Read-only is deliberate' and explains why pcapng bytes aren't suitable for LLM output. It adds concrete behavioral details beyond annotations: the upstream returns the 200 most-recent rows ordered by id desc, filters are client-side AND-combined, and it lists exact row fields (id, user_id, device_id, status, etc.). This gives the agent a clear model of what to expect 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?

The description is well-organized: it front-loads the core purpose and endpoint, then covers usage, row fields, filters, exclusions, and permission, ending with three concise examples. Every sentence earns its place; no filler. The structure makes it easy to scan for the key decision points, and the examples are short and illustrative. 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?

For a read-only list tool with no output schema, the description is remarkably complete. It specifies the exact row fields returned, pagination defaults (per_page default 50, max 200), filter semantics, and the ordering behavior. It also mentions the permission requirement and provides usage examples. An agent has everything needed to invoke it correctly and interpret the response, so 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%, so every parameter already has a description in the input schema. The description adds minor context beyond that: it notes filters are 'client-side, AND-combined' and clarifies search is a substring on label (already in schema). It also demonstrates usage with examples like capture_list({status: 'running'}). These are helpful but not essential given the schema's completeness, so a 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 precise verb-resource pair ('Read-only listing of packet captures') and immediately ties it to a concrete endpoint ('Wraps GET /api/captures'). It also distinguishes itself from sibling capture_get by stating it lists while capture_get drills into a single row, and clarifies what it does NOT cover (creation, stop, delete, pcapng download). An agent can confidently select this tool over siblings without opening schemas.

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 tells when to use it via concrete question examples ('is there a capture running on device X?', 'do we have packet evidence?') and pairs it with capture_get for deeper inspection. It also states exclusions ('creation, stop, delete, and pcapng download endpoints are NOT wrapped') and explains why, giving clear when-not guidance. This goes beyond mere context and provides actionable selection 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context: it reveals the underlying API endpoint (GET /api/devices?search=<q>), the default pagination values (per_page=25, max 200, page=1), and the required permission ('devices'). This goes beyond the annotations and helps the agent understand side effects and constraints.

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 well-structured: a one-sentence definition, a usage-routing sentence, a pagination/permission line, and a concrete example. Every sentence earns its place, and the most important scoping information is 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?

For a simple read-only search tool with full schema coverage and safety annotations, the description is nearly complete. It covers the API equivalent, pagination defaults, permission requirement, and an example. The only minor gap is that it doesn't describe the return shape, but since there is no output schema and the tool is a thin wrapper over a list endpoint, this is a small omission rather than a critical one.

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 schema already documents all three parameters (q, page, per_page) with types and defaults. The description adds a little extra meaning by explaining q as a substring match against label or ip_address and by restating pagination defaults, but it doesn't significantly go beyond the schema. 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 ('Find devices') and resource ('matching a substring of label or ip_address'), and explicitly distinguishes it from device_list by calling it a convenience wrapper for a one-arg shortcut. This makes the tool's purpose unambiguous and differentiates it from the sibling device_list.

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 device_find ('the one-arg shortcut for does anything look like X?') and when to use device_list instead ('when you need tag/status filters or relation includes'). It also provides a concrete example, leaving no ambiguity about selection.

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 cover readOnly/idempotent/non-destructive behavior, so the description adds value beyond them: it discloses the default compact output, logs_truncated behavior, unbounded tracker count, window scoping, permissions, and the self-monitoring 127.0.0.1 device quirk. There is no contradiction with 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 front-loaded with the purpose, then transparently explains the payload-size tradeoffs and ends with useful examples. It is longer than strictly necessary, with specific byte measurements, but each paragraph addresses a real agent decision and there is no 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?

With no output schema, the description must carry the burden of explaining response shape and edge cases, and it does: default identity+latest value+log_count, include_logs and include_walk_data behavior, logs_truncated, window influence, unbounded trackers, and the self-monitoring device id. An agent can call this tool correctly without relying on external docs.

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% and the input schema already describes bounds, defaults, and behavior for parameters. The description adds meaning by explaining why include_logs is off by default, how max_log_rows interacts with log_count, and how hours/pair start_time/end_time scope both log_count and the netflow rollup. This is above the baseline but the schema already does a lot of the work.

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 concrete verb and resource: 'Fetch one device with its related state' and enumerates the attached data (tags, alerts, trackers, netflow rollup). It also distinguishes the tool from siblings by naming device_metric_summary and interfaces_search as alternatives for specific questions.

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 tells the agent to use device_list or device_find first to locate an id, and points to device_metric_summary for degradation questions and interfaces_search for fleet-wide interface metadata. It also gives clear guidance on when to enable include_logs and include_walk_data, with warnings about response sizes.

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, idempotentHint, and destructiveHint. The description adds crucial context beyond these: the required permission, server-side tag-scope enforcement, opt-in relation flags to control response size, and pagination with has_more. 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 well-structured with clear sections: purpose, filters, relation flags, pagination, and an example. It is concise despite covering many parameters, using bullet points to avoid verbosity. The example is illustrative and the whole is easily scannable.

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?

Despite 13 optional parameters and no output schema, the description explains every aspect needed for correct invocation: filter options, relation flags, pagination mechanics, and permission requirements. It also hints at response shape via meta.pagination.has_more. For a read-only listing tool, this is comprehensive.

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 baseline is 3. The description adds meaning beyond the schema by explaining tag slugs (stable hyphenated form vs spaces), status based on latest ping, search being case-insensitive substring over label+ip, pagination defaults (25, max 200) and the has_more indicator, plus a concrete usage example. This goes well beyond what the schema provides.

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 (List) and resource (monitored devices), and adds the HTTP endpoint and permission. It is clearly distinct from sibling tools like device_get (specific device) or device_find (search) by focusing on listing with filters and relations.

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 detailed usage instructions including optional filters, relation flags, and pagination behavior, but does not explicitly name when to use this tool versus alternatives like device_get or device_find. The context strongly implies listing vs. lookup, but an explicit exclusion would be stronger.

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 annotations: it discloses fixed-window vs time-bucket behavior, per-metric return fields, empty-array semantics for disk, tag-scoped permission, and endpoint mapping. Annotations already cover readOnly/idempotent/destructive safety, so the description adds the missing behavioral context rather than contradicting it.

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 precise summary and then well-delineated sections for metric backends, common discovery pitfalls, alternative usage, and permission. It is long, but most sentences carry unique information; a couple of future-looking or expensive-half remarks are extras the agent could do without.

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 two-backend tool with no output schema, this is very complete: it describes the meaning of each return group, the failure semantics of empty arrays, permission scoping, and the correct way to obtain target_id via device_get. No critical call decision is left to inference.

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?

Even with 100% schema coverage, the description adds valuable semantics: target_id is explicitly 'a TRACKER id, never a device id', it shows where the id lives in device_get’s response, and warns that passing a device id silently returns the wrong tracker or a 404. The metric parameter is fully mapped to distinct upstream endpoints and return shapes.

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 a specific resource (single device-tracker), a specific operation (summary stats), and the time windows/metric types. It also distinguishes itself from device_get for raw samples and notes the port-stats omission, so an agent can differentiate it from siblings without opening schemas.

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 fixed-window summary to assess degradation, and explicitly redirects to device_get for raw log samples underneath it. It also states what upstream endpoints are covered and that port-stats has no equivalent, which are clear when-not conditions.

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, idempotentHint, destructiveHint), the description adds critical behavioral context: it requires the 'logs' permission, decodes server-side, omits base64 bytes in payload, and provides a detailed response envelope structure. This significantly enhances transparency for the agent.

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 fairly long but every section contributes: the core action, permission, and the comprehensive response envelope. It is front-loaded with the primary verb and resource, and the detailed field list is justified given the absence of an output schema. The length is appropriate for the 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?

With no output schema, the description fully enumerates the return envelope (summary, endpoints, app_layer, flow, payload, decoded, findings, metadata, raw record) and explains key details like payload truncation and decoded protocol parsing. It also specifies the prerequisite of using eve_search for id discovery, making the tool self-sufficient for correct 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?

The schema already fully documents the id parameter, including its type and source (from eve_search results). The description reinforces this by mentioning 'by id' and referencing eve_search, but does not add substantial new meaning beyond what the schema provides.

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 fetches a single Suricata EVE event by id, decodes it server-side, and wraps a specific REST endpoint. It differentiates from siblings by focusing on single-event retrieval and explicitly mentions using eve_search to locate ids, which is the complementary search tool.

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 instructs to use eve_search to locate ids, establishing a clear workflow and an alternative tool. It implies the tool is for retrieving full event details when an id is known, though it does not explicitly enumerate other alternative tools or state 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 already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds substantial behavioral context: required permission ('logs'), tag-scoping behavior, the raw Windows severity mapping (with the caveat that 0 is not Information), window semantics, limit behavior, and the fact that 'total' in the response is the full match count. This goes well beyond the annotations and enriches the agent's understanding of side effects and edge cases. 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 appropriately structured: it opens with the core purpose, then breaks down key nuances (severity, window, limit, total) in separate logical segments, and ends with a concrete example. Every sentence earns its place—there is no filler or redundancy. The length is justified by the tool's complexity, and the information is front-loaded with the most critical semantics early.

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 (10 optional parameters, no output schema), the description covers all critical operational pitfalls: the severity mapping (especially the non-intuitive 0 value), window exclusivity, limit behavior, and the meaning of 'total'. It also gives an example. While the return format is not described (no output schema), the mention of 'total' in the response gives a helpful hint. An agent has enough information to call this tool correctly without further research.

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 significant meaning beyond the schema: it explains the severity values and that names or ints are accepted, clarifies the window option (hours OR start/end_time pair), the limit default and maximum, and the advice to use filters rather than increasing limit when total exceeds it. It also notes that 'event_id' can be a single int or array, though the schema already hints at that. This is additive value, not 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 clearly states the tool searches Windows Event Log entries ingested from Netmon agents, wraps a specific API endpoint, and notes tag-scoped server-side filtering. It distinguishes from sibling tools like syslog_search by specifying the Windows Event Log domain and the Netmon ingestion source. The verb 'search' and resource are explicit, 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 detailed usage context: it explains the severity mapping (including the non-obvious 0='logalways' not being Information), the window options (hours vs start/end_time), the limit default and max, and advises narrowing filters when total exceeds limit. However, it does not explicitly name alternative tools (like syslog_search) or state when not to use this tool, so it falls short of explicit when-to-use vs. when-not-to guidance. Still, the usage constraints are clearly articulated.

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, idempotentHint=true, destructiveHint=false. The description adds valuable behavioral context: permission requirement (logs), severity scale semantics, IP filter OR/AND logic, device_id translation, and total vs limit behavior. No contradictions with annotations.

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

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

The description is well-structured: front-loaded with the core purpose, then detailed behavioral notes presented in clear, scannable paragraphs. Every sentence adds value, including the practical example at the end. Length is justified given 14 parameters and no output 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 complexity (14 parameters, no output schema, no enums), the description covers all critical usage aspects: severity mapping, IP filter behavior, device_id resolution, time window selection, limit and total handling, and provides an example. It adequately prepares an agent to invoke the tool correctly without needing external documentation.

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 71%, but the description adds meaning for many parameters beyond the schema: severity names-to-int mapping, IP OR/AND semantics, device_id resolution to src/dst IP, hours vs start_time/end_time alternatives, limit defaults and max, and use of signature_id for narrowing. It compensates for undocumented params like vlan and ports with contextual explanation.

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 verb 'search', the resource 'Suricata EVE-format IDS events', and wraps the specific endpoint GET /api/eve/list. It distinguishes itself from generic search tools by emphasizing EVE format and tag-scoping, which separates it from siblings like eventlog_search or syslog_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?

Provides explicit parameter usage rules: severity scale mapping, IP OR/AND behavior, device_id resolution, window selection (hours vs start/end), limit default and max, and how to narrow results. It does not explicitly compare to alternatives like eve_get or eventlog_search, but the detailed usage conditions are sufficient for correct invocation.

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, destructiveHint, etc., but the description goes far beyond them: byte totals are window-approximate, rows vs conversations distinction, direction semantics (as_source/as_destination), server-side 168-hour ceiling, 10-second statement timeout, tag scoping on endpoints only, and error behavior for too-wide windows. This is rich behavioral context not derivable from annotations.

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

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

The description is long but every section carries necessary behavioral detail: window semantics, direction handling, row counting, tag scoping, and error behavior. It is front-loaded with the core purpose and organized by topic. Slightly longer than strictly minimal, but every sentence adds value for a complex tool.

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 return structure, default/max limits, window interactions, timeout behavior, row-count semantics, direction normalization, tag scoping, and example usage. It leaves little for an agent to guess. No output schema exists, so the description's explanation of what each returned section means is essential and well supplied.

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 adds crucial semantics: ip matches on either endpoint, hours vs start_time/end_time with server-side ceiling, limit meaning with `other` bucket reconciliation, and the row-count vs conversation-count meaning of `conversations`. This goes well 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 first sentence names the exact verb and resource ('Summarize one host's network conversations'), specifies the outputs (top peers, top ports, other buckets), and contrasts with netflow_search ('before pulling rows'). This makes the tool's purpose unambiguous and distinct from 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 to use this tool before pulling rows with netflow_search, and gives concrete usage context: when to use hours vs start_time/end_time, how limit behaves, and which sibling to consult for raw rows. This is direct when-to-use guidance with implicit exclusion of 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?

The description goes far beyond the annotations. It discloses that `whois` comes from whois.iana.org only, that GeoIP responses are passed through verbatim with variable keys, that the whole `geoip` key may be omitted for non-routable addresses, and that hostname resolution behavior depends on whether resolution succeeds. It also provides detailed guidance on how to interpret PTR records and ASN fields for classification, and explicitly warns against reporting RIRs as operators. This is exceptional behavioral transparency for a read-only lookup tool.

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 every section earns its place. It is front-loaded with the core purpose, then systematically covers WHOIS source, GeoIP variability, and classification heuristics. The structure uses clear paragraph breaks and bullet-like guidance. It is not concise in the sense of being short, but it is efficiently organized and dense with necessary caveats. The length is justified by the complexity of the tool's output interpretation, though a slightly tighter summary of the classification heuristics could have been considered.

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 parameter, no output schema, and rich behavioral caveats, the description is complete. It covers input semantics, output variability, data sources, interpretation guidance, and failure modes (missing PTR, missing ASN, non-routable addresses). An agent has everything needed to call the tool correctly and interpret the response. The annotations (readOnlyHint, idempotentHint, destructiveHint) already cover the safety profile, so the description's focus on data interpretation is appropriate.

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 has 100% description coverage for the single parameter `entity_identifier`, which is described as 'The IP address or hostname to query.' The description adds meaningful semantics beyond this: it explains that a hostname is resolved to an IP for GeoIP, and an IP gets a reverse DNS lookup. It also clarifies the input must be a public IP or hostname. The only minor gap is that the description doesn't explicitly state the expected format (e.g., IPv4 vs IPv6), but the schema already covers the basic meaning, so the description adds sufficient value.

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: 'Retrieves WHOIS, GeoIP and DNS information for a public IP address or hostname.' It clearly distinguishes the tool's scope from siblings like search_ip or arp_lookup by naming the three data types and the input type. The annotation title 'Look Up WHOIS, GeoIP and DNS' reinforces the purpose, and the description adds detail about resolution behavior that makes the tool's function 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 explains when to use this tool: for WHOIS, GeoIP, and DNS lookups on public IPs or hostnames. It also provides implicit guidance by contrasting with what the tool does NOT do—it does not query the RIR's whois server, and it does not return ISP/operator information. This helps an agent avoid misusing the tool for operator attribution. The sibling list includes related network tools (search_ip, arp_lookup, traceroute), and the description's clarity about scope effectively routes the agent to this tool for the right use case.

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/idempotentHint/destructiveHint, and description goes well beyond them: it says the endpoint returns the full list in one shot, filtering happens client-side with AND-combination, permissions are tag-scoped server-side via withUserTags, and explicitly tells it says it does NOT return status/octets/errors/MTU/speed and must not fabricate them. This level of behavioral disclosure is exactly what an agent needs on an unmodeled fleet query.

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 the two-sentence ideal, but it is well chunked with bold section headers and examples at the end. Every section—metadata contract, filters, pagination, permission, examples—earns it implied place. Slight redundancy persists with the input schema's parameter descriptions (e.g., default 50/max 200, case-insensitive substring), keeping it from a 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?

There is no output schema, so the description correctly carries the full burden: it names the exact per-row fields (id, device_id, device_label, name, interface, description), clarifies which fields are absent, explains pagination behavior on large installs, and states the rule to not fabricate missing stats. A model can make a correct call and interpret the response without any other source of truth—there are no hidden traps left unaddressed.

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% and every parameter has its own informative description, so the baseline is 3. The description adds notable value by stating that filters are client-side, AND-combined, that page/per_page control pagination over the full upstream list, and by giving three realistic invocation examples (device_id restriction, search-only, search+per_page). The semantics genuinely help beyond the schema, though schema already did much of the work.

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 question the tool answers ('what interfaces are tracked across the fleet...') and names the exact resource ('interface metadata listing') and the wrapped endpoint. It distinguishes itself from siblings by emphasizing metadata-only, cross-device scope, and filter by name/device, so an agent can separate it from netflow, syslog, or per-device stats 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 explicit guidance on when to paginate (tens of thousands on interfaces) and when to follow up with device_get(id, interfaces=true): when per-interface statistics are needed. It does not enumerate sibling tools, but the specific follow-up instruction and the metadata-only scoping make usage conditions clear enough to differentiate from 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?

Goes well beyond the readOnlyHint/idempotentHint/destructiveHint annotations by spelling out the surprising safety property: all-zero results are not proof the stream is clean. It enumerates the four stream_health states, the extra verification call for stale/silent verdicts, and the permission requirement, giving an agent a robust model of the tool's runtime behavior.

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 paragraph-form but extremely well structured: a one-sentence summary, a stream list, a usage guidance note, and a separate stream-health section. Every sentence earns its place; no fluff or repetition. The most critical safety information (ALL-ZERO IS NOT SAME AS CLEAN) is emphasized.

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 three backends, a window selection, device filtering, and the risk of misleading zero-results, the description covers all branches. It even mentions the permission model ('logs. Tag-scoped server-side') and explains the meaning of meta.stream_health. There is no output schema, but the description says what to expect ('numeric key and label') and how to interpret 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 description coverage is already 100%, but the tool description adds parameter meaning beyond the schema: it maps the stream enum to the underlying endpoints and severity ranges (0-7, 0-5, 1-3), explains the window alternatives, and clarifies the eve device_id translation. This fills in the semantics the schema alone cannot convey.

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?

States a specific verb, resource, and scope: 'Count log events grouped by severity over a time window.' It distinguishes itself from row-returning same-family tools by saying it returns 'one tight rollup instead of 1000 sample rows,' so an agent can tell when to call this vs syslog_search/eve_search/eventlog_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?

Gives an explicit usage rule: 'Use this for triage before pulling rows.' It also details stream selection, end-time pairing, and the device_id translation for eve. Does not name the exact sibling tools to switch to when rows are needed, but the distinction from 'pulling rows' is clear and actionable.

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, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: it does NOT compute whether a window is active right now, it depends on server local clock and dawom interpretation, and it returns a human-readable description field to avoid LLM misinterpretation. It also discloses the legacy-only route constraint for per-alert mode. This 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 well-structured with clear sections: purpose, two modes, legacy constraint, row fields, limitation note, permission, and examples. Every sentence earns its place, and the most important usage guidance is front-loaded. The examples at the end are concise and illustrative without being verbose.

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 list tool with one optional parameter, the description is complete. It covers what the tool returns (schedule fields, human-readable description), how to use it in both modes, its limitations (no active-window computation), and its relationship to modern vs legacy alerts. The output schema is absent, but the description compensates by listing the row fields. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100% and the single parameter alert_id is already described in the schema. The description adds meaning by explaining that setting alert_id switches to per-legacy-alert mode and that modern alerts use routing rules instead. This is a meaningful addition beyond the schema, though the schema already covers the basic semantics.

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 lists maintenance windows (suppression schedules that gate alert dispatch) and distinguishes it from sibling tools by explaining its role in alerting. It also explicitly names two modes (global catalog vs per-legacy-alert) and the exact API endpoints they wrap, making the tool's 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 when-to-use guidance: use when a user asks 'why didn't this page me' or 'is this device under maintenance right now'. It also gives clear exclusions: modern alerts should use routing rules, not this per-alert path, and it explicitly says the tool does NOT compute active windows, directing users to alertmond IPC for reliable yes/no. 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, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds substantial behavioral context beyond annotations: the 15-minute retention horizon, the cleanup_netflow deletion behavior, the overlap window matching semantics, the strict-equality filter behavior, the tag-scoping on endpoints rather than flow_src, and the limit default/max. It even explains why a 24-hour request may return empty, which is exactly the kind of behavioral disclosure that prevents false fault reports.

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 every section earns its place: the horizon warning, the drill-down use case, the filter semantics, the window semantics, and the example. It is front-loaded with the core purpose and the most critical constraint (15-minute horizon). It could be slightly tightened, but the density of actionable information is high and the structure (purpose, horizon, filters, window, example) is logical.

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 15-parameter tool with no output schema, this description is remarkably complete. It covers the data source, the retention horizon, the filter semantics, the window matching, the limit behavior, the tag-scoping behavior, and gives a concrete example. The only minor gap is the return format, but with no output schema and the description already explaining what fields survive the rollup, an agent has enough to call the tool correctly and interpret 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?

Schema description coverage is 93%, so the schema already documents most parameters well. The description adds meaning beyond the schema by explaining the compound vs strict filter semantics, the overlap window matching, and the tag-scoping behavior. It doesn't add per-parameter detail for every field, but the schema already covers those; the description's added value is in the cross-parameter semantics and the horizon warning, which is more important than repeating field-level docs.

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: 'Search raw NetFlow records (per-flow, not aggregated).' It immediately distinguishes itself from the aggregated sibling netflow_search, and the rest of the description reinforces the drill-down role. The title 'Search Raw NetFlow' is consistent, and the description names the exact endpoint and permission, leaving no ambiguity about what the tool does.

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 tool for raw per-flow drill-down within the 15-minute horizon, and use netflow_search for anything beyond that. It also warns against using src_ip/dst_ip when the side is unknown and directs the agent to the compound ip/port filters. This is exemplary routing behavior with clear alternatives 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 already declare read-only/idempotent behavior, and the description goes well beyond that: union arms, OVERLAP window semantics, pro-rated window_bytes vs full bytes, direction normalization, lack of a packets column, and tag scoping on endpoints. It even names the wrapped endpoint and required permission.

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?

Long but information-dense; each paragraph addresses a distinct correctness concern such as filter semantics, window behavior, output interpretation, and scoping. The most important sibling distinction is front-loaded, and nothing reads as 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?

For a complex search tool with no output schema, the description explains both request semantics and key response fields: window_bytes, bytes, is_raw, and total. It also covers tag scoping, authorization, and truncation guidance, giving the agent everything necessary to invoke and interpret results 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?

Although the schema covers 100% of parameters, the description adds crucial meaning the schema cannot: strict vs compound matching, src_port ANY semantics, dst_port as the lower port, hours OR start_time/end_time, and the meaning of `total` and `limit`. The example further anchors correct usage.

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 precise verb and resource: 'Search the FULL NetFlow history' via a union of raw and rollup data. It also explicitly distinguishes itself from netflow_raw_search by scope and use case, so an agent can immediately tell them apart.

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 names netflow_raw_search as the drill-down alternative and states the conditions for choosing it: per-flow packet counts and exact timing. It also provides concrete filter guidance, such as preferring the compound `ip` filter unless the host's side is known.

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 idempotent; the description adds meaningful behavior beyond that: the wrapped endpoint, the required permission ('devices'), and the in-tool aggregation logic including severity breakdown and top-N calculation. No contradictions with annotations.

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

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

Three tight sentences: use case, endpoint + aggregation behavior, and sibling navigation. Every sentence earns its place and the most decision-relevant information is 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?

For a single-optional-parameter summary tool, the description covers the use case, endpoint, permission requirement, output dimensions, and the key sibling alternative. Even without an output schema, an agent has enough 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?

Schema coverage is 100%, so the baseline is 3, but the description adds real value by clarifying that top_n refers to 'top-N devices by alert count,' resolving the otherwise ambiguous 'loudest' terminology 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 names a specific purpose ('high-level network health snapshot'), a concrete underlying endpoint, and the exact aggregate outputs (device count, active alert count, top-N devices). It also positions itself against the sibling device_get by presenting the tool as a summary view rather than a drill-down.

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 scopes the tool to 'how's the network?' style questions and tells the agent to use device_get for specific-device drill-down. It does not enumerate every alternative like alerts_list or device_list, but the primary routing guidance is clear.

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 well beyond the annotations (readOnlyHint, idempotentHint, destructiveHint) by explaining nuanced behaviors: status false is a normal result with distinct reasons (packet_loss, unreachable, unresolved), status null means UNKNOWN and should not be read as down, and hostname resolution persists even when down. It also discloses the fixed packet count. This is exceptionally transparent and adds significant value beyond the structured 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 lengthy but every sentence earns its place. It is front-loaded with the core purpose, then explains the execution context, return fields, and edge cases in a logical order. The structure is clear and the level of detail is justified by the subtle semantics of the tool. No fluff 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?

With only one parameter and no output schema, the description thoroughly covers all necessary aspects: the underlying API, permission requirement, execution location, return fields and their meanings, special status values, and an example. Nothing an agent needs to call this tool correctly 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 describes the target parameter as 'IP address or hostname to ping' with 100% coverage. The description adds an example call but no additional semantic meaning beyond what the schema provides. Per the rubric, baseline 3 is appropriate when the schema carries the burden, and the description does not materially enhance parameter understanding.

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 and resource: 'Ping a target host from the Netmon server.' It also differentiates itself by clarifying the execution location (netmon server) and the monitoring context, which helps distinguish it from sibling tools like traceroute or snmp_test.

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 clear context on when to use this tool: for reachability questions from the netmon perspective. It also mentions an alternative for longer tests ('use the system tools UI'), though not a sibling MCP tool. It does not explicitly list exclusions or compare with sibling tools, but the context is sufficient for an agent to decide when this tool applies.

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, idempotentHint, and destructiveHint false, but the description adds substantial behavioral context: the probe originates from netmon rather than mcpmond, latency is ~30-90s with a 120s client timeout, and the precise return structure (host element with status, address, ports[]). It also mentions the permission requirement ('tools'). This 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 front-loaded with the core purpose in the first sentence, then builds logically: wrapping endpoint, origin, constraints, return format, latency, and an example. Every sentence contributes new information; no filler or repetition. The structure is easy to parse and the example at the end aids comprehension.

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?

Despite lacking an output schema, the description fully specifies the return format (nmap host element as JSON with status, address, ports[].state/service/product/version). It also covers latency, timeout, permissions, and the single-target constraint. For an agent to call this tool correctly, nothing essential is omitted.

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% for both parameters, and the schema already documents both fields including the CIDR limitation and default. The description adds value by providing a concrete example, reiterating the default range behavior, and clarifying the exact serialization of port_range. This enhances the schema rather than merely repeating 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 verb+resource: 'Nmap port scan against a single host from the Netmon server.' It names the wrapped endpoint (POST /api/getPortscanInfo) and clarifies the scope (single IP/hostname only). This clearly distinguishes it from sibling network tools like ping, traceroute, or arp_lookup without ambiguity.

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 clearly indicates when to use the tool: for port scanning a single host from Netmon's perspective, and it explicitly states the constraint that CIDR or ranges are not accepted. However, it does not explicitly name alternative tools or conditions when another tool would be preferred, leaving the 'when-not-to-use' guidance implicit rather than direct.

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/idempotent/destructive annotations, the description discloses partial-result behavior through `skipped`, explains that syslog/eventlog use unindexed substring scans that may time out, and notes server-side tag-scope permission filtering. This gives the agent a realistic model of failure and partial success without contradicting 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 dense but efficient: the core purpose is front-loaded, the parameter list is compact, and the behavioral caveats are organized logically. Every sentence contributes distinct information, and the example earns its place by showing realistic usage.

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 output schema, the description appropriately explains the return shape ({total, samples}), the `skipped` mechanism, authentication/tag-scope behavior, and the timeout fallback. For a tool with four parameters, five stream types, and no structured return schema, 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 covers all parameters at 100%, but the description adds operational meaning: `per_stream` caps samples while `total` remains complete, `hours` affects timeout risk on unindexed scans, and `streams` controls fan-out. The concrete example also demonstrates how the parameters combine, going well 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 action and resource: 'Find every mention of a specific IP across Netmon's log and telemetry streams,' then enumerates the five concrete streams. This distinguishes search_ip from the many single-stream siblings like syslog_search, eve_search, and netflow_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 explicitly tells when to use this tool versus alternatives: if high-volume syslog/eventlog scans time out, it directs users to narrow `hours` or use syslog_search/eventlog_search with a device_id. It also explains how to narrow the fan-out with the `streams` parameter, giving clear selection 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 indicate readOnly, openWorld, idempotent, non-destructive. The description adds context about the blocking behavior (up to 60 seconds) and notes the callback wrapper, which is important for an agent to avoid timeout. It also mentions the permission requirement (write_devices), adding valuable behavioral context 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 concise with two sentences, front-loading the core purpose and then providing essential usage details. Every sentence adds value: purpose, endpoint, permissions, blocking behavior, config specifics, and return format. No 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 tool with a nested object parameter and no output schema, the description sufficiently covers all necessary details: config structure for both versions, return type, and blocking behavior. The schema already covers parameter descriptions, so the description completes the picture.

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 schema already documents both parameters. The description does not add much beyond what the schema provides, except for clarifying the return shape and emphasizing the need for valid configuration. This aligns with the baseline of 3 when schema covers everything.

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 ('Probe a device for SNMP reachability'), identifies the underlying endpoint, and mentions the wrapper binary. It clearly differentiates from siblings like ping and traceroute by focusing on SNMP reachability.

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 explains when to use (to test SNMP reachability) and provides clear configuration guidance for v1/v2 vs v3. It does not explicitly mention alternatives, but the sibling list includes similar network diagnostics (ping, snmp_walk), and the description is clear enough that an agent can infer when to choose this 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 set readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds valuable behavioral context beyond that: it says the call is a 'cheap single-row read', states the return type ('raw walk row including device_id and the captured OID payload'), and defines the meaning of an empty result ('device has never been walked'). It also discloses the lack of a freshness timestamp, which is a real operational trap for an agent. These are genuine behavioral features not already in annotations.

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

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

Five sentences, each earning its place: state the resource, label it cheap, give preferred alternative, describe the return and the empty case, and show an example. No fluff, and the crucial distinction from snmp_walk_run is front-loaded. Formatting is clear and 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?

For a tool with one parameter, no output schema, and complete safety annotations, the description covers everything a agent needs: what is fetched, where it is stored (tools_walks), the API path, the required permission, how to decide between it and snmp_walk_run, the meaning of an empty result, and the freshness limitation. There is no missing information for a correct call decision.

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% and the only parameter, device_id, is already well-described ('Device id to look up the most recent stored walk for'). The description adds an example call (snmp_walk_last({device_id: 42})) but does not add meaning beyond that. Baseline 3 is appropriate because the schema already carries the semantics and the description adds marginal color.

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 precise verb and resource: 'Fetch the most recent stored SNMP walk for a device'. It names the cache table (tools_walks), the wrapped HTTP endpoint, and the permission required. It explicitly distinguishes itself from the sibling tool snmp_walk_run ('Always try this first', 'Only fall back to snmp_walk_run'), so an agent can immediately tell them apart.

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 guidance: always call this first for an SNMP walk, fall back to snmp_walk_run only if the cached row is missing or stale. It even explains how to assess staleness given the controller does not stamp a freshness header. This is a textbook example of when/alternatives guidance with no ambiguity.

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 that the operation is 'SLOW and SIDE-EFFECTING,' details the 1200s timeout, mentions the server-side writeback to the tools_walks table, and warns that the writeback may complete even if the HTTP response stalls. This goes well beyond the annotations (readOnlyHint false, idempotentHint true) by adding concrete behavioral context. 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 dense but every sentence serves a purpose: it front-loads the core purpose, immediately warns about slowness and side effects, gives usage guidance, explains timeout behavior, and provides an example. It is well-structured and not verbose given the critical warnings 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 tool with no output schema and significant behavioral caveats, the description covers all essentials: what it does, when to use it, side effects, timeout, retry policy, and an example. It also clarifies that the result is stored in tools_walks table, so the agent knows to retrieve it via snmp_walk_last. 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 already provides a full description for device_id ('Device id to walk. Server resolves SNMP credentials from the device row.'), so the tool description adds little beyond an example call. Since schema coverage is 100%, the baseline is 3; the example is helpful but does not introduce new semantic 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?

Description states a clear verb+resource: 'Trigger a FRESH SNMP walk against a device.' It also mentions the exact endpoint wrapper (POST /api/getSNMPWalkInfo/{deviceId}) and explicitly differentiates from the sibling snmp_walk_last by saying 'Always try snmp_walk_last first.' This leaves no ambiguity about what the tool does and how it differs from its nearest sibling.

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 when-to-use vs. alternative: 'Always try snmp_walk_last first; only call this when the cached walk is missing or known to be stale.' It also gives retry guidance on timeout, telling the agent not to retry without checking snmp_walk_last. This is textbook 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 convey read-only and non-destructive behavior, but the description adds substantial context beyond them: client-side filtering, no server-side cap on the upstream endpoint, automatic passthrough of new columns, and no row reshaping. It even warns against fetching unbounded history, which is actionable behavioral guidance.

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 well organized: purpose, row shape, usage context, filter semantics, permission, and example. Every sentence provides operational value, and the core answer to 'what does this do' comes first.

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 output schema, the description compensates by describing the row shape, typical fields, ordering, dynamic column behavior, and the fact that rows are passed through unmodified. It also covers permission and gives a concrete invocation example, so an agent has enough context to call 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 input schema already documents ranges and defaults for both parameters, so the baseline is 3. The description adds meaningful extra context by noting the filters are client-side, explaining that the upstream returns the full history with no cap, and recommending narrowing with hours to avoid unbounded fetches. This goes beyond the schema's static 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 clearly states the tool returns recent WAN speedtest results ordered by timestamp, answers a specific user question about internet health, and maps to a concrete endpoint. It also distinguishes itself from ping/traceroute/netflow by naming the exact scenario (WAN throughput trends) where it applies.

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 it versus alternatives: it is lower priority than ping/traceroute/netflow for general 'internet slow' investigations, but the right tool when the user asks about WAN throughput trends or recent speedtest runs. This gives the agent a clear selection rule.

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 annotations, the description discloses critical behavior: for message fields, device_id is required and server rejects fleet-wide pivots, scans are sequential and ~37x costlier, and limits like 10s timeout are exposed. It also explains how to interpret results and common errors, providing deep behavioral insight.

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 detailed and organized with clear sections, but it is relatively long. However, every section adds value—from usage, to parameter details, to error handling—and is front-loaded with the most important context. Slightly verbose but justified for the 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, the description is remarkably complete: it covers purpose, parameters, constraints, performance implications, result interpretation, and error handling. With no output schema, it explains the output structure, making it fully self-contained for correct 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?

The schema already has 100% coverage, but the description enriches it substantially: it categorizes fields into columns vs message fields, explains the difference between devname and source, clarifies window constraints (168h) and error handling, and gives examples of valid parameter combinations. This is far beyond schema basics.

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 purpose: to get top-N value counts for one syslog field over a window, with a concrete example and alternative approach. It distinguishes itself from row-pulling and syslog_search by focusing on aggregated facets, making it clear what this tool uniquely offers.

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 and when not to, including specific scenarios like wide windows versus narrow, and when to use device_id. It also contrasts with pulling rows manually and suggests alternatives for wide scans, making usage context clear.

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 and idempotentHint, and the description adds valuable behavioral facts beyond them: the API requires 'logs' permission, results are tag-scoped server-side, and the response's total reflects the full match count. This materially helps the agent understand access constraints and result semantics.

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-organized: purpose first, then filters, window/limit rules, response-count behavior, and a compact example. Each sentence contributes value and none repeats annotation or schema content unnecessarily.

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 9 parameters, no output schema, and no enums, the description covers all invocation-critical details: parameter meanings, constraints, defaults, pairing rules, and the total-vs-limit behavior. The only notable gap is that it does not outline the shape of the returned records beyond the total count, which would be more critical without any output 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 description coverage is 100%, so the baseline is 3. The description earns a 4 by adding semantics not explicit in the schema: the mutually exclusive relationship between hours and start_time/end_time, the explicit 'all optional' framing, and the concrete example illustrating parameter combination.

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?

States a specific verb and resource ('Search syslog messages from network devices') and differentiates from siblings like eventlog_search and eve_search by naming syslog as the target. The extra detail about wrapping GET /api/syslog/list and being tag-scoped further pins down the scope.

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 clear, actionable usage context: all filters are optional, hours OR start_time+end_time are alternatives, and it advises narrowing the window or adding filters when total exceeds limit. It does not explicitly name sibling tools or state when not to use this tool, so it falls short of the highest bar.

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, idempotentHint=true, and destructiveHint=false. The description adds beyond that: it states the endpoint wrapper (GET /tags), visibility scope ('every tag the caller has visibility to'), expected volume ('O(10s) per install'), and the operational nuance that all tags are visible while scoping is enforced through slugs. This is useful behavioral context without contradicting 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 information-dense yet compact: it front-loads the resource, then explains identifiers, scoping, return scope, type semantics, permissions, and a concrete example flow. 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 read-only catalog listing with no output schema, the description covers what tags are, which types exist, how the slug relates to other tools, visibility rules, scale expectations, and a working example. There is no meaningful missing context for an agent to select and call this tool.

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 meaningfully expands on both parameters. It details what each `type` value means — 'device' tags are what device_list matches, 'status' tags are system-reserved, 'all' is the default — and clarifies that 'search' is case-insensitive over name or slug. This goes well beyond the bare schema text.

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 clear verb and resource: 'List tag definitions,' and disambiguates what tags are by explaining the stable slug vs. human display name. It also distinguishes this tool from nearby device/network tools by showing it is the tag-definition lookup step feeding device_list, arp_lookup, and alert tag filters.

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 a concrete example flow ('check our routers' → tags_list → device_list) and specifies when type='device' is the relevant filter. It does not explicitly name exclusion cases or alternatives, but the provided example plus slug-vs-display guidance gives an agent clear context for when and how 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?

Despite rich annotations (readOnlyHint, idempotentHint, destructiveHint), the description adds substantial behavioral context: the hardcoded 20-conversation cap, the absence of top_n, how hostnames are resolved, how bytes are pro-rated, and how bps is averaged. This goes far beyond what annotations provide.

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 a clear purpose, usage guidance, output row shape, permission, and examples. Every section adds value and no sentence is redundant.

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 tool is simple (one optional parameter), but the description covers the return shape, row semantics, permissions, example calls, and the key sibling comparison. With no output schema, this is fully sufficient for an agent to call 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?

Although schema coverage is 100%, the description enriches the minutes parameter with crucial semantics: the OVERLAP-matching behavior, pro-rating to the window, and why long lookbacks remain honest. This adds meaning beyond the schema's basic type and default.

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 and resource: it returns top NetFlow conversations over a window, wrapping a specific endpoint and answering a clear question. It distinguishes itself from netflow_search by being the live snapshot tool, so an agent can tell it apart immediately.

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?

Usage guidance is explicit: use for short-window 'right now' inquiries, and use netflow_search for longer windows or filtered top-talkers. It names the alternative and the condition that selects it, leaving nothing to inference.

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 (readOnly, idempotent, non-destructive), the description discloses the exact execution environment (netmon server, not mcpmond), the precise command flags (--mtu -m 10 -q 2 -w 1), the hop limit and truncation behavior, and server-side PTR lookups. It also explains the return format with null fields on timeout. This is a thorough and honest behavioral contract that goes far beyond what annotations convey.

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 information-dense yet well-organized: purpose first, then execution context, command specifics, return shape, and an example. Every sentence contributes meaningful detail—nothing is redundant or filler. The front-loaded purpose and the structured flow make it easy for an agent to parse quickly.

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 network diagnostic tool with no output schema, the description covers all essential aspects: what it does, where it runs, operational limits (10 hops, MTU), behavior on timeout, return field names, and a concrete example. It also notes the permission requirement. An agent has everything needed to invoke it correctly without additional assumptions.

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 parameter 'target' is already documented as an IP or hostname. The description reinforces this and provides a usage example, but it does not add new constraints or disambiguation beyond the schema. It adds mild value by clarifying the target's role in the traceroute context, but the baseline of 3 is appropriate given full schema coverage.

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 'Traceroute to a target from the Netmon server', which is a specific verb, resource, and origin point. It distinguishes itself from network siblings like ping by making clear it traces the path from a fixed server, and it names the underlying API and permission requirement. This is unambiguous and tells an agent exactly what operation is performed.

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 strong contextual cues about when this tool is relevant (network path tracing, MTU discovery, hops up to 10) but it never explicitly contrasts it with alternatives or states when not to use it. It does not name ping or other siblings, nor does it give a 'use this if...' rule, leaving usage inference to the agent. The purpose itself implies route tracing, but explicit guidance is missing.

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