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

With no annotations, the description carries the full burden and excels. It explains the underlying XML persistence mechanism, discloses exactly what is returned and what is flagged, and prominently highlights critical limitations: block-to-block wiring and setting values are not recoverable, and absence of output is not proof of absence.

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?

While longer than one sentence, every sentence adds value. The description is front-loaded with the core purpose, followed by mechanism, outputs, flags, and limits in a logical, readable structure with no redundant content.

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?

Despite having an output schema, the description adds essential context: when to use it, what it cannot recover, and what its output can be used for. It is complete for a read-only analysis tool, addressing caveats and providing enough context for an agent to invoke it appropriately.

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 mentions that ACT signals are part of the output (hinting at include_signals) and the path is implied by 'out of a .apcmp archive.' However, it does not explicitly explain the effect of setting include_signals to false or describe the expected path format, leaving some ambiguity.

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

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

The description opens with a specific verb and resource: 'Read a project's ACT application logic out of a .apcmp archive without importing it.' This clearly states what the tool does and distinguishes it from siblings like apcmp_summary by focusing on ACT logic extraction rather than a general archive summary.

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 provides clear context for use: review logic without needing an import, especially when the connectivity package is missing. It also includes exclusions ('Use it for review, not as a substitute for opening the project') and limitations, but does not explicitly compare to alternative 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?

With no annotations provided, the description carries full behavioral burden and it succeeds: it states it reads only metadata sidecars, cannot access SQL Server engineering data inside the archive, and that no import occurs. It also discloses the risk of silent IED loss on import, which is critical operational context.

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

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

Four paragraph breaks, front-loaded with the core purpose, then usage guidance, then limitations. Every sentence adds value — no filler, efficient and well-organized for an agent to quickly extract actionable intent.

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 inspection tool with an output schema present, the description is complete: it covers purpose, when to use, tool limits (metadata only), and the key safety warning about import behavior. The presence of an output schema satisfies return-value documentation.

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 sole parameter 'path' is undocumented. However, the description clearly implies 'path' is the .apcmp archive file location through context, and for a single self-evident parameter with high-context prose, the schema baseline of 3 is appropriate. The description doesn't add literal param syntax details but the context strongly conveys meaning.

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 tool inspects a PCM600 .apcmp project archive without importing it, reports the project name, IED inventory, and connectivity package availability. This is specific and distinguishes it from sibling tools like pcm_import_ied or scl_summary, which operate on different resources/formats.

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

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

Explicitly instructs to run BEFORE importing any .apcmp and explains why (PCM600 silently discards IEDs with unrecognized object types when connectivity packages are missing). This provides clear when-to-use guidance and warning context, exceeding what's needed for a 1-parameter tool.

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

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

With no annotations provided, the description carries full burden for behavioral disclosure. It explains that the tool runs `export-system-info` (a read/health-check operation), and additionally reveals it lists installed connectivity packages that 'bound what IED types can be handled at all,' giving the agent useful insight into the tool's side effects and their strategic meaning. This is solid non-obvious context beyond what a bare invocation would suggest.

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

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

Three sentences, tight and front-loaded with the core purpose. The second and third sentences add meaningful context (health-check role, connectivity packages). Minor inefficiency: the third sentence about connectivity packages could arguably be merged, but overall it's economical with no redundant 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?

Has an output schema, so return values needn't be documented in the description. The tool is a simple parameterless probe with clear purpose, and the description covers its functional role plus the strategic implication of connectivity packages. Complete enough for an agent to decide when to call it. Could optionally mention what the output-format looks like, but the output schema handles that.

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

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

The tool has zero parameters, making parameter semantics largely moot. With no params to document, a baseline of 4 is appropriate since there's nothing the description needs to clarify about arguments; the description focuses its effort on purpose and behavior instead.

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 tool reports detected PCM600 installation and proves CLI reachability by running the project-free `export-system-info` command. It distinguishes this from sibling tools by emphasizing it's the 'only command that needs no project,' clearly separating it from the many pcm_export_*/pcm_import_* siblings that require project context.

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 explicitly notes this doubles as a health check and is the only no-project command, which implicitly signals when to use it (before any project-based PCM operations). It doesn't explicitly name alternative tools or state when NOT to use it, but the contrast with project-requiring siblings is strongly implied through the project-free framing.

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

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

No annotations are provided, so the description carries the full burden. It explicitly discloses 'Read-only; no relay contact' — a valuable behavioral trait indicating this tool does not mutate the device or relay. It also adds context that no technical key is needed. This is meaningful behavioral disclosure beyond what any annotation would provide.

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 three sentences, with the core purpose front-loaded in sentence one. Sentences two and three add meaningful context (no technical key, discovery use case, read-only behavior). No wasted words, 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?

