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

With no annotations, the description carries the full burden. It discloses the return content (encodings, YANG models, gNMI version), which is useful, but says nothing about read-only nature, required session state, permissions, or failure modes.

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

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

Two tight sentences with the operation front-loaded and the return payload immediately following. 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 single-parameter, read-style discovery tool with no output schema, the description covers purpose and return contents adequately. The only gap is the implicit prerequisite of an existing device session, which is not stated.

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?

One parameter at 100% schema coverage; the schema already documents 'name' as the device session name. The description adds no format, linkage, or naming detail beyond that, 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 — 'Get gNMI capabilities from Nokia SR OS device' — and enumerates what is returned. It is clearly distinguishable from siblings like sros_get_config or sros_set_update, though it does not explicitly name a sibling it is not.

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

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

There is no guidance on when to call this versus alternatives such as sros_connect (must a session already exist?) or the get_config/get_state tools. The purpose implies discovery usage, but no conditions or exclusions are stated.

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

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

With no annotations, the description carries the full disclosure burden but only partially meets it. It usefully states the default port (57400) and that TLS verification is on by default, which are safety-relevant behaviors; however it omits whether credentials are persisted, what happens on reconnecting an existing session name, and that sros_disconnect is needed for cleanup.

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 short, front-loaded sentences with no filler; the core action is stated first and the security/port caveats follow. Slightly more than strictly needed but each sentence carries value.

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?

There is no output schema and no annotations, so the description must be self-sufficient; it explains connection behavior and defaults but says nothing about what a successful call returns (session handle/status) or how failures surface, leaving a gap for an 8-parameter stateful 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 every parameter is already documented in the schema, and the description adds only the default port value, which is already in the schema. Baseline 3 is appropriate since the schema does the heavy lifting.

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

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

The description uses a specific verb ('Connect') plus resource ('Nokia SR OS device via gNMI (gRPC)') and states the side effect of registering a named session. This clearly distinguishes it from siblings like sros_disconnect, sros_list_sessions, and the sros_set_* tools.

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

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

The phrase 'for subsequent operations' implicitly tells the agent this must precede other sros_* calls, but there is no explicit when/when-not guidance and no named alternative (e.g. how it relates to sros_list_sessions or when to reuse an existing session). Usage is implied rather than stated.

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

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

No annotations are provided, so the description carries the full behavioral burden. It does not state whether the operation is idempotent, what happens if the named session does not exist, or whether an active subscription is terminated—material details for a session-teardown tool.

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

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

One front-loaded sentence with no wasted words. It is lean rather than verbose; the only cost is that the brevity leaves gaps elsewhere.

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

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

For a one-parameter teardown with no output schema, the description is minimally sufficient. With no annotations and no statement of error or idempotency behavior, an agent still lacks enough to know how failure cases behave.

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

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

Schema coverage is 100% with a single, self-documented 'name' parameter ('Session name to disconnect'). The description adds no syntax, format, or lookup 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 ('Close') and resource ('gNMI session to a Nokia SR OS device'), which is clear enough to distinguish from sros_connect. However, it never names the sibling it pairs with or contrasts against, so sibling differentiation is left to inference from the name.

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 call this versus the alternatives (e.g., sros_connect, sros_list_sessions), nor any prerequisite such as an existing session. Usage is only implied by the tool name.

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

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

With no annotations, the description carries the full burden. It usefully discloses the datatype (config), the protocol (gNMI) and the json_ietf encoding, and read semantics are clear. However it says nothing about permissions, error behavior, response size, or what happens with very broad queries such as '/configure (entire config)'.

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 operational sentence is front-loaded, followed by a clearly labeled, scannable list of example paths. Every element earns its place and nothing is padded.

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 100% schema coverage and no output schema, the description supplies what an agent needs to construct a valid call: paths, examples, and encoding. Only the shape of the returned data and error handling are left unaddressed, which is acceptable given no output schema is declared.

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 real value beyond the schema by showing six concrete YANG path patterns (interfaces, ports, VPRN services, BGP, card slots, and the entire config), which the schema only hints at with a single example.

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?

