YAADMINEndpoint administration#
Action1 exposes real organization/endpoint lookup, software repository and installed-software reads, deployment/uninstall, Script Library search/detail/execution and inline PowerShell. Targets must use IDs from real inventory, not guessed host-to-ID mappings.
Scripts and approvals#
Library scripts construct CHANGE/POLICY requests. Inline PowerShell requires impact=routine or critical: routine constructs CHANGE/NEVER, critical constructs CHANGE/POLICY. Static registration is READ/NEVER, so it alone does not describe actual execution approval. RBAC remains active.
Batches and limits#
Endpoint_id and endpoints are mutually exclusive. Generic batches keep per-endpoint requests/results, fail_fast and optional timeout. Input schema caps endpoints at 5000 and concurrency at 100. Handler concurrency defaults to 28, although schema descriptions say 10. Web approval groups have their own 2..100 card / 50 concurrency cap.
Provider failures#
Default client timeout is 30 seconds, max retries 3, backoff 1 second and pacing 28 requests/minute. 429 uses Retry-After/body guidance; 401 permits one token refresh retry. Ambiguous mutations are not blindly replayed. Inline PowerShell detects a disconnected endpoint before submission; do not assume that for every execution path.
Exact registered tools#
action1.list_organizationsaction1.organizations.read
List real Action1 organizations. Use this when the organization ID is not already known. Never fabricate organization IDs.
Registration: RiskLevel.READ / ApprovalMode.NEVER · enabled
ExecutionRequest to the provider backend; ExecutionResult carries normalized data/error/status and provider metadata. Runtime RBAC can raise deny or force approval even where metadata says NEVER/POLICY; static metadata is not final policy.
Exact input schema
{
"type": "object",
"required": [],
"additionalProperties": false,
"properties": {
"backend_id": {
"type": "string",
"minLength": 1,
"description": "Optional configured Action1 backend ID. Reuse an exact backend_id from a previous ControlHub result/configuration; never invent one."
},
"max_items": {
"type": "integer",
"minimum": 1,
"maximum": 50000,
"description": "Optional retrieval cap. For semantic resolution normally omit it so the available candidate set is not knowingly truncated."
}
}
}action1.list_endpointsaction1.endpoints.read
Action1 organization-wide endpoint inventory. Use THIS tool for requests such as all PCs/endpoints, all active or Connected PCs, offline or Disconnected PCs, and organization-wide endpoint status. For ordinary fleet lists use view='summary'; summary preserves endpoint comment/description. For active/online use status='Connected'; for offline use status='Disconnected'. If the user provides literal text expected in an endpoint name, logged-on user, or comment/description, pass that text as query so filtering happens locally before results are sent back to the model; do NOT request the full discovery inventory just to search those fields. Prefer targets.resolve for one named person, partial hostname, named group, alias, or other semantic target discovery. If organization_id is not already known, call action1.list_organizations first and use a real returned ID. Never invent organization_id='unknown' or endpoint IDs. Normally omit max_items so the result is complete. Use view='discovery' only when fleet-wide semantic metadata is needed and view='full' only when full vendor objects are explicitly required. Resolver-confirmation guard: do not use this inventory tool to recover from targets.resolve ambiguity or after the user confirms a resolver candidate; repeat targets.resolve with the exact confirmed candidate.
Registration: RiskLevel.READ / ApprovalMode.NEVER · enabled
ExecutionRequest to the provider backend; ExecutionResult carries normalized data/error/status and provider metadata. Runtime RBAC can raise deny or force approval even where metadata says NEVER/POLICY; static metadata is not final policy.
Exact input schema
{
"type": "object",
"required": [
"organization_id"
],
"additionalProperties": false,
"properties": {
"organization_id": {
"type": "string",
"minLength": 1,
"description": "Exact Action1 organization ID obtained from configuration or action1.list_organizations. Never invent it."
},
"backend_id": {
"type": "string",
"minLength": 1,
"description": "Optional configured Action1 backend ID. Reuse an exact backend_id from a previous ControlHub result/configuration; never invent one."
},
"view": {
"type": "string",
"enum": [
"summary",
"discovery",
"full"
],
"description": "Projection returned to the model. Use 'summary' for ordinary fleet-wide listing/status questions; 'discovery' only when organization-wide semantic metadata is actually needed; 'full' only when full vendor objects for the whole fleet are explicitly required."
},
"status": {
"type": "string",
"minLength": 1,
"description": "Optional exact Action1 endpoint status filter. For currently active/online endpoints use 'Connected'; for offline endpoints use 'Disconnected'. This is an exact structured filter, not free-text search."
},
"query": {
"type": "string",
"minLength": 1,
"description": "Optional literal text to filter endpoint name, logged-on user/account, or Action1 comment/description locally before rows are returned. Pass the identifying text from the user's request, for example '\u0420\u045b\u0420\u00b1\u0420\u0406\u0420\u00b0\u0420\u00bb\u0420\u0454\u0420\u00b0'. This is lexical filtering only; use targets.resolve for semantic person, group, alias or fuzzy target resolution."
},
"max_items": {
"type": "integer",
"minimum": 1,
"maximum": 50000,
"description": "Optional retrieval cap. For semantic resolution normally omit it so the available candidate set is not knowingly truncated."
}
}
}action1.get_endpointaction1.endpoints.read
Get full details for one exact Action1 endpoint already resolved from real inventory. Use this after action1.list_endpoints when the user asks for a fact that was not present in discovery view. This is the safe detail-expansion path: resolve WHO first, then fetch full metadata only for the endpoint(s) actually needed. Never guess an endpoint ID and never infer a missing fact.
Registration: RiskLevel.READ / ApprovalMode.NEVER · enabled
ExecutionRequest to the provider backend; ExecutionResult carries normalized data/error/status and provider metadata. Runtime RBAC can raise deny or force approval even where metadata says NEVER/POLICY; static metadata is not final policy.
Exact input schema
{
"type": "object",
"required": [
"organization_id",
"endpoint_id"
],
"additionalProperties": false,
"properties": {
"organization_id": {
"type": "string",
"minLength": 1,
"description": "Exact Action1 organization ID obtained from configuration or action1.list_organizations. Never invent it."
},
"endpoint_id": {
"type": "string",
"minLength": 1,
"description": "Exact Action1 endpoint ID returned by real endpoint inventory. Never synthesize or guess it from the hostname."
},
"endpoint_name": {
"type": "string",
"minLength": 1,
"description": "Optional real endpoint display/host name returned by Action1 inventory."
},
"backend_id": {
"type": "string",
"minLength": 1,
"description": "Optional configured Action1 backend ID. Reuse an exact backend_id from a previous ControlHub result/configuration; never invent one."
}
}
}action1.get_endpoint_statusaction1.endpoints.read
Get Action1 endpoint-status data for an exact organization.
Registration: RiskLevel.READ / ApprovalMode.NEVER · enabled
ExecutionRequest to the provider backend; ExecutionResult carries normalized data/error/status and provider metadata. Runtime RBAC can raise deny or force approval even where metadata says NEVER/POLICY; static metadata is not final policy.
Exact input schema
{
"type": "object",
"required": [
"organization_id"
],
"additionalProperties": false,
"properties": {
"organization_id": {
"type": "string",
"minLength": 1,
"description": "Exact Action1 organization ID obtained from configuration or action1.list_organizations. Never invent it."
},
"backend_id": {
"type": "string",
"minLength": 1,
"description": "Optional configured Action1 backend ID. Reuse an exact backend_id from a previous ControlHub result/configuration; never invent one."
}
}
}action1.search_software_packagesaction1.software.read
PRIMARY software discovery tool for ordinary installation requests. Search the complete real Action1 Software Repository locally by lexical/fuzzy similarity and return only a compact shortlist. Pass the software/product words from the user's request as query. The local score is only a shortlist; YOU must still choose semantically among the real returned candidates. Never invent a package ID. If none is suitable, use action1.list_software_packages as the broad fallback.
Registration: RiskLevel.READ / ApprovalMode.NEVER · enabled
ExecutionRequest to the provider backend; ExecutionResult carries normalized data/error/status and provider metadata. Runtime RBAC can raise deny or force approval even where metadata says NEVER/POLICY; static metadata is not final policy.
Exact input schema
{
"type": "object",
"required": [
"organization_id",
"query"
],
"additionalProperties": false,
"properties": {
"organization_id": {
"type": "string",
"minLength": 1,
"description": "Exact Action1 organization ID obtained from configuration or action1.list_organizations. Never invent it."
},
"query": {
"type": "string",
"minLength": 1,
"description": "Software/product name or identifying words for local repository search."
},
"backend_id": {
"type": "string",
"minLength": 1,
"description": "Optional configured Action1 backend ID. Reuse an exact backend_id from a previous ControlHub result/configuration; never invent one."
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 50,
"description": "Optional candidate count; normally omit."
},
"max_items": {
"type": "integer",
"minimum": 1,
"maximum": 50000,
"description": "Optional retrieval cap. For semantic resolution normally omit it so the available candidate set is not knowingly truncated."
}
}
}action1.list_software_packagesaction1.software.read
BROAD FALLBACK listing of the real Action1 Software Repository. Do not use this first for an ordinary install request because the complete catalog is expensive in LLM context. First use action1.search_software_packages. Use this full listing only if the compact candidates are semantically insufficient. Never invent package IDs.
Registration: RiskLevel.READ / ApprovalMode.NEVER · enabled
ExecutionRequest to the provider backend; ExecutionResult carries normalized data/error/status and provider metadata. Runtime RBAC can raise deny or force approval even where metadata says NEVER/POLICY; static metadata is not final policy.
Exact input schema
{
"type": "object",
"required": [
"organization_id"
],
"additionalProperties": false,
"properties": {
"organization_id": {
"type": "string",
"minLength": 1,
"description": "Exact Action1 organization ID obtained from configuration or action1.list_organizations. Never invent it."
},
"backend_id": {
"type": "string",
"minLength": 1,
"description": "Optional configured Action1 backend ID. Reuse an exact backend_id from a previous ControlHub result/configuration; never invent one."
},
"max_items": {
"type": "integer",
"minimum": 1,
"maximum": 50000,
"description": "Optional retrieval cap. For semantic resolution normally omit it so the available candidate set is not knowingly truncated."
}
}
}action1.get_software_packageaction1.software.read
Get full detail for one exact Action1 Software Repository package_id already returned by action1.list_software_packages. Use this after discovery and before deployment to obtain the real versions array. Select an exact deployable version from that returned Action1 data; never invent or guess a version.
Registration: RiskLevel.READ / ApprovalMode.NEVER · enabled
ExecutionRequest to the provider backend; ExecutionResult carries normalized data/error/status and provider metadata. Runtime RBAC can raise deny or force approval even where metadata says NEVER/POLICY; static metadata is not final policy.
Exact input schema
{
"type": "object",
"required": [
"organization_id",
"package_id"
],
"additionalProperties": false,
"properties": {
"organization_id": {
"type": "string",
"minLength": 1,
"description": "Exact Action1 organization ID obtained from configuration or action1.list_organizations. Never invent it."
},
"package_id": {
"type": "string",
"minLength": 1,
"description": "Exact Action1 Software Repository package ID returned by action1.list_software_packages."
},
"backend_id": {
"type": "string",
"minLength": 1,
"description": "Optional configured Action1 backend ID. Reuse an exact backend_id from a previous ControlHub result/configuration; never invent one."
}
}
}action1.list_installed_softwareaction1.software.read
List real installed-software inventory across an Action1 organization. Use this for questions such as where an application is installed. Semantically interpret real returned metadata; do not fabricate software IDs or use fixed scoring.
Registration: RiskLevel.READ / ApprovalMode.NEVER · enabled
ExecutionRequest to the provider backend; ExecutionResult carries normalized data/error/status and provider metadata. Runtime RBAC can raise deny or force approval even where metadata says NEVER/POLICY; static metadata is not final policy.
Exact input schema
{
"type": "object",
"required": [
"organization_id"
],
"additionalProperties": false,
"properties": {
"organization_id": {
"type": "string",
"minLength": 1,
"description": "Exact Action1 organization ID obtained from configuration or action1.list_organizations. Never invent it."
},
"backend_id": {
"type": "string",
"minLength": 1,
"description": "Optional configured Action1 backend ID. Reuse an exact backend_id from a previous ControlHub result/configuration; never invent one."
},
"max_items": {
"type": "integer",
"minimum": 1,
"maximum": 50000,
"description": "Optional retrieval cap. For semantic resolution normally omit it so the available candidate set is not knowingly truncated."
}
}
}action1.list_endpoint_installed_softwareaction1.software.read
SOFTWARE-ONLY tool: list real software installed on one exact, already-resolved Action1 endpoint. Never use this tool to list PCs, find active/Connected or offline/Disconnected endpoints, discover an organization, or inspect endpoint connectivity/status. For a request to REMOVE software, inspect this inventory first and choose the exact installed software entry that semantically matches the user's intent. Never guess a software_id. Native uninstall also needs the exact Software Repository package_id, so inspect the repository before calling uninstall_software. If several endpoint targets genuinely match the user's target description, perform the same discovery for each via the generic batch/agent flow.
Registration: RiskLevel.READ / ApprovalMode.NEVER · enabled
ExecutionRequest to the provider backend; ExecutionResult carries normalized data/error/status and provider metadata. Runtime RBAC can raise deny or force approval even where metadata says NEVER/POLICY; static metadata is not final policy.
Exact input schema
{
"type": "object",
"required": [
"organization_id",
"endpoint_id"
],
"additionalProperties": false,
"properties": {
"organization_id": {
"type": "string",
"minLength": 1,
"description": "Exact Action1 organization ID obtained from configuration or action1.list_organizations. Never invent it."
},
"endpoint_id": {
"type": "string",
"minLength": 1,
"description": "Exact Action1 endpoint ID returned by real endpoint inventory. Never synthesize or guess it from the hostname."
},
"endpoint_name": {
"type": "string",
"minLength": 1,
"description": "Optional real endpoint display/host name returned by Action1 inventory."
},
"backend_id": {
"type": "string",
"minLength": 1,
"description": "Optional configured Action1 backend ID. Reuse an exact backend_id from a previous ControlHub result/configuration; never invent one."
},
"max_items": {
"type": "integer",
"minimum": 1,
"maximum": 50000,
"description": "Optional retrieval cap. For semantic resolution normally omit it so the available candidate set is not knowingly truncated."
}
}
}action1.deploy_softwareaction1.software.deploy
Deploy one exact existing Action1 Software Repository package and exact version to one exact endpoint using Action1's native Deploy Software action. Before calling this tool, inspect the real repository and use the exact package_id and package_version returned by Action1. Never invent a version or fall back to generated PowerShell while a suitable native package exists. Requires normal ControlHub CHANGE approval policy.
Registration: RiskLevel.CHANGE / ApprovalMode.POLICY · enabled
ExecutionRequest to the provider backend; ExecutionResult carries normalized data/error/status and provider metadata. Runtime RBAC can raise deny or force approval even where metadata says NEVER/POLICY; static metadata is not final policy.
Exact input schema
{
"type": "object",
"required": [
"organization_id",
"endpoint_id",
"package_id",
"package_version"
],
"additionalProperties": false,
"properties": {
"organization_id": {
"type": "string",
"minLength": 1,
"description": "Exact Action1 organization ID obtained from configuration or action1.list_organizations. Never invent it."
},
"endpoint_id": {
"type": "string",
"minLength": 1,
"description": "Exact Action1 endpoint ID returned by real endpoint inventory. Never synthesize or guess it from the hostname."
},
"package_id": {
"type": "string",
"minLength": 1,
"description": "Exact package ID selected from the real Action1 Software Repository."
},
"package_version": {
"type": "string",
"minLength": 1,
"description": "Exact deployable version returned by Action1 for that exact Software Repository package."
},
"endpoint_name": {
"type": "string",
"minLength": 1,
"description": "Optional real endpoint display/host name returned by Action1 inventory."
},
"backend_id": {
"type": "string",
"minLength": 1,
"description": "Optional configured Action1 backend ID. Reuse an exact backend_id from a previous ControlHub result/configuration; never invent one."
},
"execution_name": {
"type": "string",
"minLength": 1,
"description": "Optional human-readable deployment name."
},
"retry_minutes": {
"type": "integer",
"minimum": 0,
"maximum": 10080,
"description": "Optional Action1 retry window in minutes."
},
"reboot_options": {
"type": "object",
"description": "Optional Action1-compatible reboot behavior already known by the calling integration. Do not invent vendor fields.",
"additionalProperties": true
}
}
}action1.uninstall_softwareaction1.software.uninstall
Uninstall software from one exact Action1 endpoint using the verified native uninstall_program action. First inspect the endpoint with action1.list_endpoint_installed_software and use the exact software_id as proof that the application is installed. Also inspect the real Action1 Software Repository and supply the exact package_id used by native uninstall. The wire payload uses that package_id with '*' (all installed versions). Never guess either ID. This is a DESTRUCTIVE operation and remains subject to ControlHub policy and approval.
Registration: RiskLevel.DESTRUCTIVE / ApprovalMode.POLICY · enabled
ExecutionRequest to the provider backend; ExecutionResult carries normalized data/error/status and provider metadata. Runtime RBAC can raise deny or force approval even where metadata says NEVER/POLICY; static metadata is not final policy.
Exact input schema
{
"type": "object",
"required": [
"organization_id",
"endpoint_id",
"software_id",
"package_id"
],
"additionalProperties": false,
"properties": {
"organization_id": {
"type": "string",
"minLength": 1,
"description": "Exact Action1 organization ID obtained from configuration or action1.list_organizations. Never invent it."
},
"endpoint_id": {
"type": "string",
"minLength": 1,
"description": "Exact Action1 endpoint ID returned by real endpoint inventory. Never synthesize or guess it from the hostname."
},
"software_id": {
"type": "string",
"minLength": 1,
"description": "Exact installed-software ID returned for this exact endpoint by Action1."
},
"package_id": {
"type": "string",
"minLength": 1,
"description": "Exact Action1 Software Repository package ID for the application selected for uninstall."
},
"endpoint_name": {
"type": "string",
"minLength": 1,
"description": "Optional real endpoint display/host name returned by Action1 inventory."
},
"backend_id": {
"type": "string",
"minLength": 1,
"description": "Optional configured Action1 backend ID. Reuse an exact backend_id from a previous ControlHub result/configuration; never invent one."
},
"execution_name": {
"type": "string",
"minLength": 1,
"description": "Optional human-readable uninstall name."
},
"retry_minutes": {
"type": "integer",
"minimum": 0,
"maximum": 10080,
"description": "Optional Action1 retry window in minutes."
},
"reboot_options": {
"type": "object",
"description": "Optional Action1-compatible reboot behavior already known by the calling integration. Do not invent vendor fields.",
"additionalProperties": true
}
}
}action1.search_scriptsaction1.scripts.read
Search the REAL Action1 Script Library before generating ad-hoc PowerShell for a scriptable task. This is the preferred discovery tool for ordinary script selection because YAADMIN ranks the full metadata catalog locally and returns only the most relevant IDs, names and descriptions; script source is NEVER included. Ranking uses deterministic lexical/fuzzy similarity over name/description and is only a shortlist, not the final semantic decision. Inspect the returned candidates yourself and call action1.get_script for a plausible exact ID before running it. Use query as a short natural-language task description; optional search_terms may add synonyms or UA/RU/EN variants when useful. Do not treat relevance_score as proof that a script is safe or suitable for the execution context.
Registration: RiskLevel.READ / ApprovalMode.NEVER · enabled
ExecutionRequest to the provider backend; ExecutionResult carries normalized data/error/status and provider metadata. Runtime RBAC can raise deny or force approval even where metadata says NEVER/POLICY; static metadata is not final policy.
Exact input schema
{
"type": "object",
"required": [
"query"
],
"additionalProperties": false,
"properties": {
"query": {
"type": "string",
"minLength": 1,
"description": "Short natural-language description of the script task to find. Do not paste PowerShell source here."
},
"search_terms": {
"type": "array",
"maxItems": 12,
"items": {
"type": "string",
"minLength": 1
},
"description": "Optional synonyms or language variants to improve recall."
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 50,
"default": 12,
"description": "Maximum shortlisted metadata candidates."
},
"backend_id": {
"type": "string",
"minLength": 1,
"description": "Optional configured Action1 backend ID. Reuse an exact backend_id from a previous ControlHub result/configuration; never invent one."
}
}
}action1.list_scriptsaction1.scripts.read
List/browse the real Action1 Script Library metadata catalog. Prefer action1.search_scripts for ordinary script selection so the model sees only a small relevant metadata shortlist. Use this full catalog tool when the user explicitly asks to browse/list the library or when an exhaustive metadata listing is actually required. It returns ONLY exact script IDs, names and descriptions (never source code or parameters). Read count and truncated; do not call a partial list exhaustive. If listing is unavailable, never claim it was checked.
Registration: RiskLevel.READ / ApprovalMode.NEVER · enabled
ExecutionRequest to the provider backend; ExecutionResult carries normalized data/error/status and provider metadata. Runtime RBAC can raise deny or force approval even where metadata says NEVER/POLICY; static metadata is not final policy.
Exact input schema
{
"type": "object",
"required": [],
"additionalProperties": false,
"properties": {
"backend_id": {
"type": "string",
"minLength": 1,
"description": "Optional configured Action1 backend ID. Reuse an exact backend_id from a previous ControlHub result/configuration; never invent one."
},
"max_items": {
"type": "integer",
"minimum": 1,
"maximum": 50000,
"description": "Optional retrieval cap. For semantic resolution normally omit it so the available candidate set is not knowingly truncated."
}
}
}action1.get_scriptaction1.scripts.read
Get one exact Action1 Script Library item by script ID selected from search_scripts/list_scripts metadata. Inspect its actual code, supported parameters and SYSTEM/user-session context before execution. Never invent script IDs or parameters.
Registration: RiskLevel.READ / ApprovalMode.NEVER · enabled
ExecutionRequest to the provider backend; ExecutionResult carries normalized data/error/status and provider metadata. Runtime RBAC can raise deny or force approval even where metadata says NEVER/POLICY; static metadata is not final policy.
Exact input schema
{
"type": "object",
"required": [
"script_id"
],
"additionalProperties": false,
"properties": {
"script_id": {
"type": "string",
"minLength": 1,
"description": "Exact Script Library ID returned by Action1."
},
"backend_id": {
"type": "string",
"minLength": 1,
"description": "Optional configured Action1 backend ID. Reuse an exact backend_id from a previous ControlHub result/configuration; never invent one."
}
}
}action1.run_library_scriptaction1.scripts.run
Execute one exact existing Action1 Script Library item on one or many exact endpoints. Prefer this over generated PowerShell when a semantically suitable library item exists. Use endpoint_id for one target OR endpoints for several already-resolved targets; never provide both and never invent endpoint IDs. Several targets are executed through the generic ControlHub BatchExecutor, not by Action1-specific parallel code. Every atomic item still passes through ordinary ControlHub policy, approval, audit and executor logic. Native Action1 capabilities such as Software Repository deployment remain higher priority when they directly represent the requested task. Windows library scripts normally start as LocalSystem in Session 0. For user-specific work, inspect the selected script with action1.get_script and use it only if its code or supported parameters target the intended Windows user's actual resources or interactive session. A script using SYSTEM's own Desktop/HKCU/profile does not satisfy a request about the user's resources. If no library item fits that context, use action1.run_powershell with an appropriate script. Do not invent parameters.
Registration: RiskLevel.CHANGE / ApprovalMode.POLICY · enabled
ExecutionRequest to the provider backend; ExecutionResult carries normalized data/error/status and provider metadata. Runtime RBAC can raise deny or force approval even where metadata says NEVER/POLICY; static metadata is not final policy.
Exact input schema
{
"type": "object",
"required": [
"organization_id",
"script_id"
],
"additionalProperties": false,
"properties": {
"organization_id": {
"type": "string",
"minLength": 1,
"description": "Exact Action1 organization ID obtained from configuration or action1.list_organizations. Never invent it."
},
"endpoint_id": {
"description": "Exact endpoint ID for a SINGLE target. Use either endpoint_id or endpoints, never both."
},
"endpoints": {
"type": "array",
"minItems": 1,
"maxItems": 5000,
"description": "Exact real Action1 endpoints for one generic batch execution. Use this instead of endpoint_id when the same action must run on several already-resolved endpoints. Every endpoint_id must come from real Action1 inventory; never invent IDs. Do not provide endpoint_id or the top-level endpoint_name together with endpoints.",
"items": {
"type": "object",
"properties": {
"endpoint_id": {
"type": "string",
"minLength": 1,
"description": "Exact Action1 endpoint ID returned by real endpoint inventory. Never synthesize or guess it from the hostname."
},
"endpoint_name": {
"type": "string",
"minLength": 1,
"description": "Optional real endpoint display/host name returned by Action1 inventory."
}
},
"required": [
"endpoint_id"
],
"additionalProperties": false
}
},
"script_id": {
"type": "string",
"minLength": 1,
"description": "Exact ID of the selected existing Script Library item."
},
"endpoint_name": {
"description": "Optional real name for the SINGLE endpoint_id target. For batch targets put endpoint_name inside each endpoints item."
},
"backend_id": {
"type": "string",
"minLength": 1,
"description": "Optional configured Action1 backend ID. Reuse an exact backend_id from a previous ControlHub result/configuration; never invent one."
},
"script_parameters": {
"type": "object",
"description": "Optional non-secret parameters for the PowerShell execution. Do not place passwords, tokens, API keys or other raw secrets here.",
"additionalProperties": true
},
"execution_name": {
"type": "string",
"minLength": 1,
"description": "Optional human-readable execution name."
},
"retry_minutes": {
"type": "integer",
"minimum": 0,
"maximum": 10080,
"description": "Optional Action1 retry window in minutes."
},
"max_concurrency": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"description": "Maximum number of endpoint operations allowed to run concurrently inside the generic ControlHub batch. Normally omit to use 10. This is not a target-count limit."
},
"fail_fast": {
"type": "boolean",
"description": "Whether the generic batch should stop starting new items after a failure. Normally false so one failed PC does not block the others."
},
"overall_timeout_seconds": {
"type": "number",
"exclusiveMinimum": 0,
"maximum": 86400,
"description": "Optional overall timeout in seconds for the whole generic batch. Normally omit; each atomic Action1 request still keeps its own timeout."
}
}
}action1.run_powershellaction1.powershell.run
Execute LLM-generated or explicitly provided ad-hoc PowerShell on one or many exact Action1 endpoints. Use endpoint_id for one already-resolved target OR endpoints for several targets; never provide both and never invent endpoint IDs. For several targets the SAME exact PowerShell is fanned out through ControlHub's generic BatchExecutor, with ordinary policy/audit/executor logic applied independently to every endpoint. Use this when the requested inspection or operation cannot be satisfied from Action1 inventory or a more appropriate native mechanism. If the user explicitly supplied a complete PowerShell script and asked to execute that script, use the supplied script itself. Do not search Script Library for a replacement and do not regenerate, repair, optimize, normalize or reformat the script unless the user explicitly asks you to modify it. If the user says as-is, verbatim, exactly, unchanged or without changes, preserve the source exactly, including whitespace, quoting, comments and line order. For scriptable tasks where the user did NOT supply a complete script for execution, search the authorized Script Library with action1.search_scripts first, even when the user does not mention it; use action1.get_script for plausible matches before deciding none fits the task and execution context. If library access failed, report that limitation instead of claiming no script matches. When ad-hoc PowerShell is needed, generate the exact script and CALL THIS TOOL instead of merely describing a command. Never include raw secrets. You MUST classify impact semantically as 'routine' or 'critical' from user intent and real-world effect; do not use regex, keywords, command-name matching, allowlists or denylists. Routine requests execute without y/N; critical requests use the normal ControlHub human-approval policy. Windows execution normally starts as LocalSystem in Session 0. For user-specific work, resolve the intended Windows account and actual resource paths before making changes. For a user-visible GUI, launch under that user's account in the selected interactive session; ordinary Start-Process from SYSTEM does not do this. Report the destination or session supported by the returned result.
Registration: RiskLevel.READ / ApprovalMode.NEVER · enabled
ExecutionRequest to the provider backend; ExecutionResult carries normalized data/error/status and provider metadata. Runtime RBAC can raise deny or force approval even where metadata says NEVER/POLICY; static metadata is not final policy.
Exact input schema
{
"type": "object",
"required": [
"organization_id",
"script",
"impact"
],
"additionalProperties": false,
"properties": {
"organization_id": {
"type": "string",
"minLength": 1,
"description": "Exact Action1 organization ID obtained from configuration or action1.list_organizations. Never invent it."
},
"endpoint_id": {
"description": "Exact endpoint ID for a SINGLE target. Use either endpoint_id or endpoints, never both."
},
"endpoints": {
"type": "array",
"minItems": 1,
"maxItems": 5000,
"description": "Exact real Action1 endpoints for one generic batch execution. Use this instead of endpoint_id when the same action must run on several already-resolved endpoints. Every endpoint_id must come from real Action1 inventory; never invent IDs. Do not provide endpoint_id or the top-level endpoint_name together with endpoints.",
"items": {
"type": "object",
"properties": {
"endpoint_id": {
"type": "string",
"minLength": 1,
"description": "Exact Action1 endpoint ID returned by real endpoint inventory. Never synthesize or guess it from the hostname."
},
"endpoint_name": {
"type": "string",
"minLength": 1,
"description": "Optional real endpoint display/host name returned by Action1 inventory."
}
},
"required": [
"endpoint_id"
],
"additionalProperties": false
}
},
"script": {
"type": "string",
"minLength": 1,
"description": "Exact PowerShell source code to execute on the already-resolved Action1 endpoint. If the user supplied a complete script for execution, pass that script itself rather than regenerating it. When the user requested as-is, verbatim, exact or unchanged execution, preserve its text exactly. Otherwise generate the script needed to satisfy the user's request. Do not merely describe a command that somebody else should run. Never embed passwords, tokens, API keys or other raw secrets. Windows default: LocalSystem in Session 0. Before writing to a user-specific location, resolve the intended Windows account and its actual folder path, including OneDrive or folder redirection. SYSTEM's HKCU, USERPROFILE, APPDATA and GetFolderPath('Desktop') are not the intended user's resources. Do not substitute systemprofile, Public Desktop or a guessed profile path. If the intended user or path remains unresolved, ask instead of writing elsewhere. Return the actual destination path in the script output."
},
"impact": {
"type": "string",
"enum": [
"routine",
"critical"
],
"description": "Semantic impact of the requested PowerShell action. Decide this from the user's intent and the real-world effect of the operation, not from keywords or command-name matching. Use 'routine' for ordinary, low-impact work that may execute immediately. Use 'critical' when the operation is sufficiently consequential that a human should confirm before execution. This value controls whether ControlHub asks y/N."
},
"endpoint_name": {
"description": "Optional real name for the SINGLE endpoint_id target. For batch targets put endpoint_name inside each endpoints item."
},
"backend_id": {
"type": "string",
"minLength": 1,
"description": "Optional configured Action1 backend ID. Reuse an exact backend_id from a previous ControlHub result/configuration; never invent one."
},
"script_parameters": {
"type": "object",
"description": "Optional non-secret parameters for the PowerShell execution. Do not place passwords, tokens, API keys or other raw secrets here.",
"additionalProperties": true
},
"execution_name": {
"type": "string",
"minLength": 1,
"description": "Optional human-readable Action1 execution name."
},
"retry_minutes": {
"type": "integer",
"minimum": 0,
"maximum": 10080,
"description": "Optional Action1 retry window in minutes."
},
"max_concurrency": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"description": "Maximum number of endpoint operations allowed to run concurrently inside the generic ControlHub batch. Normally omit to use 10. This is not a target-count limit."
},
"fail_fast": {
"type": "boolean",
"description": "Whether the generic batch should stop starting new items after a failure. Normally false so one failed PC does not block the others."
},
"overall_timeout_seconds": {
"type": "number",
"exclusiveMinimum": 0,
"maximum": 86400,
"description": "Optional overall timeout in seconds for the whole generic batch. Normally omit; each atomic Action1 request still keeps its own timeout."
}
}
}