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

Annotations already declare read-only, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds two genuinely useful behaviors beyond that: secrets (Wi-Fi keys, passwords, communities) are masked, and a full document can be hundreds of KB, which drives the projection recommendation.

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

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

Three tight sentences with zero filler: identifier form first, projection guidance second, masking caveat last. Everything is front-loaded and each sentence carries a distinct, actionable fact.

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

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

For a two-parameter read tool with full annotation and schema coverage, the description covers identification, payload sizing, and data masking. It doesn't describe the shape of the returned document, but with no output schema and a well-known resource type that is a minor gap rather than a blocker.

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

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

Schema coverage is 100%, so baseline would be 3; the description adds an example _id format and reinforces the projection pattern as comma-separated parameter paths with a concrete instance, which helps an agent construct the call rather than just parse the types.

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

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

States a specific verb and resource ('Read one device') and is explicit that it is by exact `_id`, which cleanly separates it from the sibling list tool acs_devices. The endpoint reference (GET /devices?query=...) further pins down semantics.

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

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

Gives concrete guidance on when to pass `projection` ('unless you really need the full parameter tree') and which identifier form to use (exact _id as shown by acs_devices). It doesn't explicitly say to use acs_devices for listing or searching, but the routing implication 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 declare readOnly/idempotent/non-destructive, so the bar is lower; the description still adds real value by warning that a full device document can be hundreds of KB and by defining the `total` field semantics. Return-shape detail beyond that is thin, but this is a read-only list tool with a low disclosure burden.

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?

Front-loads the purpose, then the operational rule (filter with query, always project), then examples in a compact bullet-like form. The three inline JSON examples are dense but each illustrates a distinct pattern, so little 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?

With five optional parameters, no required fields, an output schema absent, and annotations covering safety, the description supplies the two things an agent most needs: how to filter and the size cost of not projecting. Paging behavior (skip/limit bounds) and sort are left to the schema, which documents them adequately.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters, including query operators and projection syntax. The description's query examples ($regex on _id, $lt on _lastInform, VirtualParameters path) largely restate the schema's own examples, adding only the 'stale devices' framing and the total/skip relationship noted in the schema.

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

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

States a specific verb and resource ('List or search CPE/ONT devices known to the ACS') and even names the underlying endpoint (GET /devices). It does not explicitly contrast itself with the singular sibling acs_device, so an agent must infer the collection-vs-single distinction from the names 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?

Gives actionable operating guidance: use `query` to filter, 'ALWAYS pass a `projection`' to keep rows small, and supplies three concrete query patterns including a stale-device case. It does not name an alternative tool or state when this tool is the wrong choice, so it stops short of full when/when-not routing.

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, non-destructive, closed-world, so safety is covered. The description adds value by enumerating the returned fault fields and the per-device/per-channel scope, which matters since there is no output schema; it doesn't mention paging defaults or result volume, but the schema covers those.

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, front-loaded with what it returns and immediately followed by the routing hint. No filler.

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

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

All optional parameters are fully documented in the schema and the description supplies the missing return-value context (fault fields) since no output schema exists. Only gap is guidance on narrowing large result sets against the other diagnostic 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% and all six parameters are documented with examples and operators, so the description adds nothing beyond it. Baseline 3 per the high-coverage rule.

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 ACS faults') plus the underlying endpoint (GET /faults) and the record contents (code, message, retry count, timestamps). An agent can distinguish it from acs_devices/acs_tasks because faults are framed as failed sessions/provisions, though 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?

'Start here for "why does this ONT not provision"' gives a concrete diagnostic trigger for selecting this tool. It stops short of naming alternatives (e.g. when to use acs_tasks or acs_device instead) or stating 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 readOnly/idempotent/non-destructive, so the safety profile is covered; the description adds real behavioral context by clarifying that results are metadata only and that binary contents cannot be fetched here — a genuine expectation an agent would otherwise have for a firmware listing. It stops short of noting paging defaults or 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?

Two tightly written sentences: identity and endpoint first, returned shape second, scope limitation last. No filler, nothing repeated from the schema.

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

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

With six optional parameters, no output schema, and no required inputs, the description appropriately spends its words on the returned fields and the metadata-only constraint. A note on default/maximum result size or paging would round it out, but that is already partially covered in the schema text.

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 skip/limit/sort/query/projection all documented inline, so the baseline is 3. The description only hints at filterable attributes (filename, fileType, OUI, productClass, version) as returned fields rather than explaining how to filter on them via query/projection.

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 files stored in the ACS") plus the underlying endpoint GET /files and the fields returned (filename, fileType, OUI, productClass, version). The resource is clearly distinct from the device/task/fault/preset siblings, though no sibling is named explicitly for the download-oriented use case it excludes.

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

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