Names a specific verb (Get) and resource (configuration) plus the exact mechanism (gNMI Get, datatype=config) and encoding (json_ietf). The datatype=config framing implicitly separates it from the state-oriented sibling sros_get_state, but no sibling is named explicitly.

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

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

Tells the agent it must supply one or more YANG paths, which implies the intended usage of retrieving device configuration. It never states when to prefer this over sros_get_state, yang_search for path discovery, or the sros_set_* tools for modification, and gives no 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?

With no annotations, the description carries the full burden. It usefully discloses the protocol and datatype (gNMI Get, datatype=state), implying a read-only operation, and the encoding (json_ietf). It does not cover authentication, error behavior on bad paths, or session requirements.

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 operation statement is front-loaded in one dense sentence, followed by a clearly labeled example block. Every element earns its place and nothing is repeated, though the example list is longer than strictly necessary.

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 no output schema, the description covers mechanism, encoding, and path format well. It could say more about what the returned state payload looks like, but the essential information for a correct call 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 coverage is 100%, so the baseline is 3, but the description adds genuine value with five realistic SROS state path examples that go beyond the schema's single generic example. The 'name' (device session) parameter is left to the schema, which is acceptable.

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 ('Get operational state from Nokia SR OS') and pins the mechanism (gNMI Get, datatype=state), which naturally separates it from the config-oriented sibling sros_get_config. It never names a sibling explicitly, so it stops at clear-but-undifferentiated.

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?

'Provide one or more YANG paths' is an input instruction, not usage guidance. There is no statement of when to prefer this over sros_get_config or yang_search, nor any prerequisites. Usage is only implied by the 'state vs config' resource framing.

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

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

With no annotations, the description carries the full behavioral burden. 'List all active' implies a read-only, non-destructive operation and discloses a filtering trait (active sessions only), but it omits whether a connection is required, what 'active' means, and the return shape.

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

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

A single front-loaded sentence with zero filler. The verb and scope appear immediately, which is ideal for such a simple tool.

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

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

For a zero-parameter list tool with no output schema and no annotations, the description covers what is listed but says nothing about the return format or what counts as a session. Given the low complexity, this is adequate but has clear gaps.

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

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

The tool takes zero parameters, so the baseline of 4 applies. The description does not need to explain any arguments, and it correctly implies no filtering options are accepted.

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

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

The description states a specific verb (List) and resource (active Nokia SR OS gNMI sessions), making the operation unambiguous. No sibling tool lists sessions, so confusion is unlikely, but the description does not explicitly differentiate itself from the other sros_* tools.

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

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

There is no when-to-use guidance, no mention of prerequisites (e.g., an established connection), and no reference to alternatives. The agent must infer that this is the right call purely from the resource name.

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

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

No annotations are provided, so the description carries the full disclosure burden. It implies destructiveness ('Removes the config subtree') but says nothing about commit/datastore semantics, reversibility, required permissions, or idempotency — all critical for a config-deleting gNMI Set 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?

Two short sentences plus a compact example; the destructive action is front-loaded and nothing is wasted.

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

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

With no annotations and no output schema, the description adequately conveys what happens and the path format, but omits the error/failure behavior and commit semantics an agent needs to safely invoke a destructive Set operation.

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 goes beyond it by giving a concrete YANG path literal for 'paths' (with list-key predicates like router-name=Base), which materially clarifies the expected path syntax that the schema only calls 'List of YANG paths'.

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 ('Delete configuration on Nokia SR OS via gNMI Set') and clarifies scope with 'Removes the config subtree at the given path(s).' The verb 'delete' also cleanly separates it from siblings sros_set_update and sros_set_replace without needing to name them.

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

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

