xae_pou_create

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

Annotations already declare readOnly=false, destructive=false and idempotent=true, so safety is covered; the description adds real behavioral value by disclosing the accessor requirement for property kinds, the resulting compile error C0373, and the ordering constraint that implementation code must be set after creation. It omits what happens on a name collision or whether an existing object is overwritten, which keeps it from 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?

A single dense paragraph that front-loads the core action before the kind enumeration and constraints; nearly every clause carries operational information. The long pipe-delimited kind list is bulky but is the primary semantic payload the schema lacks.

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

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

An output schema exists, so return values need not be described, and the annotations carry the safety profile. Still, for an 11-parameter creation tool with zero schema descriptions, the omission of extends/implements/declaration/implementation semantics leaves the agent inferring how to build inheritance and body content.

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% across 11 parameters, so the description carries the full burden; it defines the most consequential ones (kind with a full value enumeration, accessors default and semantics, access, return_type), which is substantial added meaning since the schema's kind is a bare untyped string. But extends, implements, declaration, implementation, language, parent_path and name are left undocumented in both places, leaving a real 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?

States a specific verb and resource (create a PLC object under a folder/POU) and enumerates the full set of creatable kinds, so the agent knows exactly what can be produced. It does not explicitly differentiate itself from siblings like xae_pou_get or xae_pou_set, which would have made it 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?

It supplies a genuine usage constraint ('A property / itf_property is created with its accessors ... without one it does not compile (C0373)') and hints at a workflow boundary ('Optional code is set after creation'), implying xae_pou_set handles code. However, it never names an alternative tool or states when-not to use this one, so guidance remains implied rather than explicit.

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