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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It describes returned fields but never states that this is a read-only/status operation, nor does it cover auth needs, freshness, rate limits, or error 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?

One compact sentence, front-loaded with the resource and the returned fields. It contains no filler and is appropriately sized for a simple status lookup, though it reads as a terse fragment rather than a fully structured usage statement.

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-device status getter with an output schema, the description adequately covers the return shape. However, with no annotations, 0% schema coverage, and no usage routing, the agent still lacks parameter format guidance and clear conditions for selecting this tool.

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

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

Schema description coverage is 0% and the single required 'device' parameter has no schema description. The description says 'one device' but does not define the identifier format (ID, name, MAC), so it adds little beyond the schema property name.

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 that the tool returns the connection state for one device and enumerates the returned fields (state, port, endpoints, last update time). The purpose and resource are clear, but it does not explicitly differentiate itself from sibling tools such as idm_list_connections or idm_get_activity.

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 choose this tool over sibling status/list tools, no prerequisites, and no exclusions. The phrase 'one device' implies a single-device lookup, but the agent must infer when that is preferable.

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?

No annotations are provided, so the description carries the full burden. The verb 'Describe' implies a read-only operation with no side effects, and the output schema covers return values. However, the description does not explicitly state that it is safe, requires no auth, or has no side effects, leaving a gap in behavioral disclosure.

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 efficiently communicates the purpose and the fields returned.

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

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

Given the tool's simplicity (zero parameters, output schema exists), the description is nearly complete. It states what the tool does and what it returns, but it lacks any usage context or explicit behavioral note, which keeps it from a perfect score.

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

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

The tool takes zero parameters, so there are no parameter semantics to document. Per the rubric, a zero-parameter tool earns a baseline of 4.

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

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

The description states a specific verb and resource ('Describe the gateway') and enumerates the exact fields returned (host, API version, mode, group, device count). This clearly distinguishes it from sibling tools that focus on devices, protocols, streams, 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?

The description implies usage (call it to retrieve gateway information) but offers no explicit when-to-use guidance, no alternatives, and no exclusions. For a zero-parameter info tool the implied usage is somewhat evident, but the description does not actively route the agent against siblings.

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

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

With no annotations, the description carries the full burden and does disclose a non-obvious behavior: rejected writes surface here as 'Command not found: ...'. That is exactly the kind of trait an agent needs to diagnose silently failing writes. It omits other traits such as auth requirements, read-only status, or whether the log is bounded/rotating.

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, purpose front-loaded and the diagnostic behavior immediately after. No filler; 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?

An output schema exists, so return format needn't be explained, and with one optional parameter the description only needs to convey purpose and key behavior — which it does. The remaining gap is the absence of any safety/read-only statement, minor for a log read but not nothing given no annotations.

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?

Only one parameter, 'limit', and the schema already documents it at 100% coverage ('how many recent entries to return'). The description adds no semantics beyond the schema, 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?

States a specific verb and resource: 'Read the gateway's recent activity log.' That is unambiguous and distinct from most siblings (device/stream/parameter lookups). It does not, however, distinguish itself from the similarly named idm_get_history, which an agent could easily confuse it with.

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 a concrete use context: this is the 'real receipt for a write,' implying it should be consulted after a write to confirm the command was accepted. It does not state when not to use it or name an alternative (e.g. idm_get_history), so it stops short of a full routing directive.

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?

With no annotations, the description carries the full burden and does disclose non-obvious traits: the page grows with server access level (140 -> 195 parameters), and fetching has a side effect (marks the device as described, which write tools report back). It omits error/failure behavior and does not restate read-only safety, so not a 5.

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 imperative ('Start here: fetch...') and each subsequent sentence adds a distinct piece of value (page contents, access-level behavior, side effect). Slightly verbose in enumerating page sections, but no wasted 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?