Usage is only implied: the resource name indicates when to reach for it, and "file contents are not downloadable here" excludes one expectation, but there is no explicit when-to-use statement or pointer to an alternative tool for retrieving file contents or firmware.

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 safety behavior is covered structurally. The description adds domain context about what presets contain, but does not describe pagination behavior, default limits, or result shape beyond what the schema implies.

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 that names the operation, the endpoint, and the core domain semantics. There is no wasted text or tangential 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 read-only list tool with complete schema descriptions and clear annotations, the definition gives enough context to understand what is being listed. The remaining gap is sibling differentiation and output/result expectations, but the structured fields cover most of the call mechanics.

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 description adds no parameter-specific detail. Baseline 3 is appropriate: the schema already carries the full burden for skip, sort, limit, query, and projection.

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 and resource ('List presets') and explains what a preset represents (provisions, devices, channel, weight, precondition, events). It is clearer than most sibling listings but does not explicitly contrast itself with acs_provisions or acs_devices.

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 explicit guidance on when to use this tool versus alternatives such as acs_provisions or acs_devices. The '(GET /presets)' endpoint hints at read-only listing, but the description leaves usage context entirely implicit.

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 that this is a safe, read-only, idempotent operation. The description adds genuinely useful behavioral information not captured in annotations: script bodies are returned as stored, and password-like assignments are masked, which tells the agent not to expect real secrets.

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 consists of two tightly written sentences that front-load the core action and then add the key return-value caveat. Every sentence earns its place, with no redundancy.

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

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

For a read-only list tool with full schema coverage and annotations covering safety, the description is largely complete. It explains the masking behavior of returned script bodies, which is the main non-obvious trait, though it could mention that responses are paginated lists whose total is exposed via the result.

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

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

Schema description coverage is 100%, so all five optional parameters (skip, limit, sort, query, projection) are already fully documented in the schema. The description adds no parameter-level meaning beyond that, making the 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 and resource ('List provision scripts') and even names the underlying HTTP endpoint. It is clearly distinct from device-, task-, fault-, file-, and preset-oriented siblings, though it does not explicitly contrast itself with any of 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?

There is no guidance on when to use this tool versus alternatives such as acs_read or the other listing tools. Usage is only implied by the verb 'List' and the resource name, with no exclusions or selection criteria.

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

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

The annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false. The description adds meaningful policy context beyond those annotations: only GET is sent, write methods are refused, and certain paths and flags such as /devices/{id}/tasks and connection_request are blocked. It does not cover authentication, rate limits, or response shape, so it is not fully rich, but it substantially improves 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 front-loaded with the core purpose as an escape hatch, then gives examples, allowed paths, policy restrictions, and the sibling-tool preference. Every sentence carries operational value, and there is no redundant or filler text.

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

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

For a two-parameter raw GET tool with full schema coverage and read-only annotations, the description covers purpose, allowed paths, method restrictions, refusals, and alternatives. Since there is no output schema, it need not explain return values in detail. It could mention authentication or response format, but the essential invocation context is present.

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

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

Schema description coverage is 100%, so the baseline is 3. The description still adds value by enumerating allowed collections for the path parameter and showing concrete path-with-query examples such as /devices?limit=3&projection=_id. It also reinforces that method must be GET, though it does not explain query parameter semantics in depth.

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 gives a specific verb and resource: a raw GET against any readable NBI path, with examples and an explicit allowed-collection list. It also distinguishes the tool from dedicated siblings by calling itself an escape hatch and saying to prefer the acs_* tools. An agent can immediately tell what this tool is for and how it differs from acs_devices, acs_tasks, etc.

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 frames the tool as an escape hatch and says to prefer the dedicated acs_* tools, which directly names the alternatives. It also states which methods and paths are refused by policy, giving clear when-not guidance. This is strong routing guidance rather than implied usage.

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 the description reinforces this correctly rather than contradicting it ('tasks can not be created or deleted here'). It adds genuine operational value with the backlog-means-offline interpretation, but says nothing about pagination behavior or how large the backing collection typically is.

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

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

Three short sentences, front-loaded with the verb and resource, then the diagnostic insight, then the safety scoping. No redundant or filler text.

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 six-parameter, fully documented read-only list tool with no output schema, the description covers purpose, safety, and interpretation. The only real gap is that it does not set expectations about return volume or that paging is needed for large backlogs.

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 paging, sort, query operators, and the projection warning, so the schema carries the parameter burden. The description adds no parameter-level meaning beyond what the schema already 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?

States a specific verb and resource ('List queued ACS tasks') plus the underlying endpoint GET /tasks, and defines what a queued task is (an operation waiting for a device to connect). An agent can immediately distinguish this from acs_devices or acs_faults.

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

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

Gives clear diagnostic context: a growing backlog on one device often signals it is offline or unreachable, which tells the agent when this tool is informative. It lacks an explicit 'use acs_device instead when...' routing statement relative to the sibling read tools, so it stops short of full alternative guidance.

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