tia_reanalyze_snapshot

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

Annotations only declare readOnlyHint=false and destructiveHint=false, so the description carries real weight here and delivers: it discloses that the operation verifies against a manifest, rebuilds the model offline, publishes (mutates) the analysis, and does so under a current-pointer lock. The lock detail is exactly the kind of concurrency context annotations cannot express. It does not say what happens to a previously published analysis or what failure modes look like, keeping it below 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 sentence with no filler, and the verification step is front-loaded before the rebuild and publish steps, which mirrors the likely execution order. The phrase 'current-pointer lock' is dense jargon, but it is load-bearing rather than decorative.

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 mutating, lock-taking rebuild with two fully undocumented parameters and no output schema, the description covers the behavior well but leaves the inputs entirely opaque. An agent knows what the tool accomplishes but not what to pass it. That is adequate-but-incomplete rather than sufficient.

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?

Both parameters, exportDir and projectScopeDir, have 0% schema description coverage, so the description is the only place their meaning could be established. It mentions neither, leaving the agent to guess what a scope directory is relative to an export directory. This is a meaningful gap for an operation that mutates published state.

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?

The description names three concrete operations on a specific resource: verifying snapshot XML against the manifest, rebuilding the execution model offline, and publishing the resulting analysis. That is far more specific than the tool name alone. It stops short of 5 because it never distinguishes this from neighbors like tia_build_reference_index or tia_analyze_hmi_alarms, so the agent must infer the boundary.

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 word 'offline' hints that no live session is required, which implicitly separates it from the live-session tools. However, there is no statement of when this should be run versus a reference-index build or a fresh analysis, and no prerequisites or preconditions are given. The agent is left to guess at the selection criteria.

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