New-PSUAiTool

SYNOPSIS

Creates a new AI tool definition.

SYNTAX

New-PSUAiTool -Name <String> -ScriptFullPath <String> [-Description <String>] [-Authenticated] [-Role <String[]>] [-Mcp] [-DefaultMaxWaitTimeoutSeconds <Int32>] [-Environment <String>] [-Computer <String>] [<ConnectionOptions>] [<CommonParameters>]

<ConnectionOptions>: [-ComputerName <String>] [-AppToken <String>] [-Credential <PSCredential>] [-UseDefaultCredentials] [-Integrated] [-TrustCertificate] [-Cookies].

DESCRIPTION

Creates an AI tool backed by a PowerShell script. AI agents can invoke the tool; -Mcp also exposes it through Model Context Protocol. Tool names must be unique (case-insensitive). -Environment and -Computer set the default execution target; a computer group can use '<GroupName> (All)' or '<GroupName> (Any)'. The default maximum tool-job wait is 30 seconds.

EXAMPLES

New-PSUAiTool -Name GetTickets -Description 'Query ticket data' -ScriptFullPath 'C:\ProgramData\UniversalAutomation\Repository\scripts\GetTickets.ps1' -Authenticated -Role HelpDesk,Admin -Mcp
New-PSUAiTool -Name GetTickets -ScriptFullPath 'C:\Repository\GetTickets.ps1' -Environment '7.4' -Computer 'Agents (Any)' -DefaultMaxWaitTimeoutSeconds 60 -Mcp

PARAMETERS

Parameter	Description
-Name	Required unique tool name.
-ScriptFullPath	Required full path to the implementing script.
-Description	What the tool does.
-Authenticated	Requires authentication to execute the tool.
-Role	Roles allowed to execute it.
-Mcp	Exposes the tool through MCP.
-DefaultMaxWaitTimeoutSeconds	Default maximum wait for tool jobs, in seconds (30 by default); individual calls may override it.
-Environment	Default execution environment.
-Computer	Default computer or computer-group target.
-ComputerName	Target PSU server URL or host name (alias -Uri), not the tool's execution target.
-AppToken	Management API app token.
-Credential	Credentials for Management API Basic authentication.
-UseDefaultCredentials	Uses current Windows credentials.
-Integrated	Uses the in-process management client.
-TrustCertificate	Ignores certificate validation errors.
-Cookies	Reuses session authentication cookies.

INPUTS

None.

OUTPUTS

PowerShellUniversal.Models.Intelligence.AiTool.

PERMISSIONS

The access token requires intelligence.tools/create to run this cmdlet remotely.