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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds context beyond them: traversals are bounded by max_nodes, truncation is reported via 'truncated' so a short list isn't mistaken for complete, include_values costs one extra read per variable, node_class filtering does not prune the walk, and an unresolvable browse_path is an error rather than an empty result. These are exactly the non-obvious behaviors 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?

It is front-loaded with the four modes before drilling into each parameter, and every sentence carries operational information. It is on the long side as a single undivided paragraph, which slightly hurts scannability, but there is 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?

A 7-parameter traversal tool with an output schema is well covered: the description supplies the semantics the schema can't (type_definition, truncation, filter-vs-prune, path resolution errors) and doesn't waste space re-documenting return shapes the output schema already defines. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description earns a bump by adding semantics the schema does not: the depth-0 path-resolution idiom, the fact that node_class filtering is applied post-walk rather than pruning, and the explanation that type_definition describes what a node *is* versus its NodeClass. Minor gap: max_nodes' interaction with depth beyond the truncation note is only lightly treated.

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

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

The description opens with a specific verb+resource ('Explore the OPC UA address space') and then enumerates the four concrete modes: list children, walk a subtree, resolve a browse path, search by name. It is clearly distinguishable from read_opcua_nodes (referenced explicitly as the way to fetch values afterwards) and from act_on_alarm (mentioned via 'AlarmConditionType').

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 states the default behavior ('with the defaults it lists the immediate children of node_id') and then gives conditional routing: use browse_path when you don't know numeric IDs, set depth 0 to resolve a path, use name_filter for unknown names, and leave include_values off when mapping a large address space, reading with read_opcua_nodes instead. That is explicit when-to-use, when-not-to-use, and named 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?

Beyond the readOnlyHint/idempotentHint annotations, it discloses the key non-obvious behavior: it does not fail when the connection is down, it returns 'connected': false with a reason. It also warns that null diagnostics means the server does not publish them, not zero. That null-versus-zero distinction is genuinely important, though the description leans on detailed return-field semantics that the output schema already carries.

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?

Purpose is front-loaded in the first sentence, which is good, but the description runs long for a parameterless status tool and devotes several clauses to output fields the output schema already documents. Those clauses are informative but not all of them earn their space 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?

For a zero-parameter read-only diagnostic with an output schema and full annotation coverage, nothing an agent needs is missing. Between the annotations and the output schema the contract is fully covered, and the description fills the remaining gaps around failure behavior and diagnostic semantics.

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?

Zero parameters, so there is nothing to disambiguate; the baseline applies. The description correctly spends no space on arguments and instead explains what the no-argument result means.

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

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

The description names the specific verb and resource — report whether the MCP server is connected to the OPC UA server, plus endpoint, security, ServerStatus and NamespaceArray. The second sentence explicitly separates it from the rest of the sibling set: it is the health check and the one tool that answers while the connection is down.

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

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

Guidance is explicit and conditional: call it first when another tool cannot reach the server, and consult 'capabilities' when read_opcua_history or read_event_history was refused. It also names the concrete use case of mapping 'ns=' indexes to namespace URIs, which no sibling covers.

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, but the description adds real value beyond them: it discloses that the data comes from a direct ConditionRefresh round-trip rather than passively collected subscription data, which changes how the agent should interpret completeness. The one remaining gap is return shape and volume, which the output schema covers.

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

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

Three sentences, each earning its place: identity/scope first, mechanism second, routing guidance third. No filler or repetition of the title.

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

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

With a rich output schema, full parameter documentation, and annotations covering the safety profile, the description supplies everything an agent needs: what it returns, how it is fetched, and when to prefer it over the history sibling.

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 both node_id and the timeout's error-vs-empty-list semantics. The description adds no parameter-level detail beyond what is in 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 (list) and resource (alarm and condition instances the server is currently retaining), then defines the scope precisely as 'active, unacknowledged, or both'. An agent can distinguish this from read_events without opening either 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?

Gives an explicit decision rule: use this for 'what is wrong right now', use read_events for what has happened since you last looked. It names the sibling alternative and the condition that selects it.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered; the description adds real behavioral context by explaining that results include changes buffered since subscription creation. The notable omission is whether listing drains or leaves the buffer intact, which matters for repeated calls. Strong but not fully complete on mutation-side effects of a read.

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 load-bearing: the first defines the payload and its buffered content, the second routes the agent from the subscribe sibling and offers the resource alternative. Nothing is repeated from the name or annotations.

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, the description needn't explain return structure, and it correctly focuses on provenance of the data and the alternate access path. The only meaningful gap is buffer-consumption semantics, which an agent calling this repeatedly would want to know.

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 is nothing for the description to disambiguate and the baseline of 4 applies. The description does not need to explain any inputs.

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 ('List the active OPC UA data-change subscriptions') and adds scope that distinguishes it: each subscription comes with the value changes buffered for it since creation. An agent can tell this apart from subscribe_opcua_nodes, read_opcua_nodes, and list_active_alarms 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?