No when-to-use or when-not-to-use guidance is given. The description never mentions sros_set_replace or sros_set_update, so the agent must infer from the verb alone whether deletion or replacement semantics apply. Usage is only implied by the tool name.

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

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

With no annotations, the description carries the full behavioral burden and does disclose the critical destructive trait: the entire subtree is replaced and any config not in the new value is removed. It stops short of auth requirements, atomicity, or error/response behavior, but the key risk is surfaced explicitly.

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, zero waste, with the operation and its scope front-loaded and the destructive warning placed immediately after. Nothing could be cut without losing meaning.

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

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

For a three-parameter mutation tool with no annotations and no output schema, the description covers the essential risk (full-subtree replacement). Minor gaps remain around session prerequisites and failure/response behavior, but an agent can call it correctly.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters, making 3 the baseline. The description reinforces the relationship between path and value (entire subtree replaced by a complete value) but adds no format or syntax detail 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+resource (replace config on Nokia SR OS via gNMI Set) and describes the exact semantics of the operation. It is clearly distinguishable from siblings like sros_set_update and sros_set_delete 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 warning about removing existing config implies the choice against sros_set_update, but no alternative is named and no explicit when-to-use/when-not-to-use guidance is given. The gNMI replace-vs-update distinction is left for the agent to infer from sibling names.

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

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

With no annotations, the description carries the full burden; it does disclose the meaningful merge semantics (existing config is preserved and values are combined rather than overwritten), which is the key behavioral trait. However, it omits session prerequisites, error behavior for invalid paths, and any indication of what a successful response contains.

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 purpose sentence is front-loaded and the two examples are short and directly instructive for constructing a valid call. Slightly verbose in places, but every element (mechanism, merge semantics, path/value examples) 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 destructive-capable mutation tool with no annotations and no output schema, the description covers the operation and input format well but leaves gaps: it never states that a session (name) must first exist via sros_connect, nor what happens when a path is invalid. Adequate but not complete.

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

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

Schema coverage is already 100%, so the schema documents the three parameters, establishing a baseline of 3. The description goes beyond it by showing concrete path syntax with list keys (e.g. /configure/router[router-name=Base]/interface[interface-name=lo0]) and the nested JSON value shape, which materially clarifies how 'path' and 'value' must be formed.

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 (update/merge), the resource (configuration on Nokia SR OS) and the mechanism (gNMI Set), and the parenthetical '(merge)' hints at how it differs from sros_set_replace and sros_set_delete. It does not explicitly name those siblings, so the differentiation is implied rather than stated.

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 context is only implied: 'merge' suggests a partial, additive update versus the sibling replace/delete tools, and the examples show a call shape. There is no explicit statement of when to choose this over sros_set_replace or sros_set_delete, and no prerequisites (e.g. an active session) are given.

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. It usefully discloses a prerequisite (YANG models in yang/sros-25.10/YANG/ or a pre-built cache in yang/cache/), but says nothing about result shape, whether results are paged/truncated, or failure behavior when a keyword matches nothing.

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 one-sentence purpose followed by examples that each earn their place by demonstrating a distinct keyword/tree combination. Slightly long, but nearly all content is informative.

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 keyword-search tool with no output schema and full schema coverage, the definition is nearly sufficient: purpose, routing to downstream tools, examples, and environment prerequisites are all present. Only return-format and edge-case behavior are left implicit.

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 examples add real meaning beyond the schema by showing the kind of domain-specific keyword tokens that are valid ('fpe', 'end-dt2', 'pxc') and how the tree argument pairs with them.

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 ('Search Nokia SR OS YANG paths by keyword') and immediately positions itself relative to the sibling tools. An agent can distinguish it from sros_get_config/sros_get_state 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?

Explicitly states when to use it ('find the correct gNMI path before using sros_get_config/sros_get_state/sros_set_update') and reinforces this with five concrete invocation examples covering different domains and both trees.

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