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

The annotations already communicate that this is a non-read-only, idempotent, non-destructive operation. The description adds no behavioral detail beyond restating the action and does not clarify what acknowledgement changes about the alert state or how until_clear interacts with that state.

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 declarative sentence with no filler and the key action and resource are front-loaded. It is compact and readable, though slightly under-specified given the close sibling tools and richer operation semantics.

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 mutating alert operation, the description lacks operational context: when acknowledgement is appropriate, what side effects it has, and how it differs from unmuting. The schema and annotations cover parameters and safety, but not the situational guidance an agent needs to select this tool confidently among many alert-related siblings.

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 alert_id, note, and until_clear are already documented meaningfully in the input schema. The description adds no parameter-level information, but the schema fully carries that burden, making a baseline score of 3 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 ('Acknowledge') and resource ('an alert in LibreNMS') and identifies how the alert is selected ('by ID'). It is clear and unambiguous, though it does not explicitly differentiate this from sibling tools like alert_unmute.

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 guidance is provided about when to use this tool versus alternatives such as alert_unmute or alerts_get. The description gives no context about whether this is the right choice for muting notifications, resolving an alert, or acknowledging only the current occurrence.

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 only product context ('from LibreNMS') and retrieval semantics, with no additional behavioral details such as not-found behavior or permissions. This is acceptable for a simple read operation.

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?

A single front-loaded sentence communicates the tool's purpose with no filler or redundancy. Every word 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 tool is simple: one required parameter, read-only annotations, and an output schema present. The description is complete enough for an agent to select and invoke it correctly; no important operational detail is missing at this level of complexity.

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 documents alert_id with a description and 100% coverage. The description's 'by ID' simply restates the parameter concept without adding format details, minimum semantics, or any meaning beyond what the schema provides. Baseline 3 applies.

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

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

The description uses a specific verb ('Get'), a specific resource ('a specific alert'), and the retrieval criterion ('by ID'). It clearly distinguishes this from sibling list tools like alerts_get and from alert_rule_get, which targets rules rather than alerts.

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

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

The description implies the tool is for retrieving one alert when the caller already knows its ID, but it does not explicitly state when to prefer this over alerts_get or mention any exclusions. The usage context is clear enough by implication, but not explicitly contrasted with 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=false, destructiveHint=true, and idempotentHint=false, but the description adds no behavioral context of its own (no mention of auth needs, side effects, or the non-idempotent nature). The one useful warning about omitting rule_id lives in the schema, not the description. 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?

A single front-loaded sentence with zero waste. It is arguably under-specified rather than padded, which is penalized under completeness rather than here.

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?

An output schema exists and the parameter schema is rich, so the description needn't explain return values. However, for a destructive, non-idempotent mutation tool the one-line description does not add any behavioral or usage context beyond what annotations and schema already convey.

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 payload description is unusually thorough (required/optional fields, enums for severity, an example, and the rule_id caveat). The description text itself contributes nothing beyond the schema, so baseline 3 applies.

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

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

States a specific verb (Add) and resource (alert rule) scoped to LibreNMS, so the operation is unambiguous. It does not explicitly contrast with siblings like alert_rule_edit or alert_rule_delete, though the verb makes the distinction fairly obvious.

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

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

There is no guidance on when to use this tool versus alert_rule_edit or alert_rules_list, and no prerequisites or exclusions are stated. The agent must infer usage from the name alone.

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=false, destructiveHint=true, and idempotentHint=true, which cover the safety profile of a delete operation. The description adds little behavioral context beyond that, such as permanence or cascading effects, but it does not contradict 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 a single sentence that delivers the action, resource, scope, and identifier requirement with no filler. It is appropriately minimal for a one-parameter delete 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?

For a simple delete operation with one required parameter, destructive/idempotent annotations, and an output schema, the description provides all necessary orientation. An agent understands what to delete and how to identify the target.

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 rule_id is already documented as 'Alert rule ID to delete.' The description reinforces this by saying 'by ID' but adds no new semantic 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 uses the specific verb 'Delete' with a clear resource 'alert rule' and identifies the lookup key 'by ID.' This makes the operation unambiguous and distinguishes it from sibling tools like alert_rule_get, alert_rule_add, and alert_rule_edit.

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 implies when to use the tool: when an alert rule needs to be deleted and its ID is known. It does not explicitly mention alternatives or when-not-to-use conditions, but no sibling tool performs alert rule deletion, so the context is sufficient for correct 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 declare readOnlyHint=false, idempotentHint=true, and destructiveHint=true, so the safety profile is known. The description adds nothing beyond that — no mention of what a destructive edit overwrites, no auth/permission requirement, no idempotency explanation backing the annotation.

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?

A single front-loaded sentence with zero filler. It is efficiently sized, though the extreme brevity is under-specification rather than ideal economy.

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?

Output schema and full parameter coverage remove the need to explain returns or fields, and annotations carry the safety profile. The remaining gap is routing among the many alert_rule/alert siblings, which the description does not address.

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 payload field documents every rule attribute plus the rule_id requirement in detail. The description adds no parameter meaning of its own, which is the correct baseline of 3 when the schema does all 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?

States a specific verb and resource ("Edit an existing alert rule") and the word "existing" implicitly distinguishes it from the sibling alert_rule_add. It never names the alternatives (alert_rule_add, alert_rule_delete, alert_rule_get) that sit in the same family, so differentiation is implied rather than explicit.

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 no when-to-use, when-not-to-use, or alternative-routing guidance. With three close siblings (alert_rule_add, alert_rule_delete, alert_rule_get) an agent gets no help deciding among them.

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=true, idempotentHint=true, and destructiveHint=false, which covers the safety profile. The description adds no behavioral context beyond restating the read-only nature of the operation, but it does not contradict 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 a single, front-loaded sentence with no wasted words. It conveys the action, target resource, and selection criterion immediately, making 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 simple one-parameter getter with full schema coverage, an output schema, and safety annotations, the description is minimally adequate to invoke the tool correctly. However, it fails to disambiguate from the similarly named alert_get_by_id, leaving a real selection gap in the broader tool 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?

The input schema has 100% parameter description coverage, with rule_id described as 'Alert rule ID' and a minimum of 1. The description's reference to 'by ID' adds no semantic information 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 states a specific verb ('Get'), resource ('details for a specific alert rule'), and selection method ('by ID'). It is unambiguous about what the tool does, though it does not distinguish itself from the sibling tool alert_get_by_id, which appears to overlap in purpose.

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 explicit guidance is given about when to use this tool versus alternatives such as alert_rules_list, alerts_get, or alert_get_by_id. The phrase 'by ID' implies the caller needs a rule ID, but the description does not state when this tool is preferred or when another tool should be used.

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 without the description. The description adds only the source system name; it omits pagination behavior and the fact that results are capped by default, which matters for a 'list all' claim.

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?

