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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description contributes the consumer relationship but says nothing about the shape of the returned list or whether the catalog is static or reflects loaded labs. With annotations carrying the safety profile, this is adequate but thin.

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 the resource first and the consumer hint in parentheses. Nothing is wasted and nothing essential is buried.

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 no output schema, this covers purpose, return content, and downstream use. The only gap is that an agent must guess how the returned generator names map to ios_generate's arguments.

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 to document and the baseline is 4. The description correctly implies the tool is argument-free and returns the parameter information an agent needs for the consumer tools.

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?

Specific verb+resource: 'List IOS config generators and their parameters'. The parenthetical naming ios_generate and pt_apply_feature anchors it as a discovery tool rather than a config producer, which distinguishes it from those siblings. It stops short of describing what the returned list looks like, but its role is unmistakable.

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 'used by ios_generate / pt_apply_feature' tells an agent exactly the workflow in which this tool belongs: fetch the parameter catalog before calling one of those two consumers. There are no explicit exclusions or a stated 'call this first' precondition, so it is clear context rather than a full when/when-not rule.

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

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

The annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description reinforces that no configuration is applied and points to ios_features for parameter discovery, but it does not describe validation behavior, error cases, or the exact return shape beyond 'config lines'.

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, uses two short sentences plus one compact example, and contains no filler. Every part contributes to understanding how to call the 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 generator tool with no output schema, the description explains that it produces config lines without applying them and delegates feature/param details to ios_features. It could be slightly more complete by clarifying the return format or validation behavior, but it is sufficient for correct invocation.

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. It does so by pointing to ios_features for valid feature names and params, and by giving a concrete example showing the feature string plus a feature-specific params object, though it does not enumerate all possible feature/param combinations.

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: generate IOS config lines for a feature without applying them. It also names ios_features as the source for feature names and parameters, and the 'without applying' wording distinguishes it from configuration-application 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?

It clearly directs the agent to use ios_features to discover valid feature names and params, and 'without applying them' implies preview/generation rather than mutation. It does not explicitly name the sibling apply tool or state exclusions, so it falls short of full when/when-not 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=true and openWorldHint=false, so safety is covered. The description adds meaningful operational context by disclosing that only the first 64 results are shown, which is behavior an agent would not otherwise know. It does not cover validation errors or conflict behavior, but the main behavioral limitation is 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?

A single front-loaded sentence with no wasted words. It states the action, the two modes, and the output truncation limit efficiently.

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-only split tool, the description covers the main modes and the 64-result truncation. But with no output schema and 0% parameter documentation, it leaves gaps around cidr format, parameter interaction/defaults, and the exact return shape beyond the truncation hint.

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. It partially does: 'count equal subnets' explains count, and '/new_prefix subnets' explains new_prefix, while 'or' implies mutual exclusivity. However, the cidr parameter's expected format and the behavior when both optional parameters are supplied or omitted remain undocumented.

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 ('split') and resource ('a block') and clarifies the two output modes: equal subnets by count or subnets by new prefix. This is clear enough to distinguish it broadly from subnetting siblings, though it does not explicitly name alternatives like net_subnet or net_vlsm.

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 'or' implies count and new_prefix are alternative modes, giving some usage guidance. However, there is no explicit when-to-use guidance versus sibling tools, no exclusions, and no explanation of which mode to prefer or what happens if neither optional parameter is provided.

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=true and openWorldHint=false, so the safety profile is covered and the bar is lower. The description adds that this is a pure derivation over an address/prefix, but says nothing about behavior on malformed or host-bit-set input (error vs. normalization) or output format, which matters for a calculator-like 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 the resource stated first and the returned fields enumerated compactly — no filler. It reads as a fragment, but every element earns its place and nothing is buried.

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 output schema, listing the returned fields is exactly the right compensatory move and covers most of what an agent needs to know about the result. The remaining gap is input expectations (CIDR syntax/validation) rather than output, which the 0% schema coverage leaves unaddressed.

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 0% for the single `cidr` parameter, so the description must carry the load. The phrase 'address/prefix' usefully implies the expected form (e.g. 192.168.0.0/24) and that a prefix length is bundled in, which is real added meaning, but it gives no example, no accepted range, and no note on whether a bare address with a separate mask is allowed.

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 clearly states the resource — subnet facts derived from an address/prefix — and enumerates exactly which facts (network, mask, wildcard, broadcast, host range, count, class). It does not name or contrast with sibling calculators like net_vlsm, net_summarize, or net_split, so an agent must infer that this is the per-subnet detail tool rather than the sizing/summarizing one.

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 or when-not-to-use guidance and no mention of the sibling tools in the same family. The agent gets no signal about choosing net_subnet over net_vlsm/net_split when handed a CIDR, nor any prerequisite such as valid CIDR formatting.

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 cover the safety profile (readOnly, closed-world), and the description adds real semantic context beyond them: it discloses that two distinct results come back (an exact collapsed set and one supernet) plus the redundant-coverage amount. It doesn't specify error behavior for invalid or non-contiguous input, which keeps it short of 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?

One compact sentence, front-loaded with the operation and followed by the payload it returns; the parenthetical earns its place by flagging the extra-coverage metric. It is telegraphic but free of 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?

With no output schema, the description does a fair job of explaining what is returned, so return-value documentation is adequate. The input contract is the weak point: with one undocumented parameter at 0% schema coverage, an agent still lacks the CIDR-string format needed to 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 0% and nothing in the description explains the single 'networks' parameter — notably that it expects a list of CIDR strings. The wording 'collapsed set' weakly implies a plural input, but format, ordering and contiguity expectations are undocumented.

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 (summarize) and resource (networks/routes) and describes the two outputs produced: the exact collapsed set and the single covering supernet with extra coverage. It is clear what the tool does, though it never names the adjacent subnet/VLSM/split siblings to mark the boundary.

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, when-not-to-use, or named alternative. The agent must infer from the word 'summarization' that it applies to aggregating multiple networks rather than splitting or allocating them, which is exactly the ambiguity the sibling tools net_subnet, net_split and net_vlsm create.

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=true and openWorldHint=false, so the safety profile is covered and the description earns credit for what annotations do not say: the exact return contents (subnet, mask, wildcard, gateway as first host, host range, broadcast per segment). That is genuinely useful because no output schema exists. It omits failure behavior when needs exceed the pool size, which is the main remaining gap for a mutation-free computation 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 compact statement front-loads the operation, followed by the algorithm and the return shape; no filler sentences. The density is close to cryptic in places (`needs = {...}` with no framing verb), but nothing is redundant.

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 output schema, listing the returned fields is the right compensation, and the `needs` example fills a real schema gap. Still missing: the required format for `pool`, behavior when the pool is too small for the requested segments, and any sense of output ordering beyond 'largest first'. Adequate but with clear gaps for a 2-parameter nested-input 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% across both required parameters, so the description has to compensate. The example `{'Sales': 50, 'Eng': 25, 'R1-R2': 2}` is genuinely valuable — it shows `needs` is a name-to-integer-host-count map, which is not obvious from `additionalProperties: {type: integer}`. However, `pool` is never explained (format such as CIDR, address range, or prefix), leaving half the parameters undocumented.

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 operation and resource: a VLSM (variable-length subnet mask) plan computed from a pool plus per-segment host requirements. The inline example of the `needs` shape makes the intent concrete. It stops short of naming or contrasting with siblings such as net_subnet / net_split / net_summarize, so an agent must infer the boundary from the 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?

