Netdryrun

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

With no annotations, the description does disclose an important behavioral trait: 'Starts no lab.' But it then describes dry-run requirements, duration, and INCONCLUSIVE semantics that belong to a different tool, leaving the agent with a noisy and potentially misleading behavioral picture for this simple listing 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?

The useful content is concentrated in the first two sentences and the final sentence about record_baseline. The middle passage about Docker, WSL2, 60–120 s runtimes, and INCONCLUSIVE states is largely irrelevant to check_types and bloats the definition.

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 listing tool with an output schema, the core purpose and safe/no-lab behavior are covered. However, the description does not cleanly isolate check_types from dry_run/start_run and may lead an agent to infer requirements that do not apply here.

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 has zero parameters, so the baseline is 4. The description adds no parameter detail, but none is needed because there is nothing to document.

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 clearly states a specific verb and resource: list supported check types and their keys. It also distinguishes the tool from lab-starting operations with 'Starts no lab,' though it does not explicitly name the sibling tools 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?

It gives two concrete uses: reading netdryrun.yml or helping a human write it, and it names record_baseline when no checks exist. However, most of the usage guidance discusses when to use Netdryrun/dry runs generally rather than when to choose check_types over validate, run_checks, or dry_run.

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 so thoroughly: it discloses the 60–120s runtime, Linux/WSL2 + Docker + containerlab requirements, root-equivalent rights, macOS/sandbox exclusions, lab lifecycle, verdict values and their exact meanings, failure output structure, unready semantics, and treatment of quoted lab output as data rather than instructions.

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

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

The description is front-loaded with the core purpose, but the body is a dense wall of clauses, semicolons, parentheticals, and repeated rerun guidance. Most content is useful, but the same points about fixing and rerunning appear more than once and could be structured much more compactly.

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 complexity, the lack of annotations, and the existence of an output schema, the description covers everything an agent needs: setup prerequisites, path semantics, lab lifecycle, verdict interpretation, failure handling, baseline comparison, and the inconclusive/error distinction.

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%, so the description must explain the two parameters, and it does: path is described as a folder or file, Windows or WSL form, with absolute paths safest and relative paths resolved only against a single-folder NETDRYRUN_MCP_ROOT. keep_lab is tied to rerunning with keep_lab=true for diagnostics before destroying the lab.

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: dry-run a network change by deploying a containerlab lab, waiting for convergence, running checks, and destroying the lab. That full lifecycle clearly distinguishes it from adjacent tools like record_baseline, start_run, or run_checks.

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 explicit when-to-use guidance: before proposing or applying any routing or policy change, with no routing change without a verdict. It also rules out ping as a substitute, explains failed-run behavior, warns that a pass on a refactor is not proof, and directs the agent to record_baseline when no checks exist.

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 provided, the description carries the full behavioral burden and does so well: it explains polling behavior, typical dry-run duration, unknown run_id error handling, setup-problem statuses, and environment requirements including Linux/WSL2, Docker, and containerlab privileges. It also warns against inventing or weakening checks.

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

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

The description is front-loaded with the core purpose and polling behavior, and most sentences add useful operational guidance. However, it repeats the 60–120 s dry-run duration and includes broader Netdryrun, ping, and record_baseline guidance that is only partly specific to get_result.

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?

Because an output schema exists, the description need not explain return fields in detail. It still covers the essential context for an async result tool: polling cadence, terminal statuses, error and inconclusive meanings, environment constraints, and when to act on the verdict.

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%, so the description must add meaning for the single required run_id parameter. It does this by tying run_id to a run started with start_run and by stating that an unknown run_id yields status error, though it does not describe the run_id format.

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 identifies the resource (the result of a run) and its origin (start_run), and the body distinguishes polling from a finished verdict and from dry_run's result. An agent can route among start_run, dry_run, and get_result without needing to inspect other 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 explicitly says to wait poll_after_s seconds and call again while status is running, and it states when Netdryrun should be used before routing or policy changes. It also gives clear when-not guidance: ping is not a test, and INCONCLUSIVE means stop rather than retry repeatedly or apply the change.

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 so well: it discloses the '# INCOMPLETE BASELINE' truncation marker and what it means, that nothing is written to disk, default guard behavior plus the guards=false escape hatch, runtime (60–120 s), hard platform prerequisites (Linux/WSL2, Docker, containerlab, root-equivalent; no macOS or sandboxed DinD), and the INCONCLUSIVE/error semantics with retry limits. These are consequential operational facts an agent could not infer from the schema.

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

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

The core purpose and the guards/attributes behavior are front-loaded, but the middle section drifts into cross-cutting Netdryrun doctrine ('Ping is not a test', 'no routing change without a verdict') that repeats guidance already implied elsewhere, and the 'if no checks exist' instruction appears twice. It is information-dense but bloated for a 5-parameter tool.

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

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

An output schema exists so return structure need not be spelled out, and the description still covers the important edge case (truncated baseline) plus prerequisites, runtime, and failure modes. The main remaining hole is the unexplained deploy/wait_seconds parameters, which an agent needs to reason about before invoking a tool that may deploy a lab.

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%, so the description must compensate, and it does for guards (default standard guards of no default route / no link subnet via BGP) and attributes (pins AS path, local preference, communities). However, 'deploy' (default true, the most consequential parameter since it implies actually deploying the lab) and 'wait_seconds' (default 45) are never explained anywhere, leaving two of five parameters opaque.

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 ('Snapshot a known-good lab (containerlab topology file) as netdryrun.yml check text') and enumerates exactly what gets captured: BGP sessions, prefix counts with min/max headroom, and BGP routes. This is clearly distinguishable from siblings like dry_run and run_checks, which consume or execute checks rather than record 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?

