TIA Portal MCP server has 28 tools with basic naming and descriptions, but significant quality gaps. All tools have names starting with action verbs (Connect, Disconnect, GetState, etc.), which is positive. However, descriptions are uniformly terse (10-50 chars), providing minimal context for LLM tool selection. Input schemas are present but minimal: most tools have 0-2 parameters with only type and description fields, lacking enums, constraints, ranges, or validation guidance. No output schemas are documented. Error handling is generic (McpException with error codes) without recovery guidance. Tool composition is reasonable (single responsibility), but parameter descriptions lack actionable detail (e.g., 'path: defines the path to the project' does not specify format, constraints, or examples). No tool annotations (readOnlyHint, destructiveHint, idempotentHint) despite clear risk levels (READ_ONLY, WRITE, IRREVERSIBLE). Security: no evidence of secret injection, permission gates, or audit logging in visible code.

• Expand all tool descriptions to 100-200 characters. Include WHAT the tool does, WHEN to use it (e.g., 'Call this after opening a project to inspect its structure'), and any prerequisites. Example: 'Connect to TIA-Portal to enable project operations. Required before any project management calls. Returns connection status and error details if connection fails.'
• Add tool annotations to all tools. Use readOnlyHint=true for GET tools (GetState, GetProject, GetDevices, etc.), destructiveHint=true for DELETE/CLOSE tools (CloseProject), and idempotentHint=true for safe-to-retry operations. Mark ApplyAnalogPatch with destructiveHint=true and add a confirmation step.
• Document parameter constraints in descriptions. For OpenProject, change 'path: defines the path to the project' to 'path: absolute or relative file path to a TIA-Portal project file (.ap18, .ap19, .ap20, etc.). Must exist and be readable.' For regex parameters, specify the regex dialect (e.g., .NET Regex).
• Document output schemas for all tools. Create a schema section in the tool description or a separate schema document. Example for GetProject: 'Returns a list of open projects, each with fields: name (string), path (string), version (string), isModified (boolean).'
• Enhance error messages with recovery guidance. Instead of 'Failed to connect to TIA-Portal', return 'Failed to connect to TIA-Portal: [specific reason]. Ensure TIA-Portal is installed and running. Try Disconnect() then Connect() again.' This guides LLM retry logic.

Inferred effective spec: <=2025-11-25.

• Relies on Logging (deprecated) - log to stderr or use OpenTelemetry