The tool has an output schema (so return value explanation isn't needed), moderate complexity with 3 params, and the description covers discovery use case, permissions behavior, and purpose. It's reasonably complete for the given complexity. The main gap is parameter guidance, but the two required params are self-explanatory from 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 description coverage is 0%, and the description adds zero parameter-level detail. `project` and `out_dir` are self-evident from their names, and `overwrite` with default false is fairly clear, but the description doesn't explain the expected format of out_dir, whether overwrite replaces individual files, or any constraints. With 0% coverage, the description needed to compensate and didn't.

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?

Description clearly states it exports `.xrio` parameter files for every IED in a project into one directory. The verb `export` + resource `parameter files` + scope `every IED in a project` is specific. However, it doesn't distinguish itself from siblings like `pcm_export_parameters` or `pcm_export_ied`, though the `bulk` and `every IED` phrasing partially implies the 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 description notes 'Needs no technical key, which makes it the easiest way to discover what IEDs a project holds and what their keys are.' This gives implied usage context (good for discovery). However, it doesn't explicitly say when to use this vs `pcm_export_parameters` (single) or other export variants, nor when NOT to use it.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. While it does state 'Read-only; no relay contact' which is useful safety context, it doesn't disclose what the tool actually reads from (the source), whether the .apcmi file is platform-specific, what the 'overwrite' parameter does behaviorally, or what the output schema will return. For an export tool with zero annotation coverage, this is a meaningful 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?

Two short sentences with zero wasted words. The description front-loads the core purpose and immediately adds the read-only safety qualifier. Highly efficient.

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 relatively simple file-export tool with an output schema present, the description covers the core intent. However, given zero annotations, absence of any parameter guidance, no description of the overwrite flag behavior, and no mention of when to use this vs pcm_export_scd/project, there is room for more. It's adequate but leaves gaps for a read-only operation tool with no safety annotations.

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

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

Schema description coverage is 0%, meaning the description adds no parameter-level detail. With 4 parameters and 3 required, the description doesn't explain what 'project', 'technical_key', or 'out_path' mean, nor does it clarify the 'overwrite' default behavior. The parameter names are somewhat self-explanatory ('technical_key' likely identifies the IED), but the description adds nothing beyond what the schema shows, so baseline 3 is appropriate.

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

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

The description states a specific verb (Export), resource (a single IED), and output format (.apcmi file). It clearly distinguishes from siblings like pcm_export_scd, pcm_export_project, and pcm_export_parameters, which export different entities, and pcm_import_ied which is the inverse operation.

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 this is for exporting single IEDs as opposed to the sibling export tools for SCD, parameters, or the whole project. However, it doesn't explicitly state when to choose this over alternatives or mention prerequisites (e.g., having a valid project/technical_key). The read-only note implies safe usage, but no explicit exclusions are given.

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

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

With no annotations provided, the description carries the full behavioral disclosure burden. It does disclose read-only status and notes the file format is chosen by suffix, plus the critical technical_key vs SCL name distinction. However, it doesn't describe what happens on overwrite conflicts (despite an overwrite parameter), output format details, or failure modes.

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

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

The description is compact, using a bolded emphasis on the key clarification. Every sentence adds value: the suffix-driven format choice, the technical_key clarification with example, and the read-only safety note. 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?

The tool has 4 params (3 required), no annotations, and an output schema present. The description covers technical_key well and format selection, but doesn't address the overwrite parameter behavior, potential errors, or what the export produces. While the output schema exists, the description could better explain the `project` and `overwrite` semantics for a 3-required-param tool without annotation support.

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 `technical_key` in depth (PCM600 object-tree identity, not SCL IED name, with an example). It also clarifies `out_path` semantics via the file-suffix mechanism for format selection. However, `project` and `overwrite` parameters receive no description-level explanation beyond the schema field 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 states a specific action (export parameters) with a specific resource (one IED) to specific formats (.csv or .xrio). It clearly distinguishes this from bulk export (pcm_export_bulk_parameters) by emphasizing 'one IED's parameters'. However, it doesn't explicitly differentiate from other export siblings like pcm_export_ied or pcm_export_project, though the 'parameters' focus helps.

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 provides clear guidance on when to use this tool, importantly distinguishing the `technical_key` from the SCL IED name context and noting it's read-only with no relay contact. However, it doesn't explicitly state alternatives or when NOT to use this tool vs the bulk export variant, leaving some inference required.

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

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

No annotations are provided, so the description carries the full disclosure burden. It states 'Read-only; no relay contact' (safety profile) and adds the restore limitation, which is genuinely useful. However, it doesn't disclose behavior details like whether it overwrites existing files, what the output schema/return value contains, or whether the export can be large/slow for big projects.

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 paragraphs, front-loaded with the core action, then a crucial caveat. Every sentence adds distinct value — scope, format, read-only nature, restore limitation, rollback warning. Zero 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?

The description covers the essential behavioral boundary (no rollback) and the scope well, which is the main complexity here. However, given 0% param coverage, it stops short of fully explaining parameter expectations. An output schema exists which offloads return-value explanation, slightly raising completeness.

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. Yet none of the 3 parameters (project, out_path, overwrite) are described. The description only explains the tool-level behavior, not what 'project' refers to, what format 'out_path' expects, or the semantics of the overwrite flag beyond the 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?

Clearly states the tool exports a whole project as an `.apcmp` archive, with a specific verb (export), a specific resource (whole project), and output format (.apcmp). It distinguishes itself from sibling tools like pcm_export_scd, pcm_export_ied, pcm_export_parameters which export narrower scopes — 'whole project' names the scope precisely.

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

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

Explicitly recommends using it as a snapshot before any change, names the constraint (no CLI restore), and warns 'Do not treat this as automated rollback.' This provides clear when-to-use guidance and flags a critical limitation. Could mention alternatives but the export-tool family is self-evident.

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

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

No annotations are provided, so the description carries the full burden. It discloses the read-only nature ('Read-only; no relay contact'), the refusal-to-overwrite safety behavior and its rationale ('often the baseline you are about to diff against'), and the distinction between project name and database name. This is rich behavior context though it doesn't cover all failure modes or return values.

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?

Well-structured and front-loaded: a clear one-sentence purpose, then a compact paragraph explaining the two critical parameter quirks, then a short behavioral note. Every sentence earns its place; the overwrite rationale is valuable context rather than padding.

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

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

For a 4-parameter read-only export tool with an output schema present, the description covers the essential behavioral and parameter semantics well. The output schema presumably documents the return value, so not describing it adds cost. A small gap remains on failure modes or the exact export format, but for a read-only export this is largely complete.

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

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

With 0% schema description coverage, the description must compensate, and it does meaningfully. It explains that 'project' is the PCM600 project name, not the database name — adding critical semantic context the schema lacks — and explains scl_version selects the IEC 61850 edition. overwrite's default false and its behavior is documented. out_path is the only parameter without added meaning.

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?

Purpose is clearly stated: 'Export a project's SCD file from the PCM600 database.' The verb (export) + resource (SCD file) + source (PCM600 database) are specific and immediately distinguish it from sibling tools like pcm_export_ied and pcm_import_scd. The 'Read-only; no relay contact' clarification reinforces its scope.

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?

Explains when to use it and provides explicit guidance on prerequisites: 'if you have the .apcmp, run apcmp_summary first to get the right one.' It also documents the overwrite behavior and default behavior ('omit it for the PCM600 default'), which signals when overwrite=true is needed. This is strong conditional 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?

With no annotations provided, the description carries the full behavioral burden. It explicitly flags that this MODIFIES PROTECTION SETTINGS (a write/mutation warning), reveals preprocessing behavior (snapshots first), and discloses the wider blast radius and lack of pre-flight validation. This is strong disclosure. It doesn't detail error handling or rollback behavior, but for a bulk import tool this disclosure is quite thorough.

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, front-loaded with the critical safety warning (MODIFIES PROTECTION SETTINGS), and every sentence earns its place: the purpose, the requirements, the preprocessing note, and the risk guidance with a named alternative. No wasted words, 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?

This is a high-stakes mutation tool with no annotations, no parent description coverage of parameters, but with an output schema present. The description covers purpose, safety requirements, behavioral risks, and alternative recommendations. The main gap is parameter semantics for project and param_dir, but given the safety focus and existing output schema, the description is quite complete for guiding safe 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. The description tacitly implies `confirm` is required (via 'requires... confirm=true') and `param_dir` relates to the bulk parameter files. However, it never explicitly describes what each parameter means or the format expected for `param_dir` (directory path, glob pattern, etc.). The confirm parameter semantics are partially covered, but project and param_dir semantics remain unclear.

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 tool imports `.xrio` parameter files for many IEDs at once, with a specific verb (import), resource (`.xrio` files), and scope (bulk/many IEDs). It explicitly distinguishes from the sibling `pcm_import_parameters` by noting the wider blast radius and lack of per-file pre-flight validation, contrasting with the single-IED alternative.

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 provides explicit guidance: it states the write requirement (PCM_MCP_ALLOW_WRITES=1 and confirm=true), warns about the wider blast radius, explicitly notes the absence of per-file pre-flight validation in bulk form, and directly recommends preferring `pcm_import_parameters` per IED when the change matters. This is outstanding when-to-use vs when-not-to guidance with a clear named alternative.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It explicitly warns 'MODIFIES THE PROJECT' in all caps and states the environment variable and confirmation gate requirements. This is meaningful behavioral safety context beyond what structured data provides. However, it doesn't describe side effects on existing IED data or whether the operation is reversible beyond the snapshot mention.

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 with the key safety warning ('MODIFIES THE PROJECT') immediately. Every sentence earns its place: file formats, safety requirement, target_level constraints, and snapshot guidance. The line-break structure makes requirements scannable at a glance.

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 write/mutation tool with no annotations, the description covers the critical gaps: mutating behavior, environment requirement, confirmation flag, and valid target values. The tool has an output schema which the description need not explain. Given the mutation semantics and zero annotation coverage, this is reasonably complete, though more detail on import behavior (overwrite vs. merge) would strengthen 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 compensate. It explains the valid values for target_level (bay, voltage-level, substation) and documents the confirm gating mechanism. However, it does not explain the exact nature of ied_file path/format expectations or the project parameter semantics beyond what the schema's parameter names convey.

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 verb (Import), resource (IED file), file formats (.apcmi/.apcmt/.pcmi/.pcmt), and destination (into a project). It distinguishes from sibling tools like pcm_import_scd and pcm_import_parameters by specifying IED files specifically. The tool name already conveys the primary purpose, and the description reinforces it with concrete file extensions.

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 clearly states the write requirement (PCM_MCP_ALLOW_WRITES=1 and confirm=true) and enumerates valid target_level values. However, it does not explicitly state when NOT to use this tool or name alternative tools for similar operations, leaving the user to infer from sibling names. The 'Snapshots first' instruction provides important ordering 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?

With no annotations provided, the description carries full burden, and it delivers. It discloses the write nature ('MODIFIES PROTECTION SETTINGS'), the snapshot-before-write behavior, the pre-validation step, the environmental gate (PCM_MCP_ALLOW_WRITES), the confirm flag requirement, and the unavailable signature-bypass option. This is exemplary transparency for a dangerous mutation 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?

Well-structured and efficient. Bold warning sentence gets attention, prerequisites and behavior are listed concisely, and the safety guidance is clear. Every sentence adds essential value with no filler or redundancy.

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 dangerous mutation tool with 0% schema coverage and no annotations, the description covers safety, prerequisites, workflow, and exclusions (signature bypass unavailable). It doesn't describe the output schema semantics, but since an output schema exists, that burden is satisfied by structured data. Slightly incomplete on which IED the import targets and how technical_key identifies it, but strong overall.

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. However, the description doesn't define the individual parameters (project, technical_key, param_file) beyond what their titles imply. The confirm flag's role is explained ('confirm=true') but no detail on how param_file should be formatted or what technical_key means. The description adds context about the workflow but doesn't explain the parameters semantically. Baseline 3 is appropriate since it doesn't hugely add param-level meaning.

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 it imports a parameter file into one IED of a project, with a specific verb+resource. It distinguishes itself from siblings like pcm_import_bulk_parameters (which imports into multiple IEDs) and pcm_import_scd by explicitly noting 'one IED' and mentioning the signature-bypass option limitation not available. However, it doesn't explicitly name a sibling alternative, so it falls just 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?

Excellent guidance. It explicitly states the environmental prerequisite (PCM_MCP_ALLOW_WRITES=1 and confirm=true), says validation runs beforehand so deviations are reported, and instructs the agent to read validation output and agree with the user before confirming. It also warns this is a write operation on protection settings. This is explicit when/how-to-use guidance with clear 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?

No annotations provided, so the description carries full burden — and it does exceptionally. It discloses the mutation side effect, the snapshot/verification behavior, the silent IED-loss failure mode inherent to PCM600's import, and the destructive nature of the two overwrite parameters. This is unusually rich behavioral disclosure for a tool with zero annotation coverage.

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 tightly structured: opens with the purpose, then leads with the most critical safety fact (MODIFIES THE PROJECT), then the verification mechanism, the failure mode, and the overwrite flags. Every sentence earns its place and information is front-loaded by importance, not 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?

Given an output schema exists (so return values need no explanation) and zero annotations, the description fully covers the tool's complexity: prerequisites, verification behavior, failure modes, and destructive-parameter warnings. This is an unusually complete description for a mutation tool handling critical project data.

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 confirm (safety gate), ln_overwrite_allowed and smt_overwrite_allowed (discard engineering work when true), and clarifies their defaults. The project and scd_path parameters are self-evident from names. Nearly all parameter semantics are conveyed beyond the bare schema.

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

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

States the action clearly ('Import an SCD file into a PCM600 project') with the resource (PCM600 project) and input (SCD file). The description distinguishes it from sibling read-only tools like scl_list_ieds and pcm_export_scd by emphasizing it MODIFIES THE PROJECT, differentiating it from the export/read operations in the sibling list.

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

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

Provides explicit prerequisites (PCM_MCP_ALLOW_WRITES=1 and confirm=true), warns to check apcmp_summary or pcm_cli_info connectivity packages first, and explains when the overwrite parameters should be used. Naming specific alternative tools (apcmp_summary, pcm_cli_info) gives clear when-to-use guidance relative to siblings.

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

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

With no annotations at all, the description carries the full behavioral burden. It explicitly discloses the non-destructive, read-only nature: 'imports nothing, changes nothing.' It further explains that the deviations listed are 'what that import would change,' connecting the output to a downstream effect. This is strong behavioral transparency for a validation tool, though it could mention what the output format looks like since an output schema exists.

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 two sentences plus a compact note, tightly written with zero fluff. The key fact (validation-only, no mutation) is front-loaded in the first sentence. The em-dash clarification and pre-flight framing add value without bloat. Slightly more space could have been used for parameter definitions, but the text is efficiently structured.

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

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

An output schema exists (contributing context about return values), and the description adequately explains the tool's role and non-destructive behavior. However, with no annotations and 0% parameter schema coverage, the description carries a heavy burden that it partially meets. It positions the tool well in the workflow but leaves the three parameters entirely undefined, which is a meaningful gap for a 3-parameter tool with no annotation support.

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 parameter meaning. However, the description does not define what 'project', 'technical_key', or 'param_file' mean or their formats. The phrase 'parameter file against an IED' gives some partial context (technical_key likely references the IED, param_file is the file being checked), but this is inferred rather than explicit. With 0% schema coverage and 3 undocumented parameters, the description should do much more here.

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 verb+resource: 'Check a parameter file against an IED in the project and list deviations.' It distinguishes from siblings by explicitly contrasting with import tools ('imports nothing, changes nothing'). However, it doesn't name a specific alternative tool for differentiation, though the sibling set makes the contrast fairly obvious. The purpose is specific and actionable.

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 provides explicit guidance on when to use this tool: 'the pre-flight you run *before* any parameter import.' It positions it as a validation/checking step that precedes import operations, which helps the agent sequence tool calls correctly. It doesn't explicitly state when NOT to use it, but the pre-flight positioning plus the contrast with import tools gives solid contextual placement.

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?

There are no annotations provided, so the description carries the full behavioral disclosure burden. It does well by disclosing the 'subtle one' — the dataset-carried-signal check — which is the tool's distinguishing behavioral trait. It also explains the input-file restriction (must contain all IEDs, .scd not .cid). It doesn't state return format, but an output schema exists (context signals confirm), so that burden is partially lifted.

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 compact paragraphs, each earning its place: the first defines the tool and its failure categories, the second enumerates the four report types, and the third provides the essential input-file prerequisite. Zero filler, every sentence adds distinct value, and critical constraints are front-loaded.

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 moderately complex analysis tool with one well-explained input and an output schema present. The description thoroughly covers what the tool checks and the file prerequisite. Minor gaps: no mention of whether the tool also reports matched/healthy bindings, and no guidance on output size or interpretation, but the output schema and the explicit failure-category enumeration make this largely complete.

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

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

Schema description coverage is 0%, so the description must compensate for the single 'path' parameter. It does state the file must be an .scd containing all IEDs and that a .cid won't work, which adds meaning to 'path' beyond the bare string type. However, it doesn't mention format expectations (e.g., relative vs. absolute paths) or error behavior if the file isn't an SCD. Given only one parameter, the added file-type guidance is helpful but could be more explicit.

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, concrete phrasing: 'Trace GOOSE publishers to subscribers and flag every way the binding can be broken.' It enumerates the exact categories of failures reported (unsubscribed publishers, missing network addresses, nonexistent IEDs/control blocks, dataset-signal mismatches). It clearly distinguishes itself from sibling tools by going beyond simple listing (scl_list_goose) or validation (scl_validate) into cross-IED binding analysis.

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 explicitly states when this tool is appropriate: it requires a multi-IED .scd file because bindings are cross-IED, and explicitly notes that a single-IED .cid cannot show them. This gives clear guidance on the file prerequisite that separates it from tools operating on single-file input, effectively directing the agent to use this only when multiple IEDs are involved.

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

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

With no annotations, the description carries the full burden of disclosing behavior. It explains that the tool compares the parsed model rather than raw text, which is a key behavioral trait. It also lists the specific output categories, but it does not mention side effects (e.g., read-only) or error handling. The transparency is good but not exhaustive.

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 concise and front-loaded: the first sentence states the primary purpose. The second paragraph adds valuable context about why this tool is necessary, with no wasted words. Every sentence contributes to understanding the tool's purpose and value.

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

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

Given the tool's complexity (diffing parsed SCL models) and the presence of an output schema, the description provides a reasonable overview. It lists the main categories of differences and explains the rationale. However, it omits details like file path requirements, error scenarios, or how output is structured beyond the schema, and it lacks explicit read-only confirmation.

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 input schema has zero description coverage, so the description must compensate. It identifies the two parameters as 'two SCL files' with roles 'as-built vs. design review', but it does not explicitly map baseline_path to as-built and candidate_path to design review. It provides some semantic context but leaves the mapping implicit; this partially fills the schema gap but could be clearer.

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 tool's function with a specific verb and resource: 'structurally compare two SCL files'. It further specifies the comparison scope (as-built vs. design review) and enumerates the types of changes detected (added/removed/changed per IED, logical device, dataset, etc.), which distinguishes it from sibling tools like scl_summary or scl_validate.

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 provides strong context for when to use the tool by explaining why text diff is unusable for SCL files (PCM600 reorders elements and rewrites attributes). It implicitly advises using this tool for comparing as-built vs. design review. However, it does not explicitly name alternative sibling tools or state 'use this instead of X', so it lacks explicit 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?

No annotations are provided, so the description carries the transparency burden. It discloses the scope of detail returned (logical devices, logical nodes, datasets, control blocks) which adds useful context about what the agent will receive. However, it doesn't describe output format specifics, whether the returned structure is nested/hierarchical, or any auth/access requirements for reading a specific IED.

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?

Single sentence, efficient, no filler. The list of contents (logical devices, logical nodes, datasets, control blocks) is informative without being verbose. Appropriate for a read-only detail 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?

The output schema exists which reduces the burden of describing return values. However, with no annotations and 0% parameter schema coverage, the 'path' parameter ambiguity is a notable gap. For a tool with 2 simple parameters and an output schema, this is reasonably complete but the path ambiguity and lack of usage guidance leave room for improvement.

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 schema only provides names ('path', 'ied') with no descriptions. The description mentions 'one IED' which maps to the 'ied' parameter, but neither the description nor schema clarifies what 'path' refers to (SCD file path? hierarchical path?). This is a significant gap for a 2-parameter tool with zero schema documentation.

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 clear verb+resource structure: 'Detail one IED' with the specific contents of logical devices, logical nodes, datasets, and control blocks. It distinguishes from siblings like scl_list_ieds (which lists IEDs) and scl_list_datasets (which lists datasets), though it doesn't explicitly name the differentiating 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?

No when-to-use guidance, prerequisites, or exclusions. It doesn't state when to use this vs scl_list_ieds or scl_list_datasets, leaving the agent to infer that this is the more detailed single-IED variant. No alternatives are 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. The description adds value by revealing that the tool flags duplicates (a diagnostic behavior beyond simple listing), which is useful. However, it doesn't disclose output format, whether it's read-only, or whether validation failures affect exit status. Since the duplicate-flagging behavior is disclosed, this is a solid baseline.

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 paragraphs; the first sentence is the core purpose, the second adds the diagnostic value proposition. No wasted words. Well front-loaded with the primary action. Could be slightly more compact but 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?

The tool has 1 parameter, no annotations, and an output schema. There are many sibling tools related to SCL inspection (scl_list_goose, scl_check_goose_bindings, scl_validate), so the description should clarify how this tool's address-focused scope differs. The description covers the listing and duplicate-flagging behaviors adequately but doesn't address relationship to sibling tools or expected output structure.

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 'path' parameter. The description does not explicitly explain what 'path' means (file path to SCL file presumably) beyond the context of listing addresses. However, there is only one parameter and its purpose is reasonably inferable from the tool name and description. The description could do more to clarify or confirm the path parameter's expected format.

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

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

The description states a specific action ('List IP addressing per IED access point') with a clear grouping dimension ('grouped by subnetwork'). It also mentions a secondary function: flagging duplicate IP addresses and duplicate GOOSE APPID/MAC values. This is clear and specific, though the purpose is somewhat split between listing and flagging. It doesn't explicitly differentiate from siblings, but the verb+resource is specific.

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 tool is for inspecting IP addressing in SCL files but does not state when to use it vs. alternatives like scl_check_goose_bindings or scl_list_goose, which may also relate to GOOSE configuration. No explicit when-to-use or exclusions. The 'painful to diagnose on site' note provides some motivational context but not technical usage 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. The description does not state whether this is a read-only operation, what the output format looks like, whether it can fail or throw errors, or any ordering/filtering behaviors. Since this lists datasets with FCDA members, it's implied to be read-only, but nothing is explicitly 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, compact sentence that conveys the core purpose (listing datasets and FCDA members) and the optional filter (restrict to one IED). Every word earns its place with zero waste.

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?

The tool has an output schema which helps, but with no annotations, 0% schema description coverage, and an ambiguous 'path' parameter, the description leaves significant gaps. The agent cannot determine what the path parameter accepts, what the output structure is, or how this differs contextually from the many sibling list tools. For a moderately complex companion tool among many siblings, 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 compensate. It mentions 'Optionally restrict to one IED,' which maps to the 'ied' parameter, but the 'path' parameter is left entirely undocumented—the description doesn't clarify what path refers to (file path? SCL XML path?) or its format. With output schema present but 0% coverage and 2 undocumented-ish parameters, partial compensation only.

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 tool lists datasets and their FCDA members, with optional restriction to an IED. The verb ('list') and resource ('datasets') are specific, and it distinguishes from siblings like scl_list_ieds, scl_list_goose, and scl_list_reports which target different resources. However, it doesn't explicitly contrast with these siblings, so it loses the top score.

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

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

The description implies usage (when you need to see datasets and their FCDA members) but gives no guidance on when NOT to use it or how it differs from sibling tools like scl_list_goose or scl_list_reports. The 'Optionally restrict to one IED' phrasing hints at the ied parameter usage but offers no exclusions or alternative recommendations.

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

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

With no annotations provided, the description carries the full burden. It discloses a valuable behavioral trait: the tool cross-references IED and Communication sections and flags publishers without GSE addresses. This is genuinely useful diagnostic behavior that an agent would not otherwise know. It doesn't describe return format details, but the output schema exists to cover that.

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 two sentences with zero wasted words. The first sentence states purpose, the second adds a genuinely useful diagnostic insight about silent GOOSE transmission failures. Front-loaded and efficient.

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

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

With an output schema present and only one trivial parameter, the description doesn't need to explain return values. It covers the diagnostic value-add (flagging publishers without GSE addresses) which is the most important behavioral context. Completeness is strong for this tool's complexity level.

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's only 1 parameter (path) and schema description coverage is 0%. However, the parameter is trivially self-explanatory — 'path' to an SCD/SCL file. The description doesn't need to elaborate on what a path is. Baseline for a single obvious parameter is decent given the simplicity.

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 ('List') with a resource ('GOOSE publishers / GSEControl blocks') and specifies the key outputs (dataset and network addressing). It distinguishes itself from siblings like scl_list_reports and scl_list_datasets by focusing specifically on GOOSE publishers and GSE addressing.

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 provides a clear context for when to use this tool: when you need GOOSE publisher configuration, including their GSE address assignment. It doesn't explicitly name alternative tools, but the domain is specific enough that usage context is reasonably clear. It doesn't mention exclusions, so not a 5.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. 'List every IED' suggests a read-only operation, but the description doesn't state whether the file is parsed/validated, whether it fails on malformed files, or what the output structure looks like. There's an output schema present which mitigates some of this, but behavioral traits like error handling are undisclosed.

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 focused sentence that states the action, the resource, and the returned fields with zero filler. Every word earns its place and there is no redundant 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?

For a list-all operation with one obvious parameter, the description is largely sufficient. An output schema exists to document return values. The main gap is the lack of any mention of IED list semantics (ordering, filtering) or error behavior, but for a simple list tool among many structured siblings this is an acceptable level of completeness.

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 there is only one parameter (path). The description implies 'path' refers to an SCL file location, but doesn't add explicit format details (relative vs absolute, supported file extensions, etc.). Since the parameter is a single, obvious 'path' with a self-evident semantic, the schema carries most of the meaning, and the description adds only marginal clarity.

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 verb+resource combination ('List every IED in an SCL file') and names the specific fields returned (manufacturer, type, config version, address). It distinguishes from siblings like scl_get_ied (singular retrieval vs. list-all) and scl_list_datasets/scl_list_goose (different resource types), though it doesn't explicitly differentiate.

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 'every IED' phrasing implies a comprehensive listing vs. the single-IED scl_get_ied sibling, providing some usage context. However, there is no explicit when-to-use guidance, no mention of prerequisites (e.g., file must be valid SCL), and no exclusion criteria relative to alternatives. The usage context is implied but not explicit.

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

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

No annotations are provided, so the description carries full burden for behavioral disclosure. It is a read operation implied by 'list,' but nothing describes buffering/trigger behavior semantics, whether outputs vary by SCL standard version, or any limitations on what report blocks match. The mention of 'buffering, trigger options and timing' hints at output content but doesn't clarify return structure.

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 concise sentence that is easy to scan. It front-loads the purpose. No wasted words, though it is slightly under-specified for the behavioral and parameter 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?

The tool has an output schema which may document return values, reducing that burden. However, with zero schema param coverage, no annotations, and 2 parameters (one optional), the description should clarify parameter semantics and use context. The description is minimally complete for a simple listing tool but leaves parameter interpretation entirely to the schema-less params.

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 there are no enums. The description does not explain what 'path' refers to (SCL file path?) or what 'ied' optional parameter does (filter by IED?). With two parameters and zero schema coverage, the description should compensate but instead provides no parameter guidance at all.

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 'List report control blocks with buffering, trigger options and timing.' It identifies the resource (report control blocks), the verb (list), and adds scope detail about what fields are shown. It distinguishes from siblings like scl_list_datasets and scl_list_goose since those target different SCL element types.

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 provides no guidance on when to use this tool versus alternatives. It does not explain the path/ied parameter relationship, nor when one would choose scl_list_reports over scl_summary or scl_list_datasets. No exclusions or use-case context is 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?

No annotations are provided, so the description carries the burden. It states this is a read/summary operation which implies non-destructive behavior, and lists the output components. However, it doesn't disclose the output format or any side effects, though the presence of an output schema partially mitigates this for return value clarity.

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

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

Two sentences, zero waste. The first names the scope precisely; the second gives actionable entry-point guidance. Text is front-loaded with the primary purpose.

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 summary tool with a single parameter and an output schema, this is well-specified. The description defines the entry-point use case and scopes the output. The output schema covers return structure, so the description need not. Could mention the file-type handling explicitly (scd/icd/cid are referenced, not the header format), but overall adequate.

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 there is only one parameter ('path'). The description doesn't elaborate on what path should be, but with a single clearly-named parameter this is less critical. The description conveys the accepted file extensions (.scd/.icd/.cid), which adds value, but no further path semantics are given.

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?

Clear verb+resource: 'Summarise an SCL file' with a specific scope (header, substation topology, IED inventory counts). Distinguished from siblings like scl_get_ied and scl_list_ieds by being a summary-level overview rather than a targeted detail query.

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?

Excellent guidance: 'Start here when handed an unfamiliar .scd/.icd/.cid file' explicitly tells the agent when to use this tool as the entry point, clearly separating it from the more granular sibling tools (scl_list_datasets, scl_get_ied, etc.) that would follow.

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

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

With no annotations provided, the description carries the burden of behavioral disclosure. It does explain that default is referential integrity and that schema validation is syntax-only, which is genuinely useful behavioral context. However, it doesn't disclose what the output/return format looks like, whether it modifies anything (it doesn't say it's a read-only operation), or error-handling behavior. The behavioral traits described are meaningful but incomplete.

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 well-structured and front-loaded: the first sentence gives the core purpose, then it enumerates what the default check catches (useful detail), then handles the optional parameter. Every sentence earns its place. It's slightly longer than strictly necessary but the enumeration of referential issues provides real value for understanding scope. A minor deduction for the length of the issue list.

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?

The tool has an output schema that presumably describes the validation results, so return format is handled there. The description covers the key decision point (xsd_path optional), clearly distinguishes referential vs schema validation, and its sibling differentiation is strong. It's reasonably complete for a validation tool with an output schema, though it could briefly note expected file format or that it takes an SCD/SCL file on disk.

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 substantial meaning for 'xsd_path' (that it's optional, must be user-supplied, what it's used for). However, the single required parameter 'path' gets no semantic explanation — the agent must infer it's the SCL file path. Given 0% coverage, the baseline would be low, but the description's handling of xsd_path partially compensates while the primary 'path' param remains under-explained.

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 tool 'validates an SCL file's internal consistency, and optionally against an XSD schema.' It goes further to specify the exact scope ('referential integrity') and enumerates what that check catches: control blocks pointing at missing datasets, duplicate IPs, empty datasets, etc. This is a specific verb+resource with detail that distills the purpose from siblings like scl_check_goose_bindings.

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 explicitly explains that xsd_path is optional and provides strong when-to-use guidance: it warns that schema validation only catches syntax and will NOT find referential problems, steering agents toward using referential integrity as the primary/default check. It also explains the licensing situation (schema not bundled) so agents know they must supply their own copy. This gives clear usage context.

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