An output schema exists, so return formatting need not be explained, and the description still usefully characterizes what the page contains and how access level changes it. A brief note on failure/not-found behavior 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 both parameters (device, max_bytes) are fully documented in the schema, including the truncation flag. The description adds no parameter-level detail beyond that, 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 concrete verb and resource ('fetch the gateway's own HTML page for a device') and frames its role as the description/discovery layer. It never names the closely-named siblings (idm_get_structure, idm_list_parameters, idm_get_parameters), so an agent must infer the distinction rather than being told it.

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' plus 'how you learn what a device is and what its parameters mean before reading or writing them' gives a clear when-to-use signal relative to the read/write tools. No explicit when-not-to-use or named alternative is provided, so it stops short of a 5.

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

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

No annotations are provided, so the description carries the full burden and does meaningful work: it discloses gateway-side aggregation, that inactive devices still have records ('the gateway keeps their records'), that average intervals are in SECONDS, and that average mode adds 'n' and 'sd' to each returned point. It says nothing about permissions, result-size limits, or error 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?

Front-loaded with the core action, then a compact mode list with aligned labels — efficient and scannable. Minor cost: identifiers like `m` in the scale line are never defined in the prose, so the reader has to infer what a returned point contains.

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 documented, yet the description helpfully hints at the extra `n`/`sd` fields in average mode. Combined with mode selection, units, defaults, and inactive-device support, an agent has enough to call it correctly for a 9-parameter, 4-mode tool; only error and permission behavior are absent.

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 already 100%, so the baseline is 3. The description goes beyond it by defining the mode combinations that tie parameters together (average requires scale; calc collapses the whole record set) and by clarifying the unit of `average`. It adds cross-parameter semantics rather than just restating individual fields.

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 recorded samples of one parameter, aggregated by the gateway.' The four-mode framing (regular/scale/average/calc) makes it unmistakably the historical-samples tool rather than a live-value sibling like idm_get_value or a stream reader like idm_read_stream.

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

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

Explicitly tells the agent how to select behavior: 'Four modes, chosen by which arguments are set,' with each mode's argument combination spelled out (scale → average, calc → single aggregate). It also notes the inactive-device case. No sibling alternatives or when-not conditions are given, so it stops short of 5.

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

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

No annotations are provided, so the description carries the full behavioral burden: 'Read' does correctly convey a read-only, non-destructive operation, and the flattening note describes the output shape. It does not disclose the caching/staleness nuance (fresh=false may return a stored sample rather than a live value), error behavior, or authorization needs — though the schema's `fresh` description partly covers the caching point.

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; the read action and the flattened return shape are stated in the first half. 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?

An output schema exists, so return values need not be re-explained, and all four parameters are fully documented in the schema. However, with no annotations and six-plus closely named siblings, the description is thin on disambiguation, staleness semantics, and failure modes — gaps that matter for a device-query 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%, so baseline is 3; the `names` matching semantics, `prefix` filtering, and `fresh` round-trip cost are all documented in the schema. The description mentions no parameter semantics of its own beyond the output-path naming.

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 current values of a device's parameters') and even sketches the return shape ('flattened to path -> {value, unit}'). It does not, however, distinguish itself from close siblings like idm_list_parameters, idm_get_value, or idm_get_structure, which an agent must disambiguate by 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?

There is no explicit when-to-use guidance, no statement of when to prefer this over idm_list_parameters or idm_get_value, and no prerequisites or exclusions. The only usage-relevant hint (device round-trip cost) is buried 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?

With no annotations, the description carries the full burden and does well: it discloses that layers are returned flattened with a `path`, that a `tcp_port` marks a connectable stream at `<gateway_host>:<tcp_port>`, that nesting can be arbitrary depth, and that new protocol types appear without notice. It stops short of stating read-only/safety or error behavior explicitly, but 'Show' plus the rich structural context covers most of what an agent needs.

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-loaded with the core purpose in the first sentence, followed by compact domain context. Four sentences, each earning its place, though the middle exposition on layer types is slightly dense.

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, yet the description usefully characterizes the compound stack structure and stream semantics. For a moderately complex domain object, this is nearly complete; the main missing piece is sibling differentiation and explicit read-only framing.

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

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

Schema coverage is 100%, so both `full` and `device` are already documented, making 3 the baseline. The description does add value by explaining that output is flattened by default (implying what `full` reverses) and what `path`/`tcp_port` mean, but it does not explain parameter formats or syntax 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?

