tia_apply_unified_hmi_project

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

Goes well beyond the supplied annotations: isolated TIA process, two headless sessions, compile-and-reopen verification, no download performed, partial failed output retained on the filesystem, and a multi-minute runtime governed by TIA_MCP_HMI_WRITE_TIMEOUT_MS (default 15 min). The non-idempotent and non-destructive hints are effectively explained by 'once' and 'partial failed output is retained'. This is exactly the context annotations cannot carry.

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?

Five compact clauses, front-loaded with the core action and then the side effects and timing. Nothing is redundant, though the telegraphic style (e.g. 'No download; partial failed output is retained') slightly reduces readability for a first-time caller.

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?

Strong on execution behavior and side effects, and sufficient given there is no output schema. However, for a destructive-capable creation tool with three opaque required parameters and 0% schema coverage, an agent still cannot tell what to supply for confirmToken or planSha256, nor what the tool returns on success versus partial failure beyond the retained-output note.

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% for three required parameters (confirmToken, planSha256, approval), and the description never mentions any of them. It does not explain where confirmToken or planSha256 come from, that planSha256 must match the approved plan byte-for-byte, or that approval must be the literal string CREATE_EXACT_UNIFIED_HMI_PROJECT. With no schema descriptions, the description needed to compensate and does not.

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: applying an approved Unified project creation plan to create native objects, compile, save and reopen for verification. It is distinguishable from plan-creation siblings (tia_create_unified_hmi_project_plan) and the edit variant (tia_apply_unified_hmi_edit) by the explicit 'creation plan' and 'Create native objects' framing, though it never names those alternatives outright.

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 'explicitly approved' and 'once' wording implies the prerequisite that a plan must be produced and approved first, and that re-invocation is not safe. There is no explicit routing statement such as 'to create the plan first use X' or 'for edits use tia_apply_unified_hmi_edit', so the agent must infer the position of this tool in the workflow from sibling names.

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