'Largest first' describes the allocation algorithm, not when to choose this tool over net_subnet, net_split, or net_summarize. There is no statement of prerequisites (e.g., pool must be large enough), no exclusions, and no alternative routing. The agent gets the mechanics but not the selection criteria.

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

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

Annotations only declare openWorldHint=false; the description usefully adds that no Packet Tracer install is required and that the operation is reversible (both directions). It does not disclose whether dst is overwritten, whether the .pkt encryption is version-sensitive, or what happens on invalid input — relevant for a tool that writes a file.

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

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

A single front-loaded sentence that states the transformation and its key constraint immediately. No filler, no 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-path file-conversion tool with no output schema and near-zero annotation coverage, the description covers the core operation but omits path conventions, overwrite behavior, and any indication of error modes. Adequate to call correctly, not adequate to call confidently.

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 only parameter documentation is the bare names src and dst. The description hints at input/output formats but never states that src is the existing .pkt/.xml and dst the produced file, nor whether paths must be absolute or whether dst must not exist.

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 concrete verb (convert) and resource (.pkt <-> .xml), plus the differentiator that Packet Tracer isn't needed and which direction does what. An agent can tell this apart from pkt_inspect or pkt_export_configs by inference, but no sibling is named.

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 parenthetical implies the two use cases (decrypt to editable XML, re-encrypt to .pkt), so when to use it is derivable. However, there is no explicit exclusion or pointer to alternatives such as pkt_inspect for read-only inspection, leaving routing to inference.

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

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

The single openWorldHint annotation only says the tool stays local, so the description must carry the rest. It usefully discloses the side effect (files written to disk) and the exact output naming scheme <out_dir>/<device>.txt, but says nothing about overwriting existing files, whether out_dir is created, error handling, or 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 zero filler; every clause earns its place by naming the source, the operation, and the output pattern.

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 file-writing operation with no output schema, no descriptive parameter docs, and only a weak annotation, the description is too thin. It doesn't cover overwrite behavior, directory creation, or failure modes, which an agent needs before invoking a disk-mutating export.

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 0% – both 'path' and 'out_dir' have bare titles and no descriptions. The sentence partially compensates by implying path is the .pkt source file and out_dir is the destination directory, but it omits path format, relative-vs-absolute handling, and whether out_dir must pre-exist.

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: writes every device's running-config out of a .pkt file to per-device text files. An agent can tell this is an export operation distinct from pkt_inspect or pkt_convert, though no sibling is named.

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 pkt_inspect, pkt_convert, or pt_save_configs, and no prerequisites or exclusions are stated. The only context is implied by the verb 'Write'.

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=true, so safety is covered; the description adds genuinely new context — the file is parsed offline with no Packet Tracer running, and configs=true expands the payload to include every device's running-config. Minor gap: nothing about what happens with an invalid or missing file.

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 that front-load the action and file scope, then the output content, then the toggle, then the use case. No filler or repetition of 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?