States a specific verb ('Show') and resource ('the protocol and stream stack of the port a device is attached to'), which is clear and concrete. However, it does not differentiate itself from the overlapping sibling idm_get_streams, so an agent must infer which one returns the stack versus the stream 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?

There is no explicit when-to-use or when-not-to-use guidance, and no named alternatives. With siblings like idm_get_streams, idm_get_structure, and idm_read_stream that plausibly overlap, the absence of routing guidance 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?

With no annotations, the description carries the full behavioral burden. 'List' implies a safe read and the de-duplication rule across devices sharing a connection port is a genuine behavioral disclosure beyond the schema. However, it says nothing about permissions, result size, or whether the listing is live or cached.

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 with zero filler. The primary purpose is front-loaded and the de-duplication caveat follows it naturally.

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 explained, and the one optional parameter is fully covered by the schema. The definition is nearly complete for a simple filtered list; only the relationship to idm_read_stream is left unstated.

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

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

Schema coverage is 100%, and the single optional 'device' parameter is fully documented in the schema (root, name or substring; omit for all). The description adds no parameter detail, 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 and resource ('List the TCP streams the gateway exposes') and adds the shape of the result ('with their names'). The de-duplication clause further defines scope, though it never names the confusable sibling idm_read_stream, which an agent must disambiguate on its own.

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

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

No when-to-use or when-not guidance. The agent is not told to call this instead of idm_read_stream when it wants metadata rather than stream content, nor when to prefer idm_get_protocols or idm_list_connections. Usage must be inferred 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?

No annotations are provided, so the description carries the full burden. It usefully discloses that the response is the gateway's own nested JSON and that hidden/development sections are included, but says nothing about permissions, side effects, or error behavior. It adds real context yet leaves the safety/behavioral profile partly unstated.

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 the verb+resource and followed immediately by the routing rule. The get("") reference is slightly technical but earns its place by clarifying the fetch semantics; no padding.

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. The description covers what it fetches, how it differs from idm_get_parameters, and the section granularity. Only the permission/side-effect profile is thin, which is a minor gap for a read 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%, so the schema already documents path, device, and options in detail. The description only gestures at the underlying get("") mechanism and the 'whole sub-structure' scope, adding marginal meaning beyond the schema. Baseline 3 is 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+resource ('Fetch a whole sub-structure') and explicitly distinguishes itself from the sibling idm_get_parameters. The example sections ("cfg", "ch/PGA_in") anchor the resource meaning concretely.

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?