A single short sentence with the verb and resource front-loaded and no wasted words. It is efficient, though arguably under-specified rather than truly concise.

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 full annotation coverage, a complete input schema, and an output schema that documents return shape, the description is minimally sufficient. It leaves the agent without any routing guidance among the numerous sibling list tools, which is the main 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?

Schema description coverage is 100% with only two pagination parameters fully documented in the schema, so the baseline of 3 applies. The description adds no parameter context and its wording 'all alert rules' sits slightly at odds with the default limit of 100.

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 (list) and resource (alert rules) with source (LibreNMS), so an agent knows it enumerates alert rules. It does not explicitly distinguish itself from alert_rule_get, which retrieves a single rule, though 'List all' vs. singular siblings implies the distinction.

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 guidance, prerequisites, or alternatives are given. Nothing tells the agent to prefer alert_rule_get when a specific rule ID is known, nor which of the many sibling list tools is appropriate for a given question.

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, and the description is consistent with them. The description adds little beyond 'optional filters,' but since the annotations cover the safety profile, this 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?

The description is a single, front-loaded sentence with no filler or unnecessary detail. It is concise and easy to parse, though it could have included a bit more value without becoming 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?

Given the simple read-only nature, the rich annotations, and the output schema, the description is sufficient for basic invocation. It does not mention pagination or how to fetch a single alert, but those are covered by schema defaults and the sibling naming convention.

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 provides 100% coverage with descriptions for all six parameters, including defaults and valid values. The description only refers generically to 'optional filters,' so it adds no parameter-level meaning 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 uses a specific verb ('Get') and a clear resource ('alerts from LibreNMS'), and mentions optional filters, which conveys a list/query operation. It does not explicitly differentiate from alert_get_by_id, but the plural scope makes the distinction reasonably clear.

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

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

No guidance is given about when to use this tool versus alternatives like alert_get_by_id, alert_acknowledge, or alert_rules_list. The phrase 'optional filters' hints at flexibility but does not state conditions or scenarios.

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=false, idempotentHint=false, and destructiveHint=false, and the description adds nothing beyond them. It does not warn that repeated calls create duplicate templates (the non-idempotent consequence), nor note any permission requirements. The valuable behavioral notes (test-data rendering, omitting template_id) live in the schema, not the description.

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?

A single front-loaded sentence with zero filler, which is efficient. It is arguably too terse for a mutation tool, but nothing in it is wasted.

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?

An output schema exists, so return values need not be explained, and the schema itself carries rich field-level detail. However, for a create/mutation operation the description omits routing guidance versus alert_template_edit and any idempotency warning, leaving a visible 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?

Schema description coverage is 100%, so the baseline is 3. The single 'payload' parameter is exhaustively documented in the schema, including required fields, an example, and the template_id gotcha; the description adds no additional parameter 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?

