tia_generate_hmi_design

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

Annotations already declare readOnlyHint=true, and the description is consistent with that: this produces candidate designs rather than mutating a project. It adds genuinely useful behavior beyond the annotations — that output is a candidate, that no visual template is needed, and that native serialization still requires later TIA validation, i.e. the result is not directly usable in the project.

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 short sentences, capability summary front-loaded before the constraints. Minor waste in the vague clause 'Dependencies must be provided when planning a project', which is unclear about what a dependency is.

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 with a large nested schema, no output schema and zero property descriptions, the description covers what is produced and the validation caveat but not how to shape the required design payload. An agent would still need to read the raw schema to build a valid device, screen and template 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% and the single 'design' parameter is a deeply nested object (device, adapter const, screens, templates, element fields). The description compensates partially by naming the element capabilities that map to valueTag, navigateTo and momentaryTag, but it says nothing about the device model/width/height, the fixed adapter value, screen numbering, or the templates array structure.

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: 'Generate classic V20 native screen/template candidates', and enumerates the element kinds produced (text, rectangles, buttons, navigation, momentary tag commands, IO fields). The 'classic V20 native' qualifier implicitly distinguishes it from the sibling 'tia_generate_unified_hmi_design' without naming it, so differentiation is inferable but not spelled out.

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 conditional context ('No visual template required', 'Dependencies must be provided when planning a project') which hints at prerequisites, but never states when to choose this over tia_generate_unified_hmi_design or when to route to tia_preview_hmi_design / tia_apply_hmi_project. Usage is implied by the workflow caveats rather than explicitly guided.

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