With no output schema, the description correctly compensates by listing the returned data categories, and it covers the optional flag's effect. Somewhat thin on error/edge-case behavior for a file parser, but an agent has what it needs to invoke it.

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 carry the parameters. It explains the semantics of `configs=true` clearly (pulls every device's running-config) and `path` is self-evident from the file-type framing, though format expectations for path are not spelled out.

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 precise verb and resource ('Read a .pkt/.pka file') and enumerates what is extracted: devices, models, IPs, links, and running-configs. The 'WITHOUT Packet Tracer' clause cleanly separates it from the live-session siblings like pt_topology and pt_running_config.

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?

Names two motivating scenarios ('grading or understanding a lab file'), which implies when to use it. It never states when not to use it or explicitly names alternatives such as pkt_export_configs or pt_running_config for live devices, so routing is left to inference.

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 openWorldHint=false, so the description must carry the behavior load — and it does: auto-layout when x/y are omitted and the notable side effect that router/switch boot is skipped so they're immediately ready. It omits failure modes (duplicate names, invalid models) and whether a handle/id is returned for later use.

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 action and the payload shape, then supporting detail. The inline model list is long but justified since the schema provides no enum; a pointer to pt_catalog alone would have been tighter.

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 creation tool with no output schema and thin annotations, the description covers the payload, layout defaults, and the boot-skip side effect. Minor gaps: whether added devices are returned/identified, and error behavior on invalid model names.

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 0% and items are declared with additionalProperties and no property docs, so the description is doing all the work — it documents the object shape ({name, model, x?, y?}), which fields are optional, the model string format, and the consequence of omitting x/y. Only the semantics of `name` (uniqueness?) are left unstated.

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?

Starts with a specific verb+resource ("Add devices") and immediately enumerates supported model strings, which makes it distinguishable from pt_update_device and pt_delete_devices. It doesn't explicitly name those siblings, but the create semantics are unambiguous.

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?

Points at pt_catalog as the lookup for valid models, which is useful routing. However, it never states when to use this versus pt_update_device or pt_build, nor any preconditions such as whether the simulation must be started first.

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 openWorldHint=false, so the description carries the behavioral load and does so well: it discloses the disruptive side effect ("device is power-cycled automatically") and the return value ("the device's ports afterwards"). It does not cover failure modes, e.g. what happens if the module string is invalid or the slot is occupied.

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 action and the critical side effect in the first clause, then the example list that is genuinely necessary given opaque module identifiers. No filler sentences.

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 output schema, the description helpfully states what is returned, and it flags the power cycle. Remaining gaps are error/precondition behavior and the device identifier format, which matter for a mutation tool but are secondary given the strong module guidance.

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 0%, so the description must compensate and largely does: it explains the slot default behavior and supplies concrete, otherwise-unguessable values for module (HWIC-2T, NIM-2T, AC-POWER-SUPPLY, etc.). The device parameter is left unexplained — no hint about name format or whether the device must already exist.

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 ("Insert a module") into a device, and adds a concrete catalog of common module strings. It is clearly distinct from siblings like pt_device_modules (inspection) and pt_add_devices (creation), though it never names a sibling to reinforce that distinction.

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 module examples and the "slot omitted = first slot that accepts it" rule imply the intended usage, and the note that the device is power-cycled signals the operational cost. However, there is no explicit statement of when to use this versus pt_add_devices or pt_update_device, and no prerequisites or exclusions.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is clear. The description adds useful context about the size of the API surface and valid query forms, but it does not disclose result ordering, pagination/limit behavior, or return format.

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 no wasted language. The core search purpose is front-loaded, and the query examples are compact and directly useful.

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

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

For a read-only API search tool with no output schema, the description covers the main calling context and query forms. It is still missing enough about result shape and limit semantics that an agent might not know precisely what to expect from a search.

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. It explains the required query parameter well with class-name, method-fragment, and Class.method examples, but it does not explain the optional limit parameter beyond its schema default.

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 Packet Tracer's IPC/scripting API. It adds useful scope details (6000+ methods, 374 classes) and ties the tool to pt_run_js, though it does not explicitly contrast itself with other lookup or catalog 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 description implies the workflow: look up API details for use with pt_run_js, and it gives query examples. However, it does not explicitly say when to use this versus alternatives such as pt_catalog or pt_run_js directly, nor does it state any exclusions.

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

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

Annotations only declare openWorldHint=false, leaving the description to disclose mutation behavior. It indicates that config is applied to a device and that dry_run returns lines without applying, but it does not state persistence, reversibility, permission needs, or failure behavior for a mutating 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?

Three front-loaded sentences: purpose, example, and dry_run behavior. The example is slightly verbose but earns its place by illustrating the params structure. 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?

Given a mutating tool with 4 parameters, nested object, 0% schema coverage, and no output schema, the description should be more complete. It omits details about the device parameter, allowed feature values beyond a pointer, full params schema, and what applying actually returns or changes.

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. It provides an example for feature and params and explains dry_run behavior, but it does not describe the device parameter or exhaustively explain the nested params object. Partial but useful compensation.

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+resource: 'Generate IOS config for a feature ... and apply it to a device in one step.' It distinguishes from siblings by naming ios_features for feature discovery and by combining generation and application, which differentiates it from ios_generate. An agent can immediately tell what the tool does.

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 when to use it: to generate and apply config in one step, with a dry_run option for preview. It gives a concrete example but does not explicitly state when to avoid it or compare to alternatives like ios_generate + pt_cli. Clear context without exclusions.

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

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

Annotations only supply openWorldHint=false, so the description carries the load, and it does well: it discloses the subnet allocation rules (LANs from lan_pool, /30s for router-only links), address assignment order, DHCP behavior, overwrite semantics, and dry-run mode. It omits prerequisites (a live PT session/topology must exist) and whether overwrite clobbers host configs.

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 efficiently dense; nearly every clause carries information about allocation or toggles. It is a long, somewhat run-on block of parentheticals, but the density is justified for nine parameters.

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 nine-parameter, no-output-schema mutation tool, the description covers the bulk of decision-relevant behavior (allocation scheme, routing, dry run, overwrite). Gaps remain for dns, loopbacks, the routing enum, and required preconditions, which prevents a 5.

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 0%, so the description must compensate, and it explains most parameters: lan_pool, lan_prefix (/lan_prefix, right-sized when null), p2p_pool, dhcp, overwrite, and apply. It leaves dns and loopbacks entirely unexplained, and routing is only implied ('generate routing') without describing the enum options.

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 ('Address the live topology and generate routing') and immediately scopes it to computation 'from the actual cabling'. This clearly separates it from sibling tools like net_subnet/net_vlsm (offline calculators) and pt_configure_hosts.

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

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

Gives clear operational context: it works on the live topology, keeps existing addresses unless overwrite=true, and apply=false previews the plan and configs. It does not explicitly name alternatives or state when-not to use it (e.g. use net_subnet for planning without a live lab).

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 only openWorldHint=false in annotations, the description carries most of the burden and does add real behavior: ports auto-picked when omitted, configs applied and saved, `auto` invoking pt_auto_address after cabling, and checks executed only when verify=true. It never says whether an existing topology is cleared or appended to (pt_clear_canvas is a sibling, making this ambiguity material), nor what happens on partial failure — the main remaining gap.

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 dense spec block earns its space by encoding structure that the free-form schema cannot. Inline comments are terse and functional, though the block is heavy enough that the key behavioral note about pt_auto_address trails at the end rather than appearing where the `auto` key is defined.

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 high-complexity, nested-object tool with no output schema and near-zero annotation coverage, the spec shape is well conveyed but critical operating facts are absent: return value, whether the canvas is reset first, minimum viable spec (are devices/links required?), and failure/rollback semantics. An agent can construct a spec but cannot predict the side effects with confidence.

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 0% and spec is a free-form object with additionalProperties, so the description must do all the work — and it does, documenting six top-level spec keys with sub-field hints and `?` marking optional members (x?, y?, a_port?, b_port?). The only weak spots are that the verify parameter is only indirectly implied via 'run when verify=true' and no key is marked required.

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 is a specific verb plus resource with explicit scope — 'Build a whole network in one call' — which separates it from the incremental siblings pt_add_devices, pt_connect and pt_add_module. The spec block then enumerates exactly which artifacts it creates (devices, links, configs, hosts, addressing, checks), so an agent knows the full surface 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?

Usage is implied rather than stated: 'in one call' plus the presence of pt_add_devices/pt_connect as siblings suggests this is the batch alternative, but the description never says so explicitly or names a when-not condition. It does clarify the internal sequencing with pt_auto_address and the verify=true trigger for checks, which is useful, but the build-vs-incremental decision is left to inference.

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=true and openWorldHint=false, so safety is covered. The description usefully adds the return content (ports, slots, usage notes) and the modules flag behavior, but says nothing about output format, pagination, or whether an unfiltered call returns every model.

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 dense sentences with no filler, and the primary payload (model names for pt_add_devices) is front-loaded. The telegraphic enum dump is compact but readable.

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-param read-only catalog with no output schema, the description covers what is returned, the category vocabulary, and the modules switch. Only edge behavior (empty result, full unfiltered listing) is unaddressed, which is minor 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?

Schema coverage is 0%, so the description has to carry the parameters — and it largely does: it enumerates the category values (router | switch | l3-switch | host | firewall | ap | wireless-router) and explains that modules=true lists modules. That is substantial compensation for a bare schema; only the default behavior of modules=false is left implicit.

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 resource (device models offered by PT 9) plus what each entry contains: ports, slots, usage notes. It also ties itself to a sibling (pt_add_devices) as the source of exact names. It is not fully explicit that this is a read-only listing tool, but the intent is unambiguous.

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 parenthetical '(exact names for pt_add_devices)' implies the main use case — look up names before adding devices — but never says so directly, and no exclusions or alternatives (e.g. pt_device_modules, pt_add_module) are named. Usage is inferable 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?

The destructiveHint annotation already flags this as a destructive operation, but the description adds two things annotations don't: the blast radius is total (every device, not a subset) and a confirm=true flag must be supplied despite the schema marking no parameters required. It stops short of stating irreversibility or what the canvas looks like afterwards.

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 filler, with the blast radius front-loaded and the required precondition second. Nothing to trim and nothing buried.

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 destructive tool whose annotation already declares destructiveness and no output schema exists, this covers what an agent needs to invoke it safely. Minor gap: no statement of whether the wipe is recoverable or how it interacts with pt_save_configs before clearing.

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?

With one parameter and 0% schema description coverage, the description must carry the meaning, and it does: it tells the agent confirm=true is required, which is non-obvious given the schema declares confirm as optional with a default of false. It doesn't explain what confirm=false actually does (no-op, error, or prompt).

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 ("Delete") and resource ("EVERY device on the canvas"), and the emphasized "EVERY" makes the mass scope unambiguous. It does not name the sibling pt_delete_devices, but the capitalization of EVERY implicitly carves out the difference for a careful reader.

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 implied rather than stated: the agent can infer this is the nuclear option (wipe the whole canvas) and that confirm=true is a safety gate. However, it never explicitly says when to prefer pt_delete_devices instead, nor warns about what state is lost.

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?

Without meaningful annotations, the description carries the burden and does well: it discloses that config mode reports only failing lines (successes are silent), that sub-modes work and 'end' is auto-appended, that exec returns output, and that save=true appends 'write memory'. It omits whether config changes persist to startup-config without save, and what happens if the device is off or unnamed.

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

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

Three tight sentences; the core action is front-loaded and each clause adds operational detail (mode behavior, return semantics, save side-effect) 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?

No output schema and no annotations beyond openWorldHint, so the description has to cover everything. It handles mode semantics and the save side-effect but leaves the device identifier format and failure/error behavior underspecified for a 4-parameter command-execution 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%, so the description must compensate. It explains mode values, save's effect, and implies commands are individual lines, but the `device` parameter is never defined (name? ID? from pt_topology/pt_device?), and it doesn't resolve the string-vs-array ambiguity for `commands`.

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 IOS commands on a router/switch/ASA') and distinguishes the two modes. It also points to pt_show as the preferred tool for EXEC output, which separates it from at least one sibling. It doesn't clarify its boundary against higher-level siblings like pt_apply_feature or pt_configure_hosts.

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 per-mode guidance: mode=config enters lines from global config with 'end' appended, mode=exec returns output and should be avoided in favor of pt_show. That covers when to use each mode and names one alternative. No guidance on when to prefer this over the feature-specific 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?

readOnlyHint=true already declares this is a safe read, so the description's main added value is the 'oldest first' ordering — useful for interpreting results. It says nothing about whether the log is bounded per device, whether limit truncates from the oldest or newest end, or how far back history goes.

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 tight sentence, front-loaded with the core action and parenthetically anchored to the product concept. No wasted words, though it is arguably too sparse rather than too long.

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 output schema and 0% parameter coverage, the description leaves an agent guessing at the shape of returned commands, what device identifiers look like, and how `limit` interacts with the oldest-first ordering. For a 2-parameter retrieval tool this is under-specified.

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 carry the parameter burden — and it doesn't. 'any device CLI' faintly implies device filtering is optional, but neither `device` (name vs. ID, null meaning all) nor `limit` (default 40, truncation direction) is explained anywhere.

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: retrieving recent CLI commands from the command log, distinct from pt_cli (which executes them). The 'oldest first' ordering clarifies the read semantics. It stops short of naming a sibling, so it isn't a 5.

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 guidance on when to use this versus pt_cli, pt_show, or pt_running_config. An agent could reasonably confuse 'recent commands typed' with re-running or inspecting current commands via pt_cli, and nothing in the description disambiguates.

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

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

The only annotation is openWorldHint=false, so the description must carry the behavioral burden. It implies a configuration mutation but does not explain permissions, whether existing settings are replaced, error behavior for missing hosts, or what happens when dhcp is true alongside static IP 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?

The description is compact and front-loads the purpose before giving the hosts object shape. The dense pseudo-schema syntax is efficient, though it borders on cryptic for an agent that needs to parse field requirements.

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 tool with a single complex nested parameter, no output schema, and minimal annotations, the description is incomplete. It provides parameter shape hints but lacks usage context, behavioral effects, and return/error expectations needed to invoke it confidently.

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 0%, and the input schema exposes only an untyped hosts array, so the description adds substantial value by listing host fields and formats such as name, ip, mask/cidr alternatives, gateway, dns, dhcp, port, ipv6, and gw6. It still leaves some ambiguity around required fields and types, but it compensates well for the otherwise opaque 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?

The description identifies the resource and action context: configuring IP settings for PCs/laptops/servers/printers. The tool name supplies the verb, and the description clarifies the specific host-IP scope, though it does not explicitly distinguish this from siblings like pt_auto_address or pt_update_device.

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 no explicit guidance on when to use this tool versus alternatives such as pt_auto_address, pt_update_device, or pt_apply_feature. Usage is only implied by the phrase 'IP settings for PCs/laptops/servers/printers.'

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

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

The description adds useful behavior beyond the minimal openWorldHint annotation: port auto-selection is fastest-first, switch uplinks can be preserved with a_pref/b_pref='access', and cable defaults to auto. However, it does not disclose important mutation behavior such as whether existing links are overwritten, what happens on port conflict, or whether the operation is reversible.

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 compact and front-loaded: 'Cable devices. links: [{...}]' comes first, followed by port selection behavior, cable types, and the serial module prerequisite. Every sentence contributes operational detail without unnecessary prose.

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 mutation-like role, nested undocumented link objects, no output schema, and minimal annotations, the description covers enough to attempt a call but omits key context: what a/b identify, error behavior, conflict handling, and return/result expectations. It is adequate but incomplete for reliable invocation.

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?

With 0% schema description coverage and a nested links object, the description must compensate, and it substantially does: it documents the link object fields a, b, a_port, b_port, cable, mentions a_pref/b_pref, lists cable enum values, and explains port auto-selection. It still leaves the meaning of a and b implicit and does not fully formalize all nested 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?

The description clearly states the specific action and resource: 'Cable devices' with a links array. It is distinct from pt_disconnect and pt_add_devices in practice, but it does not explicitly mention sibling alternatives except pt_add_module as a serial prerequisite.

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 implied by the action and by details about optional ports and cable defaults, but there is no explicit statement of when to use this tool versus pt_disconnect, pt_add_devices, or other topology tools. The only sibling reference is a prerequisite for serial links needing pt_add_module.

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 destructiveHint=true, so the agent knows this is a destructive operation. The description adds valuable context that cables are also deleted, which is beyond the annotation. However, it does not state irreversibility, permission requirements, or what happens if a named device does not exist.

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 zero waste. It states the action and the key side effect immediately.

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 operation with no output schema and an undocumented required parameter, the description is too sparse. It should clarify irreversibility, cable deletion scope, and behavior for invalid or missing device names.

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?

There is one required parameter ('names') with 0% schema description coverage, so the description must compensate but does not. It does not explain whether names refer to device names, whether multiple devices can be deleted, matching behavior, or error handling for missing names.

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

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

The description uses a specific verb and resource ('Delete devices') and clarifies scope with '(and their cables).' This clearly distinguishes it from siblings like pt_add_devices and pt_update_device, though it does not name alternatives 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 tool versus alternatives such as pt_update_device, pt_clear_canvas, or pt_remove? No prerequisites or warnings are stated. The usage is only implied by the verb 'Delete'.

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

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

The readOnlyHint and openWorldHint annotations already establish the safety profile. The description adds useful context about what data is returned (IP, peer, state, switchport mode, free ports, module slots), but does not describe output shape, invalid-name behavior, or error handling.

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 important scope and return contents are presented immediately.

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-parameter read tool, annotations cover safety and the description lists the returned data categories. However, with no output schema, it still leaves the parameter meaning and exact return structure under-specified.

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 description never explains the sole required parameter, name. It is clear that a device must be identified, but the description adds no semantic detail about name format or matching behavior, and so does not compensate for the schema 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?

The description clearly identifies a single-device inspection tool and enumerates the main return categories: physical ports, free ports, and module slots. It is specific enough to distinguish from broad topology/show tools, though it never states the verb explicitly and does not call out the nearby pt_device_modules sibling.

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 implies usage by saying 'One device in depth', but gives no explicit guidance on when to use this instead of pt_device_modules, pt_topology, pt_show, or pt_running_config. There are no alternatives or exclusion conditions named.

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=true and openWorldHint=false, so the safety profile is covered. The description adds what the result contains (slot path, type, installed module), which is useful since there is no output schema, but says nothing about how the tree is shaped or whether empty slots appear.

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 compact sentence fragment with the resource front-loaded and no filler. It is terse to the point of being a noun phrase rather than an explanation, but 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 output schema, the description must carry return-value meaning, and it lists the fields but not their structure or format. It also leaves the lone parameter's expected value unspecified, so an agent could still call it incorrectly.

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 `device` parameter, and the description only alludes to it via 'of a device'. It does not say whether this is a device name, ID, or label, or how to obtain one (presumably from pt_device).

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 resource — the module slot tree of a device — and enumerates the returned fields (slot path, slot type, installed module). It is clearly distinct from siblings like pt_add_module (mutation) or pt_device (device-level info), though it does not explicitly say so.

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 statement of when to use this tool versus pt_device, pt_topology, or pt_running_config, and no prerequisites or exclusions. The read-only inspection use case is only implied by the noun phrase.

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?

Read-only annotation is consistent, and the description adds real behavioral value by disclosing the checks performed and that deep mode reads every router's routing table. It doesn't warn about cost/latency of deep mode on large topologies, which is the main missing behavioral note.

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 core purpose, then the enumerated checks, then the optional deep mode. Every clause adds information; nothing 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?

There is no output schema, and the description implies findings are returned per issue but doesn't say whether results are grouped by device, counted, or how severities are represented. Given the tool's diagnostic nature, a brief note on return shape would round it 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 coverage is 0% and the schema only says 'deep' is a boolean defaulting to false. The description fully compensates by explaining exactly what deep=true adds (routing-table reads plus unreachable-subnet listing) versus the default shallow check set.

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 ('Find misconfigurations from the live state') and enumerates the exact fault classes it detects (duplicate IPs, mixed subnets, missing gateway, cabled-but-down interfaces, powered-off devices). This clearly separates it from siblings like pt_status or pt_topology, which report state rather than diagnose faults.

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

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

Usage context is clear: it operates on live state, and the deep=true mode is explicitly described as an escalation that adds routing-table reachability analysis. It doesn't explicitly name alternatives (e.g. pt_running_config for config-based checks) or state when not to use it, so it falls 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?

Annotations already declare destructiveHint=true and openWorldHint=false, so the safety profile is covered; the description usefully confirms that what is destroyed is a cable between endpoints. It says nothing about reversibility, what happens to the link state on both devices, or behavior with an unknown port, which would be the value-add for a destructive mutation.

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 sentence with the operation front-loaded and the example inline; nothing is wasted. It is arguably too terse for a destructive tool, but structure and sizing are sound.

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 destructive tool with no output schema and annotations covering the safety profile, the essentials are present. Missing are the one-vs-both-endpoint rule and failure behavior on invalid ports, both of which an agent needs to call this 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 coverage is 0%, so the description must carry the parameter, and the example does teach the "device:interface" string format that the bare string-array schema omits. However, it never says whether one endpoint or both ends of the link must be listed, which is the single most consequential ambiguity for this call.

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 ("Remove cables by endpoint") and the example makes clear it operates on links between device interfaces. It is implicitly distinguishable from pt_connect, 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?

Usage is only implied: an agent infers this is for tearing down existing links, with pt_connect as the obvious counterpart. There is no explicit when/when-not statement, no prerequisite about devices being stopped, and no guidance on erroring on nonexistent links.

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 openWorldHint=false, so the description carries the full disclosure burden and does not meet it. It does not say whether this mutates lab state, whether it is reversible, whether it blocks, or what happens when the clock is already advanced — all relevant for a time-manipulation 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?

A single front-loaded sentence with zero filler; the core action comes first and the parenthetical adds useful scope 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?

With no output schema, near-empty annotations, and an undocumented parameter, the description leaves key gaps: what 'times' controls, what state changes occur, and what the tool returns. Adequate for identifying the tool, insufficient for calling it confidently.

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?

There is one parameter ('times') with 0% schema description coverage, and the description never mentions it. An agent cannot tell whether 'times' means seconds, a multiplier, or a repeat count, which directly affects invocation correctness.

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 ('Fast-forward') and resource ('PT's realtime clock') plus a parenthetical naming the concrete effects (STP, OSPF/EIGRP convergence, DHCP). No sibling tool does anything comparable, so it is clearly distinguishable. Minor ambiguity remains about whether the 'realtime clock' is the simulation clock or a device clock.

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 mention of STP/OSPF/EIGRP convergence and DHCP implies the use case (avoiding long protocol timers in a lab), but there is no explicit when-to-use statement, no prerequisites, and no named alternative (e.g., pt_simulation) for advancing time differently.

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

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

The description adds useful scope by saying operations apply to the open workspace and that files use the .pkt extension. However, annotations are minimal and the description omits important behavior: whether save overwrites, whether unsaved work is lost on new/open, and what errors occur if no file is open.

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 that front-loads the resource and then the action set. 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 two-parameter tool with no output schema, the description covers the essential action set. It still leaves key invocation details ambiguous, especially path requirements and overwrite behavior, which matter for correct calls.

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. It maps the action enum values and notes the .pkt extension and path usage for open/save_as, but does not clarify that path is required for open and save_as and ignored for new/save.

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 ("file operations on the open workspace") and enumerates the supported actions, which clearly distinguishes it from topology, device, and CLI siblings. It stops short of a fully precise purpose statement because "file operations" is somewhat generic.

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 action list implies when to use each operation, but there is no explicit guidance on prerequisites, when not to use this tool, or how it relates to siblings like pkt_convert or pkt_export_configs. An agent can infer usage but must make assumptions.

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

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

The description explains that verify=true pings test pairs after convergence, which is useful behavioral context beyond the openWorldHint annotation. But for a lab-building mutation tool with no readOnly/destructive annotations, it omits important behavior such as what clear_first does, whether existing lab state is overwritten, and what happens on conflicts.

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 action and is dense with useful detail. The blueprint list is long but directly supports tool selection and parameter use, with no filler sentences.

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 lab-construction tool with no output schema and 0% schema description coverage, the description leaves key gaps: clear_first behavior, params syntax, and what happens to any existing lab. It provides enough to understand the high-level purpose but not enough to invoke the tool safely and correctly in all cases.

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 carry parameter meaning. It explains name='list' and lists blueprints, and explains verify=true, but it does not explain the params object structure or the clear_first parameter at all, leaving two of four parameters underspecified.

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

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

The description uses a specific verb and resource: 'Build a complete, pre-computed lab' and enumerates what is included (devices, cabling, IPs, configs, hosts, test pairs). The 'in one call' phrasing helps distinguish it from granular sibling tools, but it does not explicitly name or contrast with alternatives such as pt_build.

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 useful usage details for name='list' and verify=true, and implies the tool is for creating complete labs in one call. However, it does not state when to use this instead of pt_build or the more granular device/connection tools, nor does it mention exclusions or prerequisites.

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 mark this as read-only, and the description adds meaningful behavioral detail: it reports OK/PARTIAL/FAIL per pair, runs pairs from different sources in parallel, and explains first-ping loss as ARP warm-up mitigated by count>=2. It does not clarify non-ARP failure semantics or output details, but the added context is substantial.

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 action and output, then provides pair format, source behavior, and a practical caveat. Every sentence adds useful information without wasting space.

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

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

For a read-only ping tool with no output schema and minimal annotations, the description covers what the tool does, how pairs are specified, source types, parallel behavior, and the count/ARP caveat. It could say more about the meaning of PARTIAL or failure modes, but it is largely complete for invocation.

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?

With 0% schema description coverage, the description compensates well by defining pairs as [[src, dst], ...], explaining dst as a device name or IP, and clarifying source types. It also explains the effect of the count parameter via the ARP warm-up note, though it does not restate the default value.

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 clearly states a specific verb and resource: ping from devices and report status per pair. It explains source types and pair structure, but does not explicitly distinguish this tool from the sibling pt_ping_matrix.

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 useful usage context such as source types, parallel execution across different sources, and the ARP warm-up caveat. However, it does not say when to use this instead of alternatives like pt_ping_matrix, pt_traceroute, or pt_diagnose.

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=true and openWorldHint=false, so the safety profile is covered. The description adds useful context about default host selection and output being a matrix, but it does not explain what the matrix values represent, timeouts, or how the count parameter affects 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?

The description is a single front-loaded sentence with no wasted words. It communicates the core operation, default scope, and limit efficiently.

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 diagnostic tool with two parameters and no output schema, the description covers the main idea but leaves out important details: what the matrix contains, parameter semantics for count, and practical output expectations. It is adequate but incomplete.

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. It adds some meaning for the hosts parameter by stating the default set and max of 10, but it never mentions the count parameter or host string format, leaving half of the parameters undocumented.

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 clearly states the operation: computing all-pairs reachability between end hosts and returning a matrix. It is distinguishable from the single-target sibling pt_ping by its all-pairs/matrix scope, but it does not explicitly name or compare against that sibling.

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 provides a default host scope and a maximum of 10 hosts, which are useful constraints, but gives no explicit guidance on when to use this tool versus pt_ping, pt_diagnose, or other connectivity 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 supply openWorldHint=false, so the description carries most of the burden. It usefully discloses the execution model ("the code is a function body: use `return`"), the return format (JSON result), and the available global namespaces — real value beyond the annotations. It does not disclose side-effect profile (whether arbitrary JS can mutate lab state), sandboxing/security constraints, or what happens on timeout, which matters for an arbitrary-code-execution 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?

Front-loaded with the purpose and the escape-hatch caveat, then the calling convention, then the globals and a worked example. Every sentence carries information an agent needs to author a correct call; 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?

There is no output schema, but the description states it returns a JSON result, and the execution contract (function body, return, globals) is spelled out. The globals list ends in "...", leaving the full API surface undiscoverable from the description alone, and timeout behavior is absent — minor gaps for an escape-hatch tool that has a dedicated API-discovery 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 description coverage is 0%, so the description must compensate, and it does so strongly for `code`: function-body semantics, `return` requirement, global namespaces with callable examples, and a concrete usage example. The second parameter, `timeout` (default 60), is never mentioned — no units, no behavior on expiry — leaving one of two parameters undocumented in both schema and description.

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 JavaScript inside PT's script engine and return the JSON result") and frames itself as an "escape hatch," which immediately positions it against the many structured siblings like pt_cli, pt_device, and pt_topology. An agent can identify what this does and why it differs from the purpose-built tools 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?

"Escape hatch" clearly signals this is the fallback for operations the structured tools don't cover, and the example shows the intended granular-object idiom. However, it never explicitly says to prefer dedicated tools first or names which sibling to reach for instead, so the routing 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, and the description adds genuine behavioral context: the config is read from the device model, is fast, and involves no paging. That clarifies the read path 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?

Two tight sentences, front-loaded with the core purpose, no wasted wording. The section clarification is appropriately placed as a second sentence.

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 3-param read tool with no output schema and covering annotations, the description supplies enough to call it correctly: what it returns (config text), the model-read behavior, and how to filter by section. Only minor gaps remain (explicit startup 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?

Schema coverage is 0%, so the description must compensate. It explains 'section' thoroughly with concrete examples and its parenthetical '(or startup)' maps to the startup flag; 'device' is self-evident. This largely fills the schema gap, though startup is only implied rather than stated directly.

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 resource (running/startup config of an IOS device) and how it is retrieved (read from the device model). It is clear enough to distinguish from generic CLI tools, though it doesn't explicitly name a sibling like pt_show.

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 'fast, no paging' implies this is preferable to a paged CLI read, but no alternative tool is named and no explicit when-to-use/when-not is given. Usage is only inferable.

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 only openWorldHint=false in annotations, the description carries the behavioral burden. 'Write memory' implies a persistent write/save operation, but it does not explicitly say that running config is saved to startup config, whether the change is persistent across reloads, how failures are reported, or what confirmation is returned.

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. Its brevity is appropriate, though the use of 'write memory' as shorthand trades clarity for concision.

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 mutation tool with sparse annotations and no output schema, the definition is under-specified. It covers the optional devices parameter and default scope, but it does not explain what save semantics mean, what happens on failure, or what the tool returns to confirm success.

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. It does add meaning by stating the parameter is 'given (default: all) routers/switches,' which clarifies the default and target type, but it does not specify device identifier format, how null differs from an empty array, or whether names versus addresses 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 action ('write memory') and target ('routers/switches'), and the tool name clarifies the resource is configs. It is clear enough to distinguish saving configs from sibling tools like pt_running_config or pkt_export_configs, though the CLI jargon 'write memory' is less explicit than 'save running configuration to startup configuration'.

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 says the action applies to the given devices or all devices by default, which gives useful scope. However, it provides no guidance on when to use this instead of alternatives such as pt_running_config, pkt_export_configs, or pt_file, and gives no prerequisites or exclusions.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety and locality are covered. The description adds useful scope by specifying that the image is of the logical workspace as drawn in PT, but it does not disclose what the capture includes (labels, device states, annotations) or whether it reflects simulation state. For a read-only image tool under annotations, this is adequate but not rich.

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 short sentence with no filler, and the key scope (logical workspace, as drawn in PT) is front-loaded. It could be slightly more informative without becoming bloated, but it is appropriately sized.

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-only screenshot tool with one optional enum parameter and no output schema, the description communicates the core return type (an image) and scope. However, it omits what the image contains, whether the canvas must be in a particular state, and anything about the fmt parameter, leaving some gaps for an agent deciding whether the tool is appropriate.

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 description does not mention the sole fmt parameter at all. While the enum values PNG and JPG are self-explanatory from the schema, the description adds no meaning about format behavior, defaults, or acceptable values.

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 clearly identifies the resource and output: an image of the logical workspace/topology as drawn in PT. This implicitly distinguishes it from pt_topology, which likely returns topology data rather than a rendered image. The phrasing is nominal rather than a verb, but the operation (capture screenshot) is unambiguous.

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

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

There is no explicit guidance on when to use this tool versus alternatives like pt_topology or pkt_export_configs. The implied use case (needing a visual capture of the current logical workspace) is understandable from the description, but no exclusions, prerequisites, or alternative routes 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds genuinely new context: the setup is one-time and PT-side, and the condition that makes it relevant. Minor gap: it doesn't say whether the output is human-readable text or structured steps, but for a zero-param read-only tool this is largely implied.

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 sentence with the purpose front-loaded and the conditional trigger appended in parentheses. Every clause carries information; nothing is redundant.

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 no-input, read-only, no-output-schema helper, the description covers what it produces and when it is needed. The only missing piece is the shape of the return (steps vs link vs prose), which is low stakes 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 takes no parameters, so the baseline is 4. Nothing in the description needs to compensate for schema coverage, which is reported at 100% for an empty object.

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 resource and intent: instructions for installing the one-time PT-side bridge module. An agent can tell this is a documentation/help tool rather than a mutation tool, though the verb is implicit ('How to install') rather than an explicit 'returns instructions for'. Sibling differentiation comes via the reference to pt_status rather than a direct contrast.

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 triggering condition: use it when pt_status reports NOT CONNECTED. That is a concrete when-to-use rule tied to a named sibling. It stops short of stating when not to use it (e.g., when already connected) or what to do after following the instructions.

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=true and openWorldHint=false, and the description usefully adds that execution is at privileged EXEC level (not config mode) and that output is returned. It does not say whether multiple commands share one session, whether output is truncated, or how device errors/timeouts surface, which matters for an open-ended command runner.

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 lines, front-loaded with the verb and resource, then parameter notes. Compact and waste-free, though the fragmentary 'commands:' / 'grep:' lines read as loose notes rather than a structured 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?

There is no output schema, so the description should carry more: the 'device' identifier format is undocumented, and nothing is said about failure modes (unreachable device, invalid command) or output size limits. For a 3-parameter tool with 0% schema coverage, this is adequate but leaves real 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?

Schema description coverage is 0%, so the description carries the load: it explains 'commands' (one or more, with examples) and 'grep' (optional regex, line-filtering like '| include') well. However, the required 'device' parameter gets no explanation at all — no hint whether it is a topology name, hostname, or ID — leaving a required parameter undefined.

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 ('Run show/exec commands') and resource (privileged EXEC on a router/switch) plus the return behavior. It clearly separates itself from config-mode tools by naming 'privileged EXEC', though it does not name a sibling like pt_cli or pt_running_config to disambiguate further.

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

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

Usage is only implied: the examples ('show ip interface brief', 'show ip route') and the '| include'-style grep hint tell an agent the intended shape, but there is no explicit statement of when to prefer this over pt_cli, pt_running_config, or pt_diagnose, and 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 only openWorldHint=false in annotations, the description carries most of the disclosure burden. It says what actions exist, but not what side effects occur, whether 'reset' is destructive, what state changes happen when switching simulation/realtime mode, or what any action returns.

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 compact and front-loads the tool's purpose before the action list. It contains no filler, though the dense action enumeration and abbreviations like 'src->dst' make it slightly cryptic.

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 simulation-control tool with no output schema and sparse annotations, the description is too thin. It lists actions but omits prerequisites, side effects of reset or mode changes, output behavior, and conditional parameter rules needed to invoke 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 0%, so the description must compensate. It usefully explains action values and ties src/dst to 'pdu' and steps to 'forward/back', but it does not document required/conditional parameter combinations, defaults such as steps=1, or accepted string formats for src/dst.

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 clear control purpose ('Simulation mode control') and enumerates specific actions: switch mode, send PDU, step events, reset, list frames, status. It does not differentiate itself from siblings like pt_fast_forward, pt_ping, or pt_traceroute, but the action list makes the tool's scope understandable.

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 lists available actions but gives no guidance on when to use this tool versus alternatives such as pt_fast_forward or pt_ping. There are no exclusions, prerequisites, or conditions that select one action over another.

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=true and openWorldHint=false, so the safety profile is covered. The description adds useful behavioral context by enumerating the status information returned, though it does not specify output format or freshness of the status data.

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

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

A single, front-loaded sentence that lists the returned status fields with no wasted words. It is appropriately sized for a simple status 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, read-only status tool with annotations covering safety, the description gives enough information about what is returned. It lacks an output schema and does not describe the exact response shape, but it remains sufficient for an agent to understand the tool's purpose.

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 explain. The baseline for a parameterless tool is 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 names a specific resource (Bridge + Packet Tracer status) and lists the status fields returned: connection, PT version, open file, and device/link counts. It is clear what the tool does, but it does not differentiate itself from sibling inspection tools such as pt_topology or pt_file.

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 does not say when to use this tool versus alternatives like pt_topology, pt_file, or pt_device. Usage is only implied by the word 'status', with no explicit when-to-use or when-not-to-use 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=true and openWorldHint=false, so safety is covered; the description adds genuine value by enumerating exactly what the compact payload contains and what detail=true layers on (MACs, switchport modes, descriptions, unused ports). It does not mention behavior with no active canvas or payload size, but the cost/benefit of the detail flag is clearly 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?

Two dense sentences, zero filler, with the payload contents front-loaded before the detail-flag modifier. Every clause maps to something an agent needs.

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 output schema, the description bears the return-value burden and largely discharges it by naming the fields returned at each detail level. Minor gaps remain around error/empty-canvas behavior and payload size, which matter for a whole-canvas dump.

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 0%, so the description must carry the single parameter, and it does: detail=false is the compact default, detail=true adds MACs, switchport modes, descriptions and unused ports. Only the exact output shape of the added fields is left unspecified.

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 retrieval over a specific resource: the whole canvas, with every device's model, position, power, interfaces, peers and link state. The 'whole canvas' scope implicitly separates it from siblings like pt_device (single device) and pt_running_config, 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?

Usage is only implied: 'whole canvas, compact' suggests an overview call and detail=true suggests a deeper inspection. There is no explicit statement of when to prefer this over pt_device, pt_show, or pt_status, and no exclusions or preconditions 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds that it 'returns the hop list', which is useful output context, but says nothing about prerequisites, expected runtime, or failure behavior for a path that may traverse unstarted devices.

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 the verb first, a helpful platform alias in parentheses, and the return value appended. 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 two-parameter read-only diagnostic, the description covers purpose, endpoints, and return value. It omits operational context such as whether the simulation must be started or how device names are resolved, which is a meaningful gap given no output schema and no parameter descriptions.

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 0%, so the description must compensate. It does explain that src is a device and dst can be a device name or IP, which maps meaning onto both parameters, but it doesn't specify the expected format or naming for src beyond 'device'.

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 ('Traceroute ... from a device to a device name or IP') and even clarifies the host-side alias (tracert). It does not explicitly differentiate itself from the sibling pt_ping or pt_diagnose, so it falls short of a 5.

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 traceroute versus pt_ping, pt_ping_matrix, or pt_diagnose, and no stated prerequisites (e.g. devices must exist or be powered on). 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?

The only annotation is openWorldHint=false, so the description carries nearly the full behavioral burden. It implies a mutation but does not state what happens when optional fields are omitted, whether the operation is partial or full replacement, permission requirements, or what the response contains. For a mutating tool with sparse annotations, this is a significant gap.

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 sentence that front-loads the key verbs and resource. It is efficient, though its brevity is partly achieved by omitting necessary detail rather than by careful editing.

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?

This is a five-parameter mutation tool with no output schema and only an openWorldHint annotation. The description does not cover null-default behavior, partial update semantics, or side effects, leaving the agent under-informed about how to 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 0%, so the description must compensate for five undocumented parameters. It loosely maps rename to new_name, move to x/y, and power to the power flag, but does not explain null defaults, coordinate semantics, whether name is the current identifier, or what happens to position when x/y are omitted.

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 specific verbs (rename, move, power on/off) and a clear resource (a device), so the agent can tell it modifies an existing device rather than adding or deleting one. It distinguishes reasonably from siblings like pt_add_devices and pt_delete_devices, though it doesn't name alternatives.

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 pt_add_devices, pt_delete_devices, or pt_device. No exclusions, prerequisites, or alternative routes are mentioned.

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