It states explicitly when to reach for this tool ('This is how to collect what subscribe_opcua_nodes has been watching') and names an equivalent alternative path (the 'opcua://subscriptions' resource). Both the use condition and the alternate access route are spelled out rather than inferred.

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 only declare readOnly/idempotent/non-destructive; the description adds substantially beyond them: a server capability prerequisite, the specific failure code capability_not_supported, the 5000-event cap, the risk of unbounded bursts, and that filtering happens client-side to avoid server misbehavior. It also explains that the `completeness` field reports truncation, which is real 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?

It is front-loaded with the purpose and the sibling distinction before prerequisites and parameters, and no sentence is filler. It runs long and restates a couple of schema facts (defaults, node id value), which keeps it from a 5.

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

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

For a five-parameter historical-read tool it covers the prerequisite, the failure mode, defaults, cap behavior, and truncation signal; an output schema exists so return-shape explanation is not owed. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds cross-tool meaning: node_id is the notifier and the same node subscribe_events takes, and the result's `completeness` ties back to range size. Most other parameter detail (ISO-8601 formats, defaults, cap) duplicates the schema rather than extending it.

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

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

The opening sentence names a specific verb and resource ('Read events the OPC UA server stored') and immediately scopes the time range to the past. It explicitly distinguishes itself from both subscribe_events (live only) and read_events (identical records, different path), so an agent can pick it without inspecting 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?

It gives a concrete when-to-use framing ('what happened overnight', 'what fired in the ten minutes before the line stopped') plus the exclusion that subscribe_events cannot answer retrospective questions. It also names when the call will be refused (no AccessHistoryEventsCapability) and what that refusal returns.

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 declare readOnlyHint=false and idempotentHint=false, and the description explains exactly why: returned events are removed from the buffer, making the call non-idempotent. It further discloses overflow behavior and points at the `completeness` field in the structured result, adding real behavioral context beyond the annotations.

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

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

Three sentences, each carrying distinct information: source and ordering, drain semantics, and overflow reporting. Front-loaded with the core action and no redundant restatement of the tool name.

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

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

For a two-optional-parameter read tool with an output schema, the description covers the essential non-obvious behavior: buffer draining, ordering, and where overflow/drop counts appear. Nothing an agent needs in order to call it correctly is missing.

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

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

Schema description coverage is 100%, so `limit` and `node_id` are already documented in the schema. The description adds no additional meaning about parameter behavior or interactions, which is acceptable given the schema does the heavy lifting, but it does not exceed the baseline.

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

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

States a specific verb and resource ('Read the events buffered by subscribe_events') plus ordering semantics ('oldest first'), which cleanly separates this from history-oriented siblings like read_event_history. An agent can tell what it returns and where the data comes from without opening the schema.

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

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

The description makes the prerequisite explicit by tying the tool to subscribe_events, and clarifies the calling pattern ('a second call returns only what has arrived since'). It does not explicitly contrast with read_event_history or state when to prefer one over the other, so it is clear context without 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, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavior beyond that: ReturnBounds=false with no boundary values or BadBoundNotFound placeholders, a pre-flight capability_not_supported refusal with a suggestion before anything is sent, continuation-point handling that preserves the interval anchor, and the 5000-value bound. It stops short of describing the shape of the returned records, leaving that to the 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?

Front-loaded with the core action and the raw-versus-aggregate fork before any caveats, which is the right order. It is a dense single block, though, and a few phrases ("which is how to ask about a week of data without transferring a week of data") spend words on rhetoric rather than new 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?

Covers what an agent needs to call this correctly on a complex 6-parameter tool: mode selection, capability preconditions, error behavior, size limits, and an explicit instruction to read the structured result's completeness field rather than counting records. Return-value detail is delegated to the output schema, which exists.

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 parameter docs are already thorough, including the num_values cap semantics, the timezone requirement on start_time, and the interaction between aggregate_function and processing_interval. The description mostly restates those rules in prose, adding only the reasoning that aggregate reads preserve the original interval anchor, so the baseline of 3 is appropriate.

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

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

Opens with a specific verb and resource ("Read what a node's value has been over time") and immediately splits the tool into its two distinct modes: raw stored readings versus aggregate summaries. The capability gating and the pointer to get_server_status make it distinguishable from read_opcua_nodes and the other history 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 states when to use each mode: omit aggregate_function for raw readings, supply it to ask about a week of data without transferring a week of data, and use it rather than raising num_values when the cap is hit. It also names prerequisites (AccessHistoryDataCapability or aggregate support) and routes the agent to get_server_status to discover which 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?

Goes well beyond the readOnly/idempotent annotations: it explains the single-round-trip batching behavior, that each node returns its own record with value, data type, status code and both timestamps, and critically that a rejected node surfaces as a per-node 'Bad…' status rather than failing the whole call. That partial-failure semantics is exactly the kind of detail an agent cannot infer from structured 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?

Four sentences, front-loaded with the action and the batching rule, then the return shape, then partial-failure semantics. The aside about quality and age ('a bare number carries neither') is rhetorical padding but does justify the returned metadata, so the cost is small.

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

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

