pcm_validate_parameters

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.