tia_generate_unified_hmi_design

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

readOnlyHint=true is consistent with the stated "offline ... no TIA access or network probing" behavior, so no contradiction. The description adds genuinely useful context beyond the annotation: the output is a JSON creation program, explicitly not a native import archive — a distinction an agent would otherwise get wrong. It stops short of saying what consumes the output or whether the generated program is validated.

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

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

Two sentences, front-loaded with the deliverable and its contents, then the two disambiguating caveats. The middle enumeration is long but each item corresponds to a real schema branch; nothing is 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 tool this complex (one deeply nested parameter, many enums, no output schema), the description omits the shape of the returned program — how screens/elements are serialized and whether there is a validation or error form — which the agent cannot get from a 0%-covered input schema. The offline/no-network and non-archive caveats cover the biggest risk, but the return-side picture stays incomplete.

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

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

Schema description coverage is 0% and the single "design" parameter is a deep nested object, so the description is the only prose guidance available. It does map its enumeration onto real branches (screens/templates, internalTags/externalTags, connections, discreteAlarms, navigateTo), but adds no constraints, defaults, cardinality limits, or required-field meaning beyond what the schema's enums and defaults already encode. Baseline 3.

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

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

Specific verb ("Generate") tied to a concrete artifact: an offline WinCC Unified V20 public-API creation program, with the payload contents enumerated (screens, layouts, tags, connections, alarms, controls, navigation, scripts). The clause "This JSON is not a native import archive" separates it from the import/apply siblings, though it never names the closest sibling (e.g. tia_generate_hmi_design) directly.

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

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

Usage context is only implied: "offline" and "No TIA access or network probing" tell the agent this is the path when a live TIA session is unavailable, and the non-archive note hints the result must be consumed by another tool. There is no explicit when-to-use vs. when-not statement and no named alternative, so routing between this and tia_generate_hmi_design or tia_preview_hmi_design is left to inference.

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