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

Annotations already establish read-only, idempotent, non-destructive behavior. The description adds meaningful behavioral context beyond that by enumerating what Naemon checks — disabled, downtime, soft state, host down, state not subscribed, acknowledged, no contact — and clarifying that recent sent notifications are included. It describes the tool's internal evaluation behavior 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 two sentences with no filler. The first sentence delivers the core behavior and the detailed reason list, and the second provides concrete usage examples. Every clause earns its place and the most important 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?

Given the rich annotations, the 100%-covered schema, and the presence of an output schema, the description is complete: it explains the tool's diagnostic purpose, the types of conclusions it can provide, and example use cases. Nothing essential for an agent to select and invoke the 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?

Schema description coverage is 100%, so the schema already documents all three parameters well. The description adds only indirect value by signaling that the tool can address both host-level and service-level notification questions via the example queries, but it does not add parameter-specific semantics 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 precise verb phrase, 'explain why a host or service did or did not notify,' and names the exact resource and diagnostic scope: settings, contacts, state checks, and recent notifications. It further grounds the purpose with concrete example questions, making it unmistakably distinct from the sibling tools in the 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 gives explicit user-facing scenarios: 'why did I get no alert for web01' and 'who gets notified for Backup on db01.' This clearly communicates when to invoke the tool, though it does not explicitly name alternatives 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=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context: it filters out cancelled and expired downtimes, and the 'running_only' parameter semantics are clarified by the description's example phrasing. It does not detail pagination or exact return shape, but the output schema exists and the added filtering behavior is valuable.

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?

Two sentences with no filler. The first sentence states the core function and exclusions; the second provides concrete example queries. Every word 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 read-only query tool with full schema coverage, an output schema, and safety annotations, the description is nearly complete. It explains what is returned (running and planned downtimes), what is excluded, and how to filter. The only minor gap is that it doesn't explicitly mention the 'limit' parameter's behavior across kinds, but the schema already documents that.

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 six parameters. The description adds value by clarifying the overall filtering intent (e.g., 'by host, service or comment') and by giving a real-world example ('is web01 in maintenance') that maps to the host and running_only parameters. This goes slightly beyond the baseline 3 for 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 states a specific verb ('Find') and resource ('running and planned downtimes of hosts and services'), and explicitly scopes what is excluded ('Cancelled and expired ones are left out'). It also provides concrete example queries ('is web01 in maintenance', 'what is planned for tonight'), which clearly distinguish it from sibling tools like find_hosts or find_services.

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 clear context for when to use the tool via example use cases, and the exclusion of cancelled/expired downtimes implies when it is appropriate. It does not explicitly name alternative tools or state when not to use it, but the examples and scope are sufficient for an agent to select it correctly among siblings.

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 behavioral context beyond the annotations: it yields counts per state and, for unreachable hosts, explicitly names the down hosts they sit behind. This is useful non-obvious behavior that helps the agent interpret results. The only minor gap is that pagination/limit semantics are left to the schema, but that is already documented.

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 sentences with no filler: the first states the core purpose and the counting/ unreachable behavior, the second gives the canonical question forms, and the third routes to the sibling. The description is front-loaded and every clause 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?

For a 7-parameter, all-optional filtering tool with an output schema and safety annotations, the description covers the purpose, typical use cases, and key behavioral quirk (unreachable hosts naming down hosts). Return-value details are handled by the output schema, and parameter details are fully in the input schema. No essential guidance 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?

Schema description coverage is 100%, so every parameter is already meaningfully documented with types, defaults, and exact descriptions (e.g., 'Part of the host name. Empty: any name.'). The tool description adds little to parameter-level semantics beyond the global behavior of counts and unreachable-host handling, which is consistent with the schema. Thus the baseline 3 applies, as the schema does the heavy lifting.

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

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