Explicit trigger conditions are given: 'Call it when no checks exist, before changing the configs, then dry-run the change against this baseline,' reinforced by 'if no checks exist, call record_baseline.' It also names the downstream sibling (dry_run) and the sequencing between them, so the agent knows both when to call this and what to do next.

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 so thoroughly: it discloses platform prerequisites (Linux/WSL2, Docker, containerlab, root-equivalent rights, not macOS or sandboxed Docker), expected runtime of 60–120 s, and that it neither deploys nor destroys the lab. It also explains how to interpret INCONCLUSIVE and status errors as setup problems rather than signal about the change.

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

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

The description is front-loaded with the core behavior and then adds necessary operational warnings. It is somewhat long and dense, but nearly every sentence adds actionable context about prerequisites, runtime, interpretation, or alternatives rather than repeating structured fields.

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

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

For a complex tool with no annotations, one required parameter, and an output schema, the description covers prerequisites, runtime, side effects, failure interpretation, retry policy, and sibling alternatives. It gives an agent everything needed to decide whether and how to call it, leaving return-value details to the output schema.

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

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

The schema has 0% description coverage for the single `path` parameter, so the description must compensate. It does clarify that `path` points to netdryrun.yml, which is useful, but it does not specify whether the path is a file or directory, absolute or relative, or any format expectations.

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: run the checks in netdryrun.yml at `path` against an already-running lab, explicitly no deploy or destroy. It distinguishes itself from sibling dry_run by saying configs edited after the lab started do not reach it and directing users to dry_run to test a change.

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 explicit when-to-use guidance: before proposing or applying any routing or policy change, because ping is not a test. It names alternatives and edge cases: use dry_run for edited configs, call record_baseline if no checks exist, and do not retry INCONCLUSIVE more than once.

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 delivers: async lifecycle, immediate success/failure signaling (a config error or a path outside NETDRYRUN_MCP_ROOT is answered at once with status error and no run_id), statefulness ('the run lives in this server: if the server restarts, start again'), expected duration (60–120 s), and hard environmental prerequisites (Linux/WSL2, Docker, containerlab, root-equivalent rights; fails on macOS and non-DinD sandboxes). It also discloses the destructive tail (the lab is destroyed at the end unless the same keep_lab semantics as dry_run apply).

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 identification and the immediate return contract, followed by polling rules, failure semantics, and prerequisites in a sensible order. Some material is server-general rather than tool-specific ('Ping is not a test', 'Never invent or weaken checks... call record_baseline'), which slightly dilutes focus, but every clause is substantive.

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 the description needn't document return values, yet it still explains the immediate running/error shapes. Polling, retry limits, restart loss, timing and platform prerequisites are all covered. The remaining gap is the two input parameters' meaning, especially keep_lab, which is invisible in both schema and description.

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% for both parameters, and the description only says 'Same `path` and keep_lab as dry_run' — deferring rather than explaining. It never says what path points to (config file? directory?) or what keep_lab actually does (leaving a deployed lab behind has cost and cleanup implications). The deferral is a small mitigation, but an agent must go read dry_run to fill the gap.

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 precise framing — 'The asynchronous dry_run, for clients that give up on a long tool call' — that names the verb (a dry run), the mode (async), and the exact sibling it mirrors. It states the immediate return shape ('returns at once with a `run_id` and status running (no verdict yet)') and that the same deploy/check/destroy lifecycle follows, so an agent can distinguish this from dry_run and get_result 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?

Routes explicitly: call get_result with the run_id every poll_after_s until status is no longer running, and use this instead of dry_run when the client gives up on long calls. Also gives decision rules for outcomes — INCONCLUSIVE means stop, retry at most once, and error/inconclusive is a setup problem unrelated to the change — plus the server-level trigger ('before proposing or applying any routing or policy change') and an anti-pattern ('Ping is not a test').

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, and it does so thoroughly: runtime in seconds, prerequisites (Linux/WSL2, Docker, containerlab, root-equivalent rights), platform limitations, and failure semantics. It also clarifies that INCONCLUSIVE and setup errors say nothing about the actual change and warns against weakening checks.

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 and return behavior, then layers in usage, prerequisites, and failure handling. It is somewhat long for a one-parameter tool and includes sibling-focused details such as dry-run duration and ping rationale, but most sentences still earn their 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?

Given one parameter, no annotations, and an output schema, the description supplies the missing operational context: prerequisites, usage policy, failure handling, retry limits, and escalation to record_baseline. Nothing critical for correct invocation appears 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 0% for the single required `path` parameter. The description identifies it as the location of netdryrun.yml, which adds some meaning beyond the bare schema, but it does not specify path format, whether relative paths are allowed, or file-existence expectations.

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 names the specific action (validate netdryrun.yml at path), what it does not do (without starting a lab), and what it is not (not a verdict; run dry_run next). This clearly distinguishes it from the dry_run sibling and tells an agent exactly what resource is being validated.

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 states when to use it: before proposing or applying any routing or policy change. It names alternatives and next steps: run dry_run next, and call record_baseline if no checks exist. It also gives clear stop/retry guidance for INCONCLUSIVE results.

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