This is a PowerShell module adapter exposing 6 cmdlets as MCP tools. Tool names follow PowerShell conventions (verb-object with hyphens) rather than agentic patterns. Descriptions are minimal (15-50 chars), leaving LLMs unable to determine when/why to select tools. Schemas are present with type info but lack proper constraints. No error handling guidance, no output schema documentation, and no actionable recovery hints. Per-tool analysis: Get-TmServerInfo (22), Enable-OrchFolderMachineAccountMapping (28), Disable-OrchFolderMachineAccountMapping (28), Get-OrchFolderMachineAccountMapping (28), Enable-OrchMaintenanceMode (30), Disable-OrchMaintenanceMode (30). This score reflects significant structural gaps in agentic tool design, the adapter prioritizes PS compatibility over LLM usability.
Tool names use PowerShell conventions (Get-*, Enable-*, Disable-*) rather than lowercase verb_noun agentic patterns (get_*, enable_*, disable_*). LLMs expect tool names in snake_case and interpret hyphenated names as literal text, not action verbs.
All tool descriptions are 15 - 50 characters, well below the 100-char minimum for effective LLM selection. Examples: 'Retrieves TestManager server information' (42 chars), 'Enables folder machine account mapping for specified machines and users' (70 chars). These lack WHEN to use the tool, prerequisites, or return-value hints.
Rename tools to lowercase snake_case: get_testmanager_info, enable_folder_machine_mapping, disable_folder_machine_mapping, get_folder_machine_mapping, enable_maintenance_mode, disable_maintenance_mode. This matches agentic convention and lets LLMs parse intent from the name alone.
Expand each tool description to 100 - 200 characters. Include: WHAT it does, WHEN to use it (vs similar tools), and WHY (e.g., 'Call this before enabling maintenance to check current status'). Example for Enable-OrchMaintenanceMode: 'Enables maintenance mode on specified machines, preventing new job allocations. Use before patching or diagnostics. Returns updated machine state. Idempotent if already in maintenance.'
Document the output schema for every tool. Specify which fields are returned, their types, and which IDs can be chained into downstream calls. E.g., Get-TmServerInfo should document: returns {version: string, status: string, health: enum}.
Add confirmation guidance to write-risk tools. For Enable/Disable operations, note in the description: 'This action is irreversible without manual recovery. Verify machine names and users before executing.' Consider offering a dry-run parameter.
Consolidate Path/LiteralPath parameters into a single 'path' parameter with clear documentation: 'Path to the folder (supports wildcards) or literal UNC path. Use LiteralPath-style syntax if your path contains special characters.'
Add constraint descriptions to all parameters. E.g., for MachineName: 'Machine name (string, case-insensitive, matches registered agents). Multiple names accepted (array).' For SessionId: 'Session ID (positive integer, 0 - 2^63-1).'
No output schema documented for any tool. LLMs cannot infer what fields are returned, what types they are, or which IDs to extract for chaining into downstream calls. This forces trial-and-error parsing and risks context loss.
Write-risk tools (Enable-*, Disable-*) lack confirmation hints or dry-run guidance. Agents have no warning before executing irreversible state changes. Pattern: confirmation-request not present.
Parameter descriptions exist but are minimal ('Names of folder machines to enable mapping for'). No constraints on valid values, formats, or ranges. LLMs receive no guidance on how to construct valid input, leading to repeated failures and retry loops.
No error handling documentation. No recovery guidance in tool descriptions. LLMs will not know how to handle 'folder not found', 'user permission denied', or other failure modes. Pattern: recovery-guide absent.
Path and LiteralPath parameters are duplicated in most tools. No documentation of why both exist or when to use each. This ambiguity forces LLMs to reason about file system conventions instead of focusing on the domain intent.
Add recovery hints to descriptions. E.g., 'If folder not found, use get_folder_mapping first to list available folders.' This guides the agent on fallback strategies.
Add an error classification guide in tool metadata or server documentation: which errors are retryable (transient failures, network timeouts) vs. user-fixable (folder not found, permission denied) vs. fatal (invalid schema, quota exceeded).
Parameter 'Recurse' and 'Depth' appear in folder operations. Document their interaction: 'If Recurse=true, apply operation to all subfolders up to Depth levels. Depth defaults to unlimited. If Depth=0, applies to specified folder only (no recursion).'
For Enable/Disable operations, document the expected state changes: 'Enables maintenance mode: MachineState transitions from Active → Maintenance. Jobs in queue are paused but not cancelled. Return value includes previous state for idempotency checks.'