Directly names the alternative ('Use this instead of `idm_get_parameters`') and the condition that selects it (when you want the gateway's own nested JSON for one section). Explicit when/when-not routing to a sibling.

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?

No annotations are provided, so the description carries the full burden. 'Read' implies a non-mutating operation, but it says nothing about the stored-sample-vs-fresh-query behavior (left entirely to the schema), error handling when a parameter is missing, or required permissions.

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 wasted words. It is efficient, though so terse that it edges toward under-specification rather than being genuinely complete.

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. However, for a tool with 4 parameters and no annotations, the one-line description leaves the agent without selection guidance or behavioral context, which is a meaningful 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 all four parameters are already documented, giving a baseline of 3. The description adds a useful worked example ('ec/E', 'device0') that illustrates path format, but does not explain fresh or options beyond what the schema says.

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 a single parameter', with a concrete example showing device/parameter usage. It implicitly contrasts with the plural siblings (idm_get_parameters, idm_list_parameters) by saying 'single', but never names 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?

There is no guidance on when to use this versus idm_get_parameters, idm_list_parameters, or idm_get_history. The example hints at a single-value read, but the agent must infer the choice of tool 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?

No annotations exist, so the description carries the full disclosure burden, and it does well: it discloses the inclusion of connections with no device behind them and the presence of link counters, which are non-obvious behaviors. It stops short of stating the read-only nature, permission requirements, or whether results are paginated.

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 with zero filler; the core capability is front-loaded and the differentiating caveat follows immediately. Every clause earns its place.

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

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

For a parameterless, read-only listing tool with an output schema already describing return values, the description covers purpose, scope and the key differentiator adequately. The only residual gap is the absence of any explicit read-only/auth statement, which annotations would normally provide.

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

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

The tool takes zero parameters, so per the rubric the baseline is 4. The description correctly implies no filtering options exist and that the call returns everything the gateway holds.

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 ('List the gateway's physical connections') and immediately scopes it ('with link counters'). It also distinguishes itself from the device/stream siblings by noting it surfaces connections that those views cannot represent, so an agent can pick it without opening any schema.

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

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

The description gives clear context for when this tool is the right choice: when a gateway-held connection has no device behind it, the device and stream views are insufficient. It does not explicitly state when not to use it or name the sibling tools by identifier, but the contextual contrast is strong enough to route correctly.

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

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

No annotations are provided, so the description carries the full burden, and it discloses almost nothing: no pagination, no return shape, no note on whether inactive devices are excluded by default, and no explanation of the implicit 'group' context. Only the word 'list' weakly implies a read-only 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?

One short, front-loaded sentence with no filler or repetition. It is efficient, though its brevity comes at the cost of substance rather than being tight-but-complete.

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, but the description still leaves a critical gap: it scopes results to 'this group' without any parameter or explanation of how the group is identified. For a list tool with no annotations, that omission makes correct invocation ambiguous.

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 brand_filter and include_inactive fully documented (including an example value), so the schema does the heavy lifting. The description adds no meaning beyond the schema, 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?

The description names a specific verb and resource ('list the devices'), which is better than a tautology. However, the scope qualifier 'of this group' is never defined — there is no group parameter in the schema — and it does nothing to distinguish this tool from siblings like idm_device_status or idm_list_connections.

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 prerequisites, and no mention of any alternative among the 14 sibling tools. An agent gets no signal about when this list is preferable to idm_device_status or the other idm_list_* 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?

No annotations are provided, so the description carries the full disclosure burden. 'List ... without their values' usefully characterizes the payload as paths only and implies a read-only operation, but there is no statement about permissions, error behavior on ambiguous substrings, or result size/pagination limits.

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 tight sentence with no filler, and the distinguishing qualifier ('without their values') is positioned at the end where it does the most differentiating work. Nothing needs trimming or front-loading.

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-only listing tool with 100% schema coverage and an output schema (so return values need no explanation), the description is nearly sufficient. The remaining gap is routing guidance relative to idm_get_parameters/idm_get_value, which an agent must infer from the phrase 'without their values'.

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%: `device` (root, full name, or unambiguous substring) and `prefix` (path-prefix restriction, with example) are both documented in the schema. The description adds nothing about either parameter, 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?

States a specific verb ('List') and resource ('a device's parameter paths'), plus the key scope modifier 'without their values', which implicitly contrasts it with the sibling idm_get_parameters. It is clear what the tool returns, though it never names the sibling it differs from.

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: an agent can infer this is the lightweight option when values are not needed, since 'without their values' contrasts with a values-returning sibling. There is no explicit when-to-use, when-not-to-use, or named alternative, and no mention of how ambiguity in the `device` substring is handled.

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?

With no annotations, the description carries the behavioral burden and discloses key traits: it attaches to the stream for the read, detaches unless already opened with idm_open_stream, and returns bytes as hex and text. This covers lifecycle side effects and output format, though it does not discuss permissions or concurrency.

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 core purpose in one sentence, then efficiently adds attachment behavior and return format in a short paragraph. Every sentence earns its place with no wasted words.

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 operation with a complete input schema and an output schema, the description is nearly complete: it explains what the tool does, its attach/detach behavior, and the return format. The main gap is absent guidance on when to choose it over sibling read tools.

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 four parameters. The description adds no parameter-specific meaning beyond what the schema provides, making the baseline 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?

States a specific verb and resource: 'Read raw bytes from a stream.' It clearly distinguishes from listing siblings like idm_get_streams, though it does not explicitly name an alternative or clarify when not to use it.

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?

Offers no explicit when-to-use or when-not-to-use guidance versus alternatives such as idm_get_value or idm_get_streams. The attachment lifecycle detail is behavioral, not usage guidance.

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