tia_create_hmi_project_plan

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

Annotations only declare readOnlyHint=true; the description adds substantive behaviour: offline, immutable, no TIA access, no overwrite of an existing directory, and a deterministic compile/save/reopen verification sequence. It does not say what the returned plan object contains or what happens if the catalog identifier is invalid, which leaves a small 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?

Three tight sentences, front-loaded with what the plan does, then the hard input requirement, then the two safety exclusions. No filler or restatement of the title.

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 very large nested schema, no output schema and zero description coverage, the prose covers intent, pipeline and safety but leaves the spec's semantics largely to structural validation. An agent can attempt a call, but must infer how screens, templates, resources and internal tags relate to the generated project.

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 single 'spec' parameter is a deeply nested object (design/screens/elements, templates, resources, internalTags) with dozens of fields. The description only clarifies one of them — the exact Siemens catalog typeIdentifier — and gestures at screen/template candidates; the remaining structure, ordering and cross-field requirements are unexplained in prose.

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 — an offline, immutable plan that creates a NEW isolated classic WinCC V20 project plus device — and enumerates the pipeline stages (import candidates, compile, save, reopen to verify). The word 'plan' combined with 'Does not access TIA' clearly separates it from the apply/generate siblings without naming them.

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

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

Gives usable preconditions: the target must be a NEW project, the directory must not already exist, and the caller must supply an exact Siemens catalog type identifier. It does not explicitly name the apply step (e.g. tia_apply_hmi_project) as the required follow-up or the unified variant as the alternative, so usage context is clear but routing is left partly implicit.

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