The description states a specific verb ('Find') and resource ('hosts') and details the filtering dimensions (name, state, container, host group) and the counting behavior. It clearly differentiates from get_host_health by naming the sibling tool and the scenario that selects it, so an agent can distinguish the two 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 gives the intended use cases ('which hosts are down' or 'how many hosts does tenant X have') and names the alternative for a different scenario ('For how one known host is doing, use get_host_health'). This provides clear when/ when-not guidance and a sibling pointer, leaving little 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds useful operational context by noting the tool provides 'what to do about each' finding, but it does not disclose any additional behavioral traits beyond that.

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?

Two sentences with no filler: the first defines the output categories, the second maps natural-language queries to the tool. Every phrase 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?

The description covers the tool's purpose and likely user intents, while the output schema and fully documented parameters fill in return and filter details. It is complete enough for an agent to select this tool, though it could add a note about optional scoping filters.

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 all five parameters are already documented in the schema. The description itself does not mention any parameters, so it adds no semantic value beyond the schema baseline.

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

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

The description identifies a specific resource ('checks that cause noise') and enumerates the three concrete findings it returns: flapping services, top notifiers, and unacknowledged long-standing problems. It also distinguishes this tool from siblings by tying it to cleanup and noise-reduction intents, even without naming alternatives.

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

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

The description gives explicit use cases: 'what is noisy', 'why do we get so many alerts', and 'what should we clean up'. It does not name alternative tools or state when not to use it, so it falls short of full routing 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?

Beyond the readOnly/idempotent/destructive annotations, the description discloses a non-obvious cost behavior: naming each package costs one API request, capped by max_packages_per_host, while the update count is always exact. This is valuable operational context that annotations alone do not 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?

Three tight sentences cover the tool's output, default behavior, a key parameter, and a cost caveat. The most important information is front-loaded and every sentence 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?

With an output schema present, rich annotations, and a description that explains all parameters and behavioral trade-offs, nothing essential is missing for an agent to correctly select and invoke the 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?

The schema documents limit and security_only, but not max_packages_per_host; the description compensates by explaining exactly what max_packages_per_host caps and the cost implication. It also clarifies security_only's semantics beyond the schema description, adding real 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 clearly states that the tool returns hosts with pending updates along with package names and versions, which is specific and distinct from sibling tools like find_hosts or find_downtimes. Even though the verb is implied by the tool name, the resource and result shape are 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 gives clear context on the default behavior (all updates) and how to narrow to security-relevant updates via security_only, which helps the agent decide how to invoke it. It does not explicitly name alternatives, but the scoping and default behavior provide sufficient usage context.

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

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

The annotations already declare readOnlyHint, idempotentHint, openWorldHint, and non-destructive behavior. The description adds that the result is a filtered listing with per-state counts, which is useful behavioral context beyond the annotations. It leaves output-shape details to the output schema, which is acceptable.

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?

Two compact sentences do all the work: the first gives scope and filter/aggregation behavior, the second gives usage examples and the alternative tool. There is no filler or repetition of schema content.

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 an all-optional, read-only, schema-rich tool, the description covers selection, typical queries, and routing to the correct sibling. Return values are handled by the output schema, so nothing essential 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 the schema carries most parameter meaning; the baseline is 3. The description adds value by mapping natural-language use cases to filter dimensions and by stating the aggregate per-state counting behavior, which is not visible in the request 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 action and resource ('Find services') and immediately lists the filter dimensions, plus the per-state count. It distinguishes this list/search tool from the sibling get_service_health, so an agent can tell which call answers a multi-service query.

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 explicit example queries ('which services are critical', 'what runs on host web01', 'which disk checks warn') and a direct alternative: use get_service_health when investigating one known service. This is clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds method transparency (straight-line fit), output specifics (rate of change, date, fit quality), and the no-match behavior for hostname/service (from schema). This goes beyond annotations in a useful way.

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 short and includes a helpful example, but the first sentence is grammatically broken, reducing clarity. It's still concise, but the structure suffers from the malformed opening.

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 fully described schema, rich annotations, and presence of an output schema, the description is almost complete. It explains method, use cases, and outcomes, and doesn't need to restate return values. The only gap is the awkward phrasing, not missing crucial context.

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

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