States a specific verb ('Create') and resource ('alert template') with the target system (LibreNMS), so the operation is unambiguous. It does not, however, differentiate itself in text from siblings like alert_template_edit or alert_template_get, relying on the name alone.

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 offers no when-to-use guidance, no prerequisites, and no mention of the sibling alert_template_edit for modifying existing templates. An agent must infer the create-vs-edit boundary purely from the tool name.

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=false, idempotentHint=true, and destructiveHint=true, covering the safety profile. The description itself adds nothing beyond that — it does not mention the full-template-replacement behavior or the refusal when template_id is missing (those details live only in the 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?

A single short, front-loaded sentence with no waste. It is efficient, though its brevity borders on under-specification rather than true conciseness.

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?

An output schema exists so return values need not be described, and the schema documents destructive replacement semantics. However, for a destructive mutation the description contributes essentially nothing on its own, leaving it minimally adequate.

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 single nested payload object is thoroughly documented with all required fields. The description adds no parameter detail of its own, so the baseline 3 applies since the schema does all 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?

States a specific verb ("Edit") and resource ("alert template") scoped to "existing" templates in LibreNMS. The word "existing" implicitly distinguishes it from the sibling alert_template_create, though it does not name the sibling explicitly.

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 no guidance on when to use this tool versus alert_template_create or alert_template_get. There is no mention of prerequisites (e.g., that the template must already exist) or conditions that would select an alternative.

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, which fully cover the safety profile. The description's 'Get' phrasing aligns with these annotations, and the presence of an output schema removes the need to describe return values. No additional behavioral disclosure is needed.

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?

A single, concise sentence that contains only essential information: the action, the resource, and the selection criterion. No filler or redundancy.

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

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

For a one-parameter read-only tool with a complete input schema, an output schema, and safety annotations, the description covers everything needed for correct invocation. Nothing important 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%: template_id is documented with type, minimum, and a description. The tool description adds no extra parameter-level meaning beyond what the schema already provides, so baseline 3 applies.

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

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

The description states a specific verb ('Get'), a clear resource ('specific alert template from LibreNMS'), and the access method ('by ID'). It clearly distinguishes from list- and mutation-oriented sibling tools like alert_templates_list, alert_template_create, and alert_template_edit.

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 implies the tool is for retrieving one known template by ID, which is enough for a simple getter. However, it does not explicitly mention when not to use it or point to alternatives such as alert_templates_list for listing all templates.

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 fully covered by structured data. The description adds essentially nothing beyond that: no pagination behavior, no result-size expectations, no indication of how templates are ordered or whether the list is filtered by anything.

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?

A single short sentence with zero filler and the resource front-loaded. It is efficient, though the brevity is a consequence of under-specification rather than disciplined editing.

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?

An output schema exists, so return-value documentation is not required, and the annotations cover safety. What remains missing is pagination guidance for a list endpoint (interaction of limit/offset, whether the full list is large), which is the main thing an agent needs to call this 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 both limit and offset are already documented in the schema, making the baseline 3 appropriate. The description adds no extra meaning such as default page size behavior or whether large limits are expensive.

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 clear verb and resource ('List all alert templates') and names the source system (LibreNMS), so the agent knows what it does. However, it does nothing to distinguish this from sibling tools like alert_template_get, alert_template_create, or alert_template_edit, leaving sibling selection to inference.

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?

There is no when-to-use guidance, no mention of when a single-template lookup (alert_template_get) would be preferable, and no prerequisites or exclusions. The agent gets a purpose statement but no routing logic.

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=false, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds nothing beyond the schema about edge-case behavior (e.g., unmuting an already-unmuted alert), but with annotations present the bar is lower and there is 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?

A single nine-word sentence that front-loads the verb and resource and contains zero filler. Every word 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 single-parameter mutation with annotations and an output schema, the description is nearly sufficient. However, the large sibling list contains alert_acknowledge, a closely related operation, and the description offers no contrast to help an agent decide between acknowledging and unmuting an alert.

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% — alert_id is already fully documented with type, minimum value, and a description. The tool description merely repeats 'by ID' and adds no extra meaning such as where to source the ID or how it maps to LibreNMS alert identifiers. 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 uses a specific verb ('unmute') with a clear resource ('alert'), system ('LibreNMS'), and method ('by ID'). It distinguishes itself from siblings such as alert_get_by_id, alerts_get, and alert_acknowledge — an agent can tell this is the inverse operation without opening any 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 no guidance on when to use this tool versus alert_acknowledge or alerts_get, and no prerequisites are stated (e.g., the alert must currently be muted, or that the ID typically comes from alerts_get). Usage is only implied by the verb, which is not enough for reliable tool 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 declare readOnly, idempotent, and non-destructive, so the safety profile is covered. The description adds nothing beyond that — no mention of pagination behavior, result limits, or the dependency between query and device fields.

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?

A single short sentence with zero waste and the key facts front-loaded. It is efficient, though arguably too sparse for the tool's behavioral quirks.

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 full schema description coverage, the description need not restate return values. However, for a search tool with a non-obvious query/device dependency, the description leaves everything to structured fields and offers no orienting 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 the query formats (IPv4, MAC, CIDR, "all") and the device coupling are fully documented in the schema. The description adds no parameter meaning beyond that, which is the baseline 3 case.

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 (Retrieve) and resource (ARP entries) and identifies the source system (LibreNMS). It does not differentiate itself from nearby siblings like fdb_lookup, ports_search_mac, or device_fdb, which an agent may consider for similar lookups.

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?

There is no guidance on when to use this tool versus the many other lookup/search siblings. The only usage constraint (query "all" requires device) lives in the schema, not the 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?

The description simply restates the operation without adding behavioral details. Annotations already convey readOnlyHint=false, idempotentHint=true, and destructiveHint=true, but the description does not explain side effects, which fields are overwritten, or any permission or rate-limit considerations.

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?

A single, front-loaded sentence with no filler. Every element contributes to the agent's understanding of the tool's purpose.

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

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

For a simple two-parameter edit with full schema coverage and an output schema, the description identifies the resource, system, and identifier. The schema and annotations carry most behavioral and safety context, though adding usage guidance would make it fully complete.

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

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

Schema description coverage is 100%, with bgp_id and payload both described in the input schema. The description adds no extra parameter semantics beyond restating the operation target.

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 ('Edit'), a clear resource ('BGP session'), and the lookup mechanism ('by ID'). It is immediately distinguishable from sibling tools such as bgp_session_get and bgp_sessions.

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

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

Provides no guidance on when to use this tool versus alternatives, such as when to prefer bgp_session_get for retrieval or how this relates to other BGP tools. The intended context must be inferred solely from the verb 'Edit' and the sibling tool names.

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, covering the safety profile. The description adds no additional behavioral context beyond the ID-based lookup, which is already present in the schema's parameter description.

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?

One short sentence with no filler, front-loading the action and resource. Every word contributes to meaning.

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 1-parameter read operation with annotations covering safety and an output schema present, the description is minimally sufficient. It does not explain error behavior or prerequisites, but these are not critical for a straightforward get-by-ID 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% and the sole parameter bgp_id is described with a type, minimum, and description. The description's 'by ID' phrase merely restates the parameter's purpose, adding no additional 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 uses a specific verb ('Get') and resource ('BGP session from LibreNMS') and identifies the retrieval mode ('by ID'). It is clear enough to distinguish from sibling tools like bgp_sessions or bgp_session_edit, though it does not name them explicitly.

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 guidance is given on when to use this tool versus alternatives such as bgp_sessions for listing sessions or bgp_session_edit for modifications. The 'by ID' phrase weakly implies use when an ID is known, but there is no explicit context or exclusion.

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, so the safety profile is covered structurally. The description adds nothing behavioral beyond that — no mention of pagination behavior, default result size, or what happens with zero matches, so it earns little credit.

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?

A single front-loaded sentence with zero waste. It is efficient, though the brevity borders on under-specification rather than tight, purposeful concision.

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 full schema coverage, the return shape and parameters are covered elsewhere, so the description needn't repeat them. However, for an 11-parameter listing tool it should at least hint at filter combination behavior or pagination defaults, which it omits.

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 11 parameters (including filter semantics like SQL LIKE for bgp_descr and family 4/6 for bgp_family) are already documented in the schema. The description's generic 'optional filters' adds no meaning beyond it; baseline 3 applies.

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

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

States a specific verb and resource ('List BGP sessions from LibreNMS') plus the scope qualifier 'with optional filters'. This distinguishes it from siblings like bgp_session_get and bgp_session_edit by implication (plural list vs. single fetch vs. edit), but no sibling is named explicitly.

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?

Only says 'with optional filters' — it never says when to use this list tool versus bgp_session_get or bgp_session_edit, nor any exclusions. Usage is barely implied, with no routing guidance for an agent choosing among BGP 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 indicate readOnlyHint=false and destructiveHint=true. The description adds the 'create or update' upsert behavior, but this is already evident from the tool name. It does not disclose side effects, which fields are overwritten, permission requirements, or consequences of providing/omitting bill_id. The description provides no meaningful behavioral insight beyond the annotations and name.

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 eight-word sentence with no filler, making it concise and front-loaded. However, given the nested payload schema and the number of sibling tools, this is arguably too terse to be appropriately sized. It communicates the basic operation but misses the opportunity to add scoping or usage context.

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 a rich input schema and the presence of an output schema, the description alone is incomplete for a tool with dual create/update modes and conditional fields. It fails to explain when each mode applies, how bill_id routes to update, or how this tool fits among the bill-related siblings. The schema compensates for parameter details, but usage context remains unresolved.

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 the payload field description detailing bill_id, bill_name, ports, bill_type, and conditional quota/cdr fields. The tool description itself contains zero parameter information, so it neither enhances nor harms what the schema already provides. This fits 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 operation, 'Create or update', and a specific resource, 'a bill in LibreNMS'. This clearly identifies the tool's purpose and separates it from sibling read/delete tools like bill_get and bill_delete. However, it adds minimal detail beyond the title and doesn't list any bill fields, so it is clear but not highly informative.

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?

There is no guidance on when to use this tool versus alternatives, no exclusions, and no mention of prerequisites. The description does not explain that bill_id is required for updates or that bill_name/ports are required for creation. The agent must infer usage entirely from the input schema and sibling names.

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 destructiveHint=true, readOnlyHint=false, and idempotentHint=true. The description does not contradict these but also adds no behavioral detail 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 a single, efficient sentence with no filler or redundant phrasing. It states the essential information upfront and earns its place entirely.

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 one-parameter destructive operation with complete annotations and an output schema, the description covers what is needed to select and invoke the tool correctly. No significant context is missing.

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

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

The input schema fully documents bill_id with type, minimum, requirement, and a description. The description's phrase 'by ID' simply echoes the schema's 'Bill ID to delete' without adding extra 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?

The description clearly states the action ('Delete'), the resource ('a bill'), and the identifying mechanism ('by ID'). This strongly distinguishes it from siblings like bill_get, bill_create_or_update, and bills_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 makes the primary use case obvious: deleting a specific bill by ID. However, it provides no explicit guidance on when not to use this tool, nor does it reference any alternative such as bill_create_or_update for modifying a bill.

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, which fully covers the safety profile. The description adds no extra behavioral context beyond the obvious read operation, so it neither contradicts nor significantly enriches 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 a single, front-loaded sentence with no filler. Every word contributes to identifying the action, resource, and lookup key.

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 simple two-parameter schema, rich annotations, and the presence of an output schema, the description is complete enough for an agent to correctly invoke the tool. No critical behavioral or parameter context 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 bill_id and period. The description adds no parameter-level detail beyond 'by ID', which matches the schema. Baseline 3 is appropriate since the schema carries the parameter 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 uses a specific verb ('Get') with a concrete resource ('a specific bill') and the access method ('by ID'). This clearly distinguishes it from sibling tools like bills_list, bill_graph, and bill_delete.

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 implies a clear use case: call this when you have a known bill_id and need a single bill. It does not name alternative tools or exclusions, but the 'by ID' qualifier provides enough contextual guidance for basic 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds that the output is an image, which is useful context, but says nothing about format, size, or rendering behavior 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 short sentences, zero waste, and the image-vs-numbers distinction is front-loaded and immediately actionable.

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, idempotent rendering tool with 100% schema coverage and no output schema, the description covers what the tool returns (an image) and how to get raw numbers instead. Adequate, though it could note the image format or any size limits.

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 graph_type enum is documented in the schema with meanings for 'bits' and 'monthly'. The description adds no parameter detail beyond what the schema already provides, so baseline 3 applies.

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

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

States a specific verb and resource ('Render a bill graph as an image') and names the sibling it is not (bill_graph_data) with the distinguishing criterion (image vs numbers). Clear, though 'bill graph' is somewhat generic given many *_graph 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?

Explicitly routes the agent: use bill_graph for an image, bill_graph_data for the underlying numbers. Names the alternative and the condition that selects it, though it doesn't exclude other graph siblings like bill_history_graph.

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 safety is covered. The description adds nothing beyond them — no note on auth scope, rate limits, or the difference in data returned compared to the other bill graph tools.

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

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

It is a single short sentence with no wasted clauses, so it is not verbose. However, the one sentence is largely filler ('from LibreNMS' is branding), so brevity here reflects under-specification rather than efficient communication.

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?

An output schema exists, so return-value explanation is not required. But for a tool sitting in a cluster of confusable bill-graph siblings, the description provides no disambiguation, which is exactly the context an agent needs to select it correctly.

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

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

Schema description coverage is 100%: bill_id is documented and graph_type carries an enum with meanings ('bits' traffic vs 'monthly' transfer per month). The description adds no parameter meaning of its own, so the baseline 3 is appropriate.

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

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

The description restates the tool's own name and title ('Bill Graph Data' → 'Get bill graph data'), giving no verb-plus-resource detail beyond that. It fails to distinguish itself from near-identical siblings such as bill_graph, bill_history_graph, and bill_history_graph_data, leaving the agent unable to tell which graph is returned.

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?

There is no statement of when to use this tool versus bill_graph or bill_history_graph, and no prerequisites or exclusions are mentioned. With four sibling tools in the same bill/graph family, this silence is a real gap.

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, covering the safety profile. The description adds no behavioral context beyond 'Get,' such as pagination behavior, historical scope, or any other operational trait. It does not contradict the annotations, but it contributes no additional behavioral transparency.

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

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

The description is only one short sentence with no fluff, which is concise. However, it is under-specified for the complexity of the tool and its many sibling tools, so the brevity comes at the cost of useful content. It is not poorly structured, but it does not earn a higher score due to missing contextual information.

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

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

Given that an output schema exists, return values need not be described. However, the description omits any clarifying context about what type of bill history is returned, how pagination works, or how this differs from bill_history_graph and bill_history_graph_data. An agent would struggle to select this tool reliably among the many bill-related siblings.

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 bill_id, limit, and offset all clearly documented in the input schema. The description itself adds no extra parameter meaning, but the schema carries the burden adequately, so the baseline score of 3 is appropriate.

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

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

The description states a clear verb and resource: 'Get bill history from LibreNMS.' It communicates what the tool does at a basic level. However, with siblings like bill_history_graph, bill_history_graph_data, and bill_get, it does not differentiate which variant of history this returns, so it lacks the distinguishing clarity needed for a 5.

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?

There is no guidance about when to use this tool versus alternatives such as bill_history_graph, bill_history_graph_data, or bill_get. The description simply states what it does without any context, exclusions, or conditions for 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 the safety profile (readOnly, idempotent, non-destructive), so the bar is lower. The description adds genuinely useful behavioral context by disclosing that the response is an image rather than structured data — critical information with no output schema. It omits image format and any size/pagination notes.

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 short sentences, zero filler, with the primary capability front-loaded and the alternative-tool hint immediately after. 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?

For a three-required-parameter read tool with full schema coverage and no output schema, the description supplies the missing piece — that the return is an image. It stops short of describing format or how the image is delivered, which would complete 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%, and the schema itself documents bill_id, history_id, and the graph_type enum values with their meanings. The description adds no parameter detail beyond what the schema already provides, so the baseline 3 applies.

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

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

States a specific verb (render), resource (graph for a past billing period), and output form (image) in one sentence. It clearly separates itself from bill_history_graph_data and the other graph siblings by declaring it returns a picture, not numbers.

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 routes the agent to bill_history_graph_data when the underlying numbers are wanted instead of a picture, which is the key decision point between the two siblings. It does not, however, clarify the boundary against bill_graph/bill_graph_data (current vs past period).

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 no behavioral context beyond those annotations—no auth requirements, rate limits, or return characteristics—and does not contradict 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?

It is a single short, front-loaded sentence with no wasted words, so it is concise. However, it is under-specified rather than informative—the sentence essentially restates the name and contributes little.

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 three required parameters and several similarly named siblings, the description provides no scope distinction or routing information. The output schema covers return values, but the selection context an agent needs 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%, with clear parameter documentation including an explanatory enum for graph_type ('bits', 'day', 'hour'). The description adds no parameter meaning, so the baseline 3 applies.

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

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

The description restates the tool name and title ('Get bill history graph data') and adds only 'from LibreNMS,' which is system context rather than a distinguishing purpose. It does not differentiate from near-identical siblings such as bill_graph_data, bill_history_graph, or bill_graph.

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 guidance, prerequisites, or alternatives are provided. Given the sibling set contains confusingly similar names (bill_graph, bill_graph_data, bill_history_graph), the absence of any routing hint leaves the agent without 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, covering the safety profile. The description adds little beyond restating 'optional filters' found in the schema, but it does not contradict the annotations and the read-only behavior is consistent with 'List bills'.

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 sentence that front-loads the verb and resource, followed by the key feature (optional filters). There is no wasted wording, and it is appropriately sized for a simple listing 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?

With a full input schema, output schema, and safety annotations, the description is largely sufficient. It could add guidance on filter interaction or distinctions from related bill tools, but the structured data already covers parameter meanings and return shape, making the definition complete enough 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?

Schema description coverage is 100%, so the schema already documents each parameter (ref, limit, custid, offset, period). The description only says 'optional filters' without adding meaning beyond what the schema provides, so the baseline 3 is appropriate.

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

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

The description uses a specific verb ('List') and resource ('bills from LibreNMS'), clearly conveying a plural listing operation. It distinguishes itself from sibling tools like bill_get or bill_delete by emphasizing listing with optional filters rather than fetching, deleting, or graphing a single bill.

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 implies usage: when you need a list of bills, potentially filtered, use this tool. However, it provides no explicit alternatives or conditions for when not to use it, nor does it reference sibling tools like bill_get for single-bill retrieval or bill_history for historical periods.

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=false, destructiveHint=true, and idempotentHint=false, so the mutation/side-effect profile is covered there. The description adds no extra behavioral context—no mention of prerequisites, duplicate handling, whether discovery runs, or required permissions—so it adds little 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 one short, scannable sentence with no filler. It is slightly redundant with the tool name, but it adds the LibreNMS target. There is no structural waste, though it is brief enough that some would consider it under-specified.

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 nested schema and available annotations, the description is minimally sufficient but not complete. It omits when to choose it over siblings, any behavioral caveats, and what side effects adding a device may have, which are noticeable gaps for a mutation tool with a nested payload.

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%: the payload property documents every field, defaults, and conditional requirements (SNMP v1/v2c vs v3). The prose description adds nothing about parameters, but with full schema coverage the description is not required to compensate. Baseline 3 applies.

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

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

The description states a specific action and resource: 'Add a new device to LibreNMS.' It is clear and unambiguous, and the name/title mirror it. However, it does not explicitly differentiate this from siblings like device_discover or device_update, so it stops short of a 5.

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 guidance is provided about when to use this tool instead of siblings such as device_update, device_delete, or device_discover. The phrase 'Add a new device' implies intent, but there are no alternatives, exclusions, or conditions, leaving the agent to infer 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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safe read nature is covered. The description adds minimal behavioral context—it only names the source system and the fact that it retrieves availability. It doesn't describe output format, timing behavior, or what 'availability' encompasses, but with strong annotations the bar is lower.

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 concise sentence with no wasted words. It is not front-loaded with extra fluff, and it uses a clear verb. Brief but appropriately sized for such a simple 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?

Given the tool only has one parameter, full schema coverage, an output schema, and strong safety annotations, the description covers the essential invocation context. It could mention what the response contains or distinguish from device_outages, but the overall package is reasonably complete for an agent to call it correctly.

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

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

Schema description coverage is 100%, so the schema already documents the single parameter (hostname) adequately. The description adds no semantic detail about what hostname should be (e.g., FQDN vs display name), but the schema carries the weight, so baseline 3 is appropriate.

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

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

The description states a specific verb and resource: 'Get device availability from LibreNMS.' This clearly identifies what the tool does. However, it does not explicitly distinguish itself from sibling tools like device_get or device_outages, so it lacks sibling differentiation.

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 guidance is provided about when to use this tool versus alternatives like device_get, devices_list, or device_outages. The description gives no context about typical use cases, prerequisites, 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 destructiveHint=true, readOnlyHint=false, and idempotentHint=true, so the core safety profile is covered externally. The description adds no further behavioral context such as whether deletion cascades to ports, services, or historical data, but it does not contradict the annotations either.

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, direct sentence that front-loads the action and object. Every word earns its place, and there is no unnecessary elaboration for such a simple one-parameter 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?

Given the tool's low complexity, one required parameter, complete schema coverage, strong annotations, and an existing output schema, the description is sufficient for an agent to make a correct call. A minor gap is the absence of any note about side effects or irreversibility, though destructiveHint partially covers 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?

The input schema already describes the only parameter, hostname, as 'Device hostname to delete', and schema coverage is 100%. The description's phrase 'by hostname' merely restates the schema rather than adding new meaning like format requirements, case sensitivity, or edge-case 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 states a specific verb ('Delete'), a definite resource ('a device from LibreNMS'), and the identifying key ('by hostname'). This makes the operation unmistakable and distinguishes it clearly from sibling delete tools that target other resource types such as rules, locations, or bills.

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 implies the use case: use this tool when you need to remove a device from LibreNMS by hostname. However, it does not explicitly name alternatives, say when not to use it, or mention any prerequisites such as the device needing to exist beforehand.

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 indicate the tool is not read-only and not idempotent, but the description adds no behavioral context beyond that. It does not disclose whether the trigger is asynchronous, what side effects occur (e.g., polling, ARP/SNMP discovery), or what happens for unknown/nonexistent hostnames.

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?

A single, front-loaded sentence with no filler. Every word contributes to stating the action and target, which is the ideal level of brevity for a simple one-parameter operation.

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 a simple one-parameter schema and the presence of an output schema, the description is minimally adequate. However, it lacks context about what rediscovery entails, whether it returns immediately or runs asynchronously, and how errors are handled. These gaps could cause an agent to misuse or misinterpret the call despite the simple input.

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 schema already documents hostname as 'Device hostname or ID'. The tool description adds no extra meaning regarding the parameter's format, resolution, or examples, so the baseline 3 applies.

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

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

The description states a specific action ('trigger') on a specific resource ('device rediscovery') in a named system (LibreNMS). 'Rediscovery' is a distinct operation from sibling tools like device_get or device_update, though it does not explicitly name an 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?

No guidance is given on when to use this tool versus alternatives such as device_update, device_set_maintenance, or device_add. The description does not mention prerequisites, typical scenarios, or exclusions; usage must be inferred entirely from the tool name.

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 (readOnlyHint=false, idempotentHint=false, destructiveHint=false) already establish this as a non-idempotent write that is not destructive. The description adds essentially nothing beyond that — no mention of device-existence requirements, payload limits, side effects, or whether entries are appended. All-false annotations carry the behavioral burden and the description does not enrich 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?

A single front-loaded sentence with zero filler. Every word adds meaning, and the size is proportionate to a two-parameter 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?

Although the output schema covers return values and the input schema documents parameters, the description is incomplete for a mutation tool: it does not state that the hostname must reference an existing device, how this relates to logs_eventlog, or what happens on repeated calls. An agent is left to infer operational 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 the schema documents hostname and payload (including text/type/severity sub-fields). The description contributes no parameter information, so the baseline of 3 is appropriate; a small gap is that the severity range (1-5) direction is not clarified anywhere.

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 ('Add') with a specific resource ('custom event log entry') and target ('a device'). The write polarity clearly separates it from read-oriented siblings like logs_eventlog, though it does not explicitly name an 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?

There is no guidance on when to use this tool versus alternatives, no prerequisites (e.g., the device must already exist), and no conditions or exclusions. The only implied usage is the verb itself, which does not rise to real 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 the tool as read-only, idempotent, and non-destructive. The description adds useful behavioral context by explaining that entries carry the learned port_id and that this is a device-wide perspective of switch connectivity, which is valuable 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?

Two sentences accomplish everything: the first states the action and object, the second explains the key output detail and perspective. No filler or repetition of schema information appears.

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, annotations cover safety, the schema fully documents parameters, and an output schema exists, so the description does not need to explain return values. The only notable gap is lack of explicit routing to sibling tools, but this does not prevent 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?

Schema description coverage is 100%, so the parameters hostname, limit, and offset are already fully documented. The description does not add parameter-specific semantics, but it also does not need to because the schema carries that burden.

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 resource ('forwarding database (learned MAC addresses)') for a device, making the primary purpose clear. It adds 'device-wide view of what is plugged into a switch,' which hints at a distinction from per-port or lookup siblings, though it does not explicitly name them.

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 implies use when you need the device-wide FDB view, and it characterizes the result as learned MACs with port_id. However, it gives no explicit guidance about when to choose this over sibling tools like fdb_lookup or port_fdb, and it does not state exclusions or 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=true, idempotentHint=true, and destructiveHint=false, so the read-only nature is covered. The description adds no further behavioral context such as error handling when a hostname is not found, authentication requirements, or response details, but it does not contradict 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 a single sentence that communicates the action, target, source, and lookup key with no filler. It is front-loaded and easy to parse.

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, idempotent lookup tool with an output schema and safety annotations, the description provides all essential operational context. The agent knows what input to supply and what kind of result to expect; output structure is delegated to the 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?

The input schema already has 100% coverage for the single parameter, including a description of 'Device hostname'. The tool description only repeats the fact that lookup is by hostname and adds no format, validation, or meaning 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 uses a specific verb ('Get'), a clear resource ('device details'), a source ('LibreNMS'), and a lookup key ('by hostname'). This differentiates it from sibling tools like devices_list (enumeration) and device_ports_get (specific port data).

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 phrase 'by hostname' implies this is the tool for fetching a single device's general details, but the description provides no explicit guidance about when not to use it or which sibling alternative to prefer for more specific data (e.g., ports, availability, VLANs). Usage context is implied, not stated.

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, so the safety profile is covered. The description adds that the output is an image, which is useful, but it does not disclose output format, potential errors, or any rendering-specific behavior 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 a single, front-loaded sentence with no wasted words. Every token earns its place: it names the operation, the resource, and the output type.

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 schema carries most parameter context, but there is no output schema and the description does not specify the return format beyond 'image'. It also lacks guidance on how to obtain valid graph_type values, though the schema does reference device_graphs_list.

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 fully documents all seven parameters including defaults and types. The description adds no parameter-level meaning, which is acceptable given the baseline of 3 for high 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 uses a specific verb ('Render'), a clear resource ('device-level graph'), and an explicit output type ('as an image'). This distinguishes it from sibling graph tools like bill_graph and port_graph, and from device_graphs_list which lists graph types rather than rendering them.

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 implies when to use this tool: when a device-level graph image is needed. However, it does not explicitly compare against alternatives such as port_graph, bill_graph, or device_graphs_list, and gives no guidance on 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, covering the safety profile. The description adds that the output is a set of allowed graph_type values, but it does not disclose additional behavioral traits such as error behavior or auth requirements. Given the annotations, this is adequate but not rich.

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, both purposeful: the first states the core action, the second provides usage context and concrete examples. No redundant wording or unnecessary detail.

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 list tool with an output schema, this description is complete. It defines the per-device scope, explains the purpose (graph type discovery), and connects directly to the dependent tool device_graph. 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 input schema documents hostname as 'Device hostname or device ID' with 100% schema description coverage. The description adds no extra meaning to the hostname parameter itself; the examples of graph_type values relate to the output, not the parameter. Baseline 3 applies.

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

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

The description states a specific verb ('List') and resource ('graph types available for a device'), and the second sentence clarifies that it is the discovery tool for valid values of device_graph's graph_type argument. This distinguishes it clearly from device_graph and other graph-related siblings like port_graph.

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 says 'Use this to discover the values accepted by the graph_type argument of device_graph', giving the agent a precise condition for when to call this tool. Concrete examples ('device_icmp_perf', 'device_poller_perf') further aid 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 declare destructiveHint=true and readOnly=false, so the safety profile is covered. The description confirms a mutation ('Add') but adds no context about duplicate names, acknowledged side effects, or authorization requirements; this is adequate but not enriched beyond annotations.

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

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

The description is a single front-loaded sentence with no filler or repetition. It states the action and target immediately, earning a maximum structure 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?

For a complex nested-payload tool, the schema fully documents fields, required conditionals, and examples, and an output schema exists for return values. The only notable gap is lack of explicit usage routing, but the overall package is 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?

Schema description coverage is 100% and the payload property schema contains detailed field descriptions, conditional requirements, and examples. The tool description itself adds no parameter-level meaning, so it relies on the schema, matching the baseline for 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 states a clear verb ('Add') and a specific resource ('device group to LibreNMS'), making the primary action unambiguous. It does not explicitly contrast with sibling tools such as devicegroup_update or devicegroup_delete, so it falls short of full differentiation.

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 no guidance on when to use this tool instead of devicegroup_update, devicegroup_delete, or devicegroup_add_devices. 'Add a new' only weakly implies creation of new groups, so an agent must infer the usage context.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, and destructiveHint=true, so the mutation profile is covered structurally. The description adds nothing on top: it doesn't say whether the add appends to or replaces existing membership, whether it needs specific permissions, or what happens on duplicate device IDs. With annotations present the bar is lower, but zero added context earns a 2.

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?

A single front-loaded sentence with no waste or filler. It is arguably under-specified rather than bloated, so it earns a 4 rather than a 5 for structure.

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?

An output schema exists, so return values needn't be described, and the schema fully documents both parameters. What's missing is behavioral context for a destructive, non-idempotent mutation (append vs replace, duplicate handling), leaving the definition minimally viable.

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%, including the nested payload format {"devices": [1, 2, 3]}, so the schema carries full parameter documentation. The description adds no syntax or format detail beyond it, making the baseline 3 correct.

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: adding devices to a device group in LibreNMS. This distinguishes it from the sibling devicegroup_remove_devices by the verb alone, though it never names or contrasts that sibling explicitly.

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?

There is no when-to-use guidance, no mention of the alternative devicegroup_remove_devices or devicegroup_devices, and no prerequisites. The agent must infer from the name alone 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?

The annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered structurally. The description adds only the fact that lookup is by name, and says nothing about what is destroyed alongside the group (membership mappings, alert bindings) or whether the group must already exist.

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?

A single front-loaded sentence with the verb, resource, source system, and key all up front. No waste, though it is terse enough that there was room for one clarifying clause about side effects.

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 one required parameter, full schema coverage, an output schema, and annotations carrying the destructive/idempotent semantics, the minimum an agent needs to invoke it is present. The gaps are around consequences of the deletion, which a destructive tool would ideally disclose.

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 sole parameter is documented by the schema itself, giving a baseline of 3. The description ('by name') actually narrows the schema, which accepts 'name or ID to delete', introducing a slight ambiguity rather than adding 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?

States a specific verb (Delete) and resource (device group) scoped to LibreNMS, with the lookup key (by name) made explicit. It cleanly separates this from sibling destructive tools like device_delete or location_delete because the resource is named. It stops short of explicitly routing the agent away from adjacent devicegroup_* 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?

No when-to-use guidance, no prerequisites, and no exclusions relative to siblings such as devicegroup_remove_devices or devicegroup_update. The agent gets no signal about whether the group must be empty, what happens to member devices, or when to prefer another tool.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds essentially nothing beyond the annotations – no mention of pagination defaults, the effect of 'full', or rate limits – so it earns little credit for behavioral context.

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

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

One front-loaded sentence with zero waste; the resource and source are stated immediately. It is efficient, though brevity here shades into under-specification.

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?

An output schema exists, so return values need not be explained, and the schema fully documents parameters. However, for a tool sitting among many device/devicegroup siblings, the absence of any disambiguation or usage context leaves a 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?

Schema description coverage is 100% with 4 documented parameters, so the schema carries parameter meaning ('full' toggles complete data vs IDs, limit/offset for pagination). The description adds no syntax or format detail beyond that, which matches the baseline of 3.

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

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

States a specific verb ('List') and resource ('devices in a device group'), which separates it from devices_list and devicegroup_add_devices. It does not explicitly name the sibling it is not, so it stops short of a 5.

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?

There is no guidance on when to use this tool versus devices_list, devicegroup_devices-style siblings, or when the group name vs ID is required. The agent must infer usage entirely from the name.

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 destructiveHint=true, non-idempotent, and non-readOnly, so the safety profile is covered structurally. The description adds nothing beyond that restatement: it does not say whether devices are deleted from LibreNMS or merely unlinked from the group, nor how to recover from a mistaken removal.

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?

A single clean sentence with no filler, front-loading the verb and target. It is concise to the point of being terse, but nothing is wasted.

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?

An output schema exists and annotations carry the safety profile, so return values and risk are covered elsewhere. Missing are usage context and clarification of what removal actually mutates, which matters for a destructive 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 both 'name' and 'payload' documented in the schema including the payload format example. The description contributes no additional parameter meaning, so the baseline 3 applies.

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

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

States a specific verb ('Remove') and resource ('devices from a device group'), which distinguishes it functionally from devicegroup_add_devices and devicegroup_devices. However, it never names or contrasts those siblings explicitly, so the differentiation requires inference.

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 guidance, no prerequisites, and no mention of alternatives such as devicegroup_add_devices or devicegroup_update. The agent is left to infer the context from the name alone.

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 destructiveHint=true, idempotentHint=true, and readOnlyHint=false. The description adds nothing beyond this – it doesn't say what maintenance does to the group, whether existing windows are overwritten, or what 'destructive' means here (e.g., alert suppression). With annotations covering the safety profile, no added context means a low score.

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?

A single, front-loaded sentence with zero waste. It is efficient, though its brevity is part of the definition's overall thinness rather than a deliberate structural choice.

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?

Annotations carry the safety profile and an output schema exists, so return values need no explanation. However, for a destructive mutation on device groups, the description says nothing about the effect of entering maintenance, leaving a noticeable 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?

Schema coverage is 100% and the nested payload schema already documents duration, title, notes, and start with formats and defaults. The description adds no parameter meaning, so the baseline 3 applies.

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

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

States a specific verb+resource ('set maintenance for a device group') and scopes it to device groups, which distinguishes it from the sibling device_set_maintenance. It does not explicitly name that sibling, so it falls short of 5.

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 guidance, no prerequisites, and no mention of the closely related device_set_maintenance or location_set_maintenance alternatives. The agent must infer everything from the tool name.

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, so the safety profile is fully covered by structured data. The description adds nothing beyond that – notably it says 'all' while the schema paginates with a default limit of 100, so it does not disclose result-size 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?

A single short, front-loaded sentence with no redundancy or filler. It is efficient, though so terse that there is essentially nothing left to structure.

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

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

For a simple read-only list tool with full schema coverage and an output schema, the description is minimally viable. The word 'all' conflicts mildly with default limit=100, and no context is given for how this differs from devicegroup_devices.

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% for both limit and offset, so the schema already documents pagination semantics fully. The description adds no syntax, format, or default-value detail, which is the expected baseline 3 when the schema does the heavy lifting.

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

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

States a clear verb and resource ('List all device groups'), which an agent can distinguish from mutation siblings like devicegroup_add or devicegroup_delete. However, it does nothing to separate itself from devicegroup_devices, which lists devices within a group, so the sibling differentiation is incomplete.

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?

There is no when-to-use guidance and no alternatives named. With many list-oriented siblings (port_groups_list, devices_list, location_get), the agent gets no help deciding when this tool is the right one.

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=false, idempotentHint=true, and destructiveHint=true. The description adds no behavioral context beyond what annotations provide, such as what gets destroyed, auth requirements, or side effects. It only restates the action.

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 short sentence that is front-loaded with the verb and resource. There is no wasted text. It is appropriately concise for the amount of information it chooses to 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?

Given that the input schema has full parameter coverage, an output schema exists, and annotations cover the safety profile, the minimal description is nearly sufficient. The only notable gap is the lack of when-to-use guidance relative to siblings, but structured fields compensate well.

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 both parameters and their nested fields. The description adds no parameter semantics or syntax details. A baseline 3 is appropriate when structured fields carry the full parameter burden.

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: 'Update a device group in LibreNMS.' It is clear what the tool does. However, it does not explicitly distinguish itself from siblings like devicegroup_add or devicegroup_delete, so it falls short of a 5.

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 offers no guidance on when to use this tool versus alternatives. It does not mention conditions for updating an existing group, prerequisites, or that devicegroup_add should be used for new groups. Usage is only implied by the name.

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, covering the safety profile. The description adds no additional behavioral context such as pagination behavior or data scope, but it does not contradict 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 a single concise sentence with no filler, front-loading the action and resource. It is easy to scan and fully 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 read-only tool with a complete input schema, an output schema, and safety annotations, the description is nearly sufficient. It is slightly incomplete in that it does not clarify how device_links relates to switching_links, but the output schema likely resolves much of the ambiguity.

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 limit, offset, and hostname are already well documented in the schema. The description's phrase 'specific device' mildly reinforces hostname as the key parameter, but it adds no meaningful semantic value 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 action ('Get'), a resource ('network links'), and a scope ('for a specific device'), which is clear and actionable. However, it does not differentiate from sibling tools like switching_links, which may overlap in meaning, so it falls short of a perfect 5.

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 guidance is provided about when to use this tool versus alternatives such as switching_links, device_ports, or ports_search. The description implies a use case for retrieving links for a device, but it gives no explicit context 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=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the point-in-time scope ('currently') but no additional behavioral detail such as response shape or edge cases, which is acceptable given the annotations and existing output 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 entire description is one focused, front-loaded sentence with no filler or redundant wording. Every word contributes to the tool's purpose.

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 single-parameter status check with a complete input schema, read-only annotations, and an output schema present, the description is sufficiently complete. An agent has enough information to select and invoke it correctly.

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

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

The input schema has 100% description coverage for the single hostname parameter, describing it as 'Device hostname or ID'. The tool description does not add further parameter-level meaning, so the schema already carries the burden and 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 uses a specific verb ('Check') and resource ('device maintenance status'), clearly distinguishing this read-only status query from sibling tools like device_set_maintenance. The phrase 'currently in maintenance mode' makes the tool's exact function immediately understandable.

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

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

The description clearly implies this tool should be used when the agent needs to determine a device's maintenance state, rather than change it. It does not explicitly name an alternative such as device_set_maintenance for toggling maintenance mode, so it stops short of a top score, but the context is clear enough.

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 readOnly, idempotent, and non-destructive behavior. The description adds useful behavioral context: it shows authenticated endpoints per port, includes authentication method, and notes that VLAN assignment is shown only 'where the device reports it'—a meaningful caveat about data availability. 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?

Two concise sentences with no filler. The primary action is front-loaded, and the follow-up sentence adds relevant output details. Every word contributes to understanding.

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 operation with an output schema and well-documented parameters, the description covers what the tool returns and its device scope. It could have explicitly referenced a sibling like nac_list for broader context, but 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%, with all three parameters (hostname, limit, offset) having descriptions. The tool description does not add parameter-specific meaning beyond stating the device scope and output contents, so the baseline of 3 applies.

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

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

The description states a specific verb and resource: 'List network access control (802.1X / MAB) sessions on a device.' It clearly scopes to a single device, distinguishing it from the sibling tool nac_list which likely covers sessions across multiple devices. The added detail about authenticated endpoints, authentication method, and VLAN makes the purpose unmistakable.

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

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

The description clearly indicates this tool is for listing NAC sessions on a specific device, giving the context of when to use it. However, it does not explicitly mention alternatives or when not to use it, such as pointing to nac_list for a global view, so it falls short of full exclusion 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 only the source system (LibreNMS) and offers no additional behavioral context such as pagination or filtering 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 a single, efficient sentence with no wasted words. It is appropriately concise for a simple read-only lookup 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?

For a straightforward read-only query with a required hostname parameter, an output schema, and full annotation coverage, the description is mostly complete. It could be improved by noting how outages are defined or when to prefer this over similar tools, but nothing essential to invoking 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 description coverage is 100%, so the parameters are already documented. The description does not add any meaning beyond the schema, which is acceptable per the baseline 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 and resource: 'Get device outages from LibreNMS.' It is clear about what the tool does, but it does not differentiate this from potentially related sibling tools such as device_availability or alerts_get.

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?

There is no guidance on when to use this tool versus alternatives. No context is given about which scenarios call for device outages compared to other monitoring or alerting tools, and no exclusions are mentioned.

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 no extra behavioral context such as pagination behavior, default limits, or how columns filtering affects results, but it also does not contradict 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 a single compact sentence that leads with the verb and resource. There is no filler or redundant content, making it appropriately sized and front-loaded.

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

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

The schema, annotations, and output schema cover most invocation needs, so a sparse description can be acceptable. However, the existence of a nearly identically named sibling (device_ports_get) and no clarification of scope leaves a material selection gap for the agent.

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

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

Schema description coverage is 100%, with all four parameters documented (hostname, limit, offset, columns). The phrase 'for a device' restates the hostname parameter and adds no additional semantic detail beyond what the schema already 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 clear action ('List') on a specific resource ('ports') scoped to a device from LibreNMS. It is unambiguous in what the tool does, but it does not differentiate from the similarly named sibling device_ports_get or related tools like ports_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?

No guidance is given on when to use this tool versus alternatives. The description does not mention device_ports_get, ports_list, or ports_search, nor any conditions that would select one over the other.

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