Covers everything an agent needs before calling: what it reads, how to batch, what comes back per node, and how failures are represented. With an output schema present and annotations declaring the safety profile, the remaining details are already structured.

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 node ID format, the 500-item cap and the include_write_access cost model are already fully documented in the schema. The description reinforces the batching intent of node_ids but adds no format or constraint detail beyond the schema, 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 ('Read the current value of one or more OPC UA nodes in a single request') and scopes it as a single batched read, which clearly separates it from siblings like read_opcua_history, browse_opcua_nodes, and subscribe_opcua_nodes.

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 a concrete usage rule — 'Pass every node you need in one call' — and quantifies the benefit (fifty nodes, one round trip), which tells the agent to batch rather than loop. It never explicitly names an alternative tool or states when not to use this one (e.g. for historical values or continuous monitoring), so it stops short of full guidance.

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

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

Beyond annotations, it discloses important behavior: the call returns immediately, events buffer in the background, repeated calls replace the subscription, and buffered events are discarded on replacement. These details go well beyond the readOnly/idempotent/destructive annotations and help the agent avoid accidental buffer loss.

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

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

The description is front-loaded with purpose, then covers asynchronous return, replacement semantics, and alternatives in four efficient sentences. Every sentence provides actionable information with 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?

Given the annotations, full schema descriptions, and output schema, the description is complete for correct invocation. It explains the asynchronous subscription model, replacement behavior, buffer discard effect, and the key sibling alternative.

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 node_id, buffer_size, and severity_min, including defaults and clamping. The description does not add meaningful parameter-level detail beyond referring generally to a notifier node, 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 gives a specific verb, resource, and scope: 'Start buffering OPC UA events (alarms, condition changes, plain events) from a notifier node.' It distinguishes the tool from siblings by naming read_events for retrieval and list_active_alarms for current problems.

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 to use this tool 'to watch for things happening' and to use list_active_alarms 'for what is wrong right now.' It also directs the agent to read_events for collected events, giving clear routing between subscription, retrieval, and current-state 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 only declare readOnlyHint=false, idempotentHint=false, destructiveHint=false, which says little about lifecycle. The description adds real behavior: the server buffers pushed values, each node gets its own subscription record and ID, subscriptions are re-established automatically if the connection drops, and results are retrieved through a separate tool or resource rather than returned here.

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 verb and the anti-pattern it replaces, and every subsequent sentence carries distinct information (collection path, per-node records, cancellation, reconnect behavior). It runs four sentences, slightly longer than strictly necessary, but no sentence is filler.

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

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

For a stateful, non-idempotent subscription tool with 7 parameters, the description covers the full lifecycle an agent needs: creation, retrieval of buffered values, cancellation, capacity context, and automatic re-establishment after disconnects. An output schema exists, so return-value detail is correctly left out.

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 per-parameter docs are unusually rich (deadband semantics, trigger modes, clamping), so the schema does the heavy lifting. The description only adds that subscriptions are per-node and separately identified, which lightly informs node_ids but adds nothing about buffer_size, deadband, or intervals. 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 first sentence gives a specific verb ('Watch') and resource ('one or more OPC UA nodes for value changes') and immediately frames it against polling. Later sentences distinguish it from read_opcua_nodes (polling) and point to list_subscriptions/unsubscribe_opcua_nodes, so an agent can separate it from every relevant sibling without opening a 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?

Explicit when-to-use framing ('tell me when this changes' or 'what has this been doing' over a short window) plus an explicit when-not alternative: repeatedly calling read_opcua_nodes misses changes between calls and costs a round trip. It also names the follow-up tools (list_subscriptions, the opcua://subscriptions resource) and the cancel path (unsubscribe_opcua_nodes).

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 declare readOnlyHint=false and destructiveHint=false, and the description adds real behavioral detail beyond them: buffered data is discarded but returned so it can be read one last time, and an unknown ID causes an error with no cancellation happening at all (all-or-nothing failure). It doesn't cover authorization requirements or whether cancellation is awaited/bounded by a timeout, but the failure semantics are unusually well disclosed.

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 action, then return content, then failure behavior. No filler or repetition of the name.

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

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

An output schema exists so return values need not be explained, and the description still covers the key mutation semantics (discard + last-read return, atomic failure on invalid IDs). For a one-parameter mutation tool this is close to complete; only auth/permission and concurrency caveats 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 100% and the single parameter is documented there, including the ID format and origin (subscribe_opcua_nodes, list_subscriptions). The description only echoes 'one or more active', which the schema already enforces via minItems 1; no additional semantics are added.

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 ('Cancel one or more active data-change subscriptions'), plus the exact consequence ('discard what they had buffered'). That is clearly distinguishable from subscribe_opcua_nodes, list_subscriptions, and the read_* siblings.

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

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

The context is clear: this is for tearing down active subscriptions, and the ID source is implied by 'active'. However, it never names an alternative or an exclusion (e.g., when to prefer list_subscriptions to check state first, or what to do for a non-existent ID besides expecting an error).

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