Schema description coverage is 100%, so parameters are fully documented in the schema. The description contributes little additional parameter meaning beyond the schema, except implying per-metric results. Baseline 3 is appropriate given high 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 conveys a specific predictive purpose: forecasting when a metric crosses a threshold using a straight-line fit, and it mentions that it reports rate of change, date, and fit quality. It is clear enough, though the first sentence is grammatically incomplete and it doesn't explicitly contrast with sibling 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 concrete use cases ("when will the disk on db01 be full" / "what is filling up"), providing clear context for when to use it. It doesn't mention alternatives or exclusions, but the examples sufficiently guide an agent.

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 establish read-only, idempotent, open-world behavior. The description goes further by revealing scoping rules (container plus descendants plus legacy exceptions), the rejection of out-of-scope values, and the conditional presence of 'legal_parent_containers' and 'members'. These are real behavioral details not inferable from annotations or schema.

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-loads the core purpose and packs genuinely necessary operational detail. Some repetition of object types and edge-case explanation could be tightened, but no sentence is 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?

Combined with the rich annotations, full parameter coverage, and the presence of an output schema, this description fully equips an agent to decide when to call the tool and what to expect. It even preempts the common failure mode of calling create with an invisible name.

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 description coverage is 100%, the description adds substantial meaning: container_name defaults to root, and for group object types it represents the intended parent container rather than the object's own container. It also explains the conditional output shape based on whether container_name resolves to a legal parent. This is far beyond the schema's brief 'Target container path'.

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 uses a specific verb ('List') and names a clear resource: allowed elements visible from a given container for a given object_type. It also enumerates the concrete element types and makes the tool's distinct role obvious even among many read-only sibling 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 explicitly says to call this tool BEFORE a create call whenever unsure whether a name is visible, and tells the agent not to guess and retry on error. It also clarifies which object_type values are valid and how container_name behaves for different object types, giving concrete routing guidance.

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

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

The description discloses that the report is computed from recorded state changes rather than live checks, and explains the metrics returned. Since annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, the description adds useful computation/output context beyond the safety profile.

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

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

Three sentences with no filler: purpose, output metrics, and use cases are each given one clear sentence. 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?

The rich input schema, output schema, and annotations together give an agent enough to select and invoke the tool correctly. The main remaining gap is the servicename required/optional inconsistency and the lack of explicit guidance on when to prefer a sibling 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 description coverage is 100%, with each parameter documented, so the main description adds little beyond the example mapping of 'shop01 last month' to hostname/days. There is a notable inconsistency: servicename is described as 'Required' but the schema's required array only lists hostname. This ambiguity prevents a higher score.

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: how available a host or service was over a period, computed from recorded state changes. It further clarifies the report's content (percentage with/without maintenance, time in each state) and gives concrete example queries. It does not explicitly name sibling tools, but the 'over a period' framing separates it from health-style 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 'Use it for...' sentence provides two concrete scenarios: 'how available was shop01 last month' and 'did we keep the SLA'. This gives clear intended use context, though it does not state when not to use the tool or explicitly mention alternative tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral context by detailing what status information is reported, such as whether an export is running or possible, 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 compact and front-loaded, using two sentences to convey purpose, scope, and usage timing. Every phrase contributes meaning, with no filler or repetition of the title.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter, read-only status tool with a rich output schema and safety annotations, the description fully equips an agent: it explains what status facets to expect and when to call. Nothing essential 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 tool has zero parameters, so the schema already covers everything; baseline 4 applies. The description adds useful domain context around configuration export and monitoring states but doesn't need to document parameter behavior.

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 identifies the tool as a status check on the monitoring engine's configuration, enumerating specific aspects: last export time, pending changes, configured-but-unmonitored items, and export running/possible state. This is specific enough to distinguish it from siblings like get_service_config or get_container_tree.

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

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

The description explicitly states when to use the tool: before and after a configuration change. It doesn't name alternatives or exclusions, but the unique purpose makes this less necessary.

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, open-world, and non-destructive behavior. The description adds meaningful behavioral details beyond those annotations: the tool starts at a given container, returns items living directly under it, and falls back to the top-most visible containers if root is inaccessible.

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, begins with the verb and resource, and every clause adds useful information. It avoids repetition of schema or annotation details and stays tightly scoped.

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 has one optional parameter, a defined default behavior, open-world annotations, and an output schema, so the description does not need to explain return values. It fully covers invocation semantics, root handling, direct-children scope, and permission-aware behavior, making it complete for an agent to call 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 0%, and the sole parameter has no schema description. The prose compensates by explaining what 'container_name' means ('starting at the given container') and how to use the default 'root' value, including the permission-aware fallback. This is sufficient guidance for the single parameter.

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 identifies the operation ('Get') and the resource ('organizational structure... containers: tenants, locations, nodes'), and specifies what is included: hosts, host groups, and service groups directly underneath. This distinguishes it from the sibling tools, which target monitoring stats, logs, host info, and other specific lists.

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 clear operational context by explaining the special 'root' value and the fallback behavior when root access is unavailable. It does not explicitly compare this tool to alternatives or state when not to use it, but the usage context is clear enough for an agent to invoke it correctly.

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 the tool read-only, idempotent, and non-destructive. The description adds meaningful behavioral detail: it reports explanatory factors like down parents, downtime, and acknowledgements, and it explains the no-match behavior. This goes beyond the structured annotations without contradicting them.

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

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

The description is two sentences, front-loaded with the core value proposition and followed by concrete example queries. Every clause adds information and there is no redundant or promotional 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 single-host health tool, the description covers the key user intents, the single-host constraint, and the unknown-host behavior. An output schema exists, so the description does not need to enumerate return fields. The context signals and schema fill the remaining details.

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

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

Schema coverage is 100%, with both parameters fully described in the schema. The description adds usage context through examples but does not add new meaning beyond the schema's definitions for hostname and hours. This meets the baseline for fully documented parameters.

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 exactly what the tool does: it provides a single host's state, likely causes of problems, dependent hosts, services by state, and recent changes. The 'one host' scope clearly distinguishes it from broader estate-wide tools, and the example queries make its purpose immediately recognizable.

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

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

Explicit use cases are given: 'how is web01', 'why is web01 down', 'what does switch01 take down with it'. It also notes there is no estate-wide form and that unknown hostnames are answered with tool suggestions. It does not explicitly name alternative sibling tools, but the single-host framing and examples provide clear context.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds valuable context: that a non-matching hostname yields pointers to discovery tools, which is a behavioral nuance not captured in annotations. No contradiction.

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

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

The description is a single, dense sentence that front-loads the core purpose and usage context. Every clause serves a purpose—no filler, no redundancy. It efficiently conveys both what and when.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (2 params, output schema present, safe annotations), the description covers the essential points: what it returns, when to use it, and behavior on unknown host. Minor gaps like pagination or result format are covered by the output schema. No critical information 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 both parameters are documented in the schema. The description adds interpretative context about the tool's output (services, hosts, groups, maps, reports) but doesn't enhance parameter-level meaning beyond what the schema already provides. Baseline of 3 is appropriate.

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

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

The description identifies a specific purpose: retrieving what a host or service carries (its services, dependent hosts, groups, maps, reports) and explicitly frames it as impact analysis for changes. This clearly distinguishes it from the many sibling tools that focus on diagnostics, metrics, or configuration.

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

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

The description states when to use it ('before you disable, delete or take it out of the monitoring') and signals that for unknown hostnames it returns tools to find the correct one. It doesn't name specific alternatives, but provides enough context to guide the agent on appropriate 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 the tool read-only, idempotent, and non-destructive. The description adds behavioral value by explaining that the tool distinguishes root causes from consequences and includes already-acknowledged/downtime items in its overview, which is not visible in annotations or schema.

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?

Two sentences carry the full meaning: the first packs the tool's output categories, the second gives the intended use case. No filler or repetition of schema details; the most important guidance 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 read-only overview tool with an output schema and fully documented optional parameters, the description covers what it does and when to use it. It does not explain how the parameters shape grouping or filtering, but the schema and output schema fill the remaining operational gaps.

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

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

The input schema describes all three parameters (groups, container, hostgroup) with 100% coverage. The description adds no parameter-specific semantics, but with full schema coverage, the baseline 3 is appropriate.

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

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

The description names the tool's function with a specific verb phrase ('What is broken') and enumerates the exact categories it returns: down hosts, unreachable hosts/services, unhandled service problems, and acknowledged/downtime items. This clearly distinguishes it from more targeted siblings like get_host_health or investigate_problem.

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 gives a usage directive: 'Use it first for "what is broken" or "give me an overview".' This establishes when to call it, though it does not name specific alternatives or state when not to use it beyond the 'first' framing.

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 behavior. The description adds valuable context: it reports configuration rather than live state, explains value origins (self-set vs. service template), and clarifies the response is never current state or check results. No contradiction found.

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

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

The description is three focused sentences with no filler and the core purpose is front-loaded. Minor awkward phrasing such as 'follows its servicetemplate for' slightly reduces clarity, but overall the structure is efficient.

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 tool with a rich annotation set, a full parameter schema, and an output schema, the description is nearly complete: it covers scope, provenance, and explicit exclusions. It could be slightly more complete by naming a sibling fallback for state/health questions, but this is a minor gap.

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

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

The input schema fully describes both required parameters with 100% coverage, so the description does not need to compensate. It adds indirect context that reported field names match update_service parameters, but this does not significantly deepen understanding of hostname/servicename semantics 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 clearly states the tool reports a service's configuration and the provenance of each value (set by the service itself vs. followed from its service template). It also explicitly distinguishes this from current state or check results, which differentiates it from health/status sibling 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 tells the agent this is for configuration, not state or check results, and notes that field names align with update_service for potential changes. It gives clear exclusions but does not explicitly name an alternative sibling tool or provide an explicit when-to-use statement.

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 establish read-only, idempotent, and non-destructive behavior. The description adds meaningful context about what the tool returns: state, duration, likely explanations, and state changes, which goes 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?

Two tight sentences carry the entire message: the first defines what the tool reveals, the second gives a concrete invocation scenario. No filler or redundant restatement of the name or 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?

The description, rich parameter schema, and strong annotations together cover the tool's inputs, behavior, and a realistic use case. The output schema exists, and the no-match behavior is documented in the parameter descriptions, so nothing essential is missing for an agent to call this 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%, with hostname, servicename, and hours all documented in the input schema. The description does not need to repeat parameter details and only lightly reinforces the time range via "recent state changes," 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 states the tool's exact scope: it reports on a single service's state, duration, likely cause, and recent changes. The use case "why is Backup on db01 critical" makes the purpose concrete and distinguishes it from estate-wide or host-level 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 a clear usage scenario with a concrete example. It does not explicitly enumerate when to prefer sibling tools like get_host_health or explain_notification, but the single-service focus and example provide enough contextual 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 this read-only, idempotent, and non-destructive. The description adds useful context about what the handover covers (acknowledged items, downtimes, notifications, open issues) but does not disclose any additional behavioral traits or caveats beyond that.

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, front-loads the core purpose with a concrete metaphor ('handover'), and ends with practical usage prompts. Every sentence earns its place with 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 simple, optional-parameter read-only tool with an output schema and full parameter schema coverage, the description covers everything an agent needs to select and invoke it correctly. No prerequisites or additional context seem 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 provides 100% coverage for the single 'hours' parameter, including its range and meaning. The description only implies a time window ('last hours') and does not add any syntax or formatting details beyond what the 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?

The description clearly identifies the tool as a shift handover/report aggregating recent problems, acknowledgements, downtimes, notifications, and open items. It is specific enough to stand apart from sibling tools like find_downtimes or explain_notification, though it does not explicitly name any sibling it is not.

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 explicit use cases: 'what happened during the night shift' and 'give me a handover.' This tells an agent when to invoke it, but it does not mention when not to use it or point to 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, and the description adds meaningful behavioral context on top: it reports the problem's start time, prior duration, co-failing hosts/services, and preceding configuration changes. It also discloses a fallback behavior for a hostname that matches no host, saying the answer includes tools that can find the right one. 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 three sentences, front-loaded with the core purpose and followed by concrete invocation examples. Every sentence earns its place: the first defines the tool's scope, the second clarifies the problem-selection behavior, and the third gives reusable use cases. There is no filler or repetition of schema fields.

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 100% input-schema coverage, an output schema, and strong annotations, the description is sufficient for invocation: it explains what the tool looks at, how it chooses the relevant problem, and when to reach for it. A fully complete definition might explicitly mention response shape or more precise failure-query scenarios, but the output schema covers the return contract.

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 has 100% parameter coverage, so the schema already documents 'hostname', 'servicename', 'days', and 'around_minutes' clearly. The description's main added value is the hostname note about no estate-wide form, which is also partially restated in the schema. This matches the baseline for a fully schema-covered tool.

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 explains what the tool does: it reconstructs what happened around a problem, including first occurrence, prior occurrences, other failing hosts/services, and relevant configuration changes. It does not use a single explicit verb+resource construction inventor but the concrete list of behaviors and two example questions make the purpose specific. It is distinguishable from the sibling list by its problem-history focus, though it does not name a sibling alternative.

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 example questions for when to use the tool: 'why did web01 go down' or 'has Backup on db01 failed before'. It also states that it works on the current problem or the last one if the object is healthy nowainer, which is useful context. It does not give when-not-to-use conditions or name alternatives, so it stops short of a 5.

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 non-destructive behavior. The description adds valuable behavioral details beyond that: results are sorted by name, 'total counts every match' while 'items lists the first', and the limit parameter affects only the returned items. This gives the agent a clear mental model of pagination 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 two sentences, front-loading the action and purpose. The first sentence states what it does and why; the second clarifies pagination and gives examples. No unnecessary words, and every clause 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?

For a simple catalog list tool with an output schema present, the description covers all key aspects: what is listed (kinds), how results are ordered, the meaning of 'total' vs 'items', and the primary use case of finding exact names for other tools. Given the low complexity and available schema, nothing essential 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 description coverage is 100%, so all parameters are already documented. The description adds meaning by explaining how the parameters interact (e.g., 'name' as partial match, 'limit' affecting items but not total) and by framing the purpose of the 'kind' parameter through the listed object types. This goes beyond the schema's simple descriptions.

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

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

The description clearly states the verb ('List'), the resource ('templates, commands, contacts, groups or time periods'), and the specific purpose ('to find the exact name another tool needs'). It also provides concrete example queries, making it easy for an agent to understand what this tool does and when it is appropriate.

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 illustrative use cases ('which service templates exist for disks' and 'what is the host group of tenant X called') that imply when to use this tool for discovery of configuration names. However, it does not explicitly mention alternatives or state when not to use it, leaving some room for ambiguity with sibling tools like find_hosts or find_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 readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior, lowering the bar. The description adds valuable non-obvious behavior: a host with no agent inventory raises instead of returning zero rows, and the OS is auto-detected. This goes beyond what annotations alone 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?

Three short paragraphs each serve a distinct purpose: definition, filtering guidance with alternative tool, and edge-case behavior. There is no filler and no redundant restatement of schema details.

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 an output schema present and annotations covering safety and idempotence, the description covers the key non-obvious edge case, the alternative tool, and filtering guidance. An agent has enough context 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 covers 3 of 4 parameters, and the description adds meaning for name_filter and only_updatable, clarifying that name_filter searches by package name and only_updatable=True returns outdated packages. This compensates for the schema not documenting only_updatable.

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 resource and scope: software installed on a host from the openITCOCKPIT agent's inventory, with OS auto-detection. It also explicitly differentiates itself from find_pending_updates, which is for estate-wide updates.

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 clear guidance on when to use this tool: per-host package inventory with optional name_filter or only_updatable filters. It explicitly names the alternative tool for estate-wide update scenarios, and the schema reinforces that this tool has no estate-wide form.

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