Tool Reference

Source of Truth

If this document disagrees with tool_search, tools/list, or real API behavior, the API wins. Update this document accordingly.

Environment & Tenant Discovery

list_live_environments

Response: direct array of environments.

Use the id value as environmentName in all other tools.

list_store_environments

Same shape as list_live_environments but read from cache (faster).

Connection Discovery

list_live_connections

Response: wrapper object with connections array.

Key field: id is the connectionName value used in connectionReferences.

Key field: connectorName maps to apiId: "/providers/Microsoft.PowerApps/apis/" + connectorName

Filter by status: prefer overallStatus == "Connected" when present; otherwise check statuses[0].status == "Connected".

environmentName is required — the platform cannot list connections across environments (omitting it answers 400 MissingEnvironmentFilter). Get one from list_live_environments.

Pass search=<connector or account> to narrow output and receive connectionReferenceTemplate plus hostTemplate values that can be copied directly into update_live_flow.

list_store_connections

Same connection data from cache.

Flow Discovery & Listing

list_live_flows

Response: wrapper object with flows array.

Access via result["flows"]. id is a plain UUID — use directly as flowName.

mode indicates the access scope used ("owner" or "admin").

Parameters added in newer server versions:

• search: filter by display name server-side.
• mode: owner for flows owned by the MCP identity; admin for all flows visible to an admin account.
• timeoutSeconds: return partial results with nextLink instead of waiting on very large environments.
• continuationUrl: pass the previous nextLink to continue the same query.

list_store_flows

Response: direct array (no wrapper).

id format: <environmentId>.<flowId> — split on the first . to extract the flow UUID: flow_id = item["id"].split(".", 1)[1]

get_store_flow

Response: single flow metadata from cache (selected fields).

runPeriodDurationAverage / runPeriodDurationMax are in milliseconds (divide by 1000). runError is a JSON string — parse with json.loads().

Flow Definition (Live API)

get_live_flow

Response: full flow definition from PA API.

update_live_flow

Create mode: Omit flowName — creates a new flow. definition and displayName required.

Update mode: Provide flowName — PATCHes existing flow.

Response:

error is always present but may be null. Check result.get("error") is not None.

On create: created is the new flow GUID (string). On update: created is false.

Required fields can vary by server version. Use tool_search with select:update_live_flow before creating or patching a flow; if a description is required, include either the new description or the existing one from get_live_flow.

The flow description is part of the workflow definition (definition.description), not a top-level tool argument in current schemas.

add_live_flow_to_solution

Migrates a non-solution flow into a solution. Returns error if already in a solution.

Use this after creating a Copilot Studio Skills-triggered flow that must be discoverable as an agent tool. Pass solutionId for the target solution. If the server supports omitting solutionId, it uses the environment’s default solution; prefer an explicit unmanaged solution for production ALM.

This tool changes solution membership only. It does not validate the trigger schema, publish a Copilot Studio agent, or prove that the flow is callable by the agent.

Connector Operation Discovery

describe_live_connector

Describes a connector/API and its operations. Use it before creating connector actions instead of guessing operation JSON.

Common modes:

The operation detail can include:

• hint: authored guidance from the connector hints table.
• exampleDefinition: copy-ready action/trigger shape when available.
• Dynamic metadata with nextTool=get_live_dynamic_options or nextTool=get_live_dynamic_properties.

get_live_dynamic_options

Resolves live dropdown/list options for connector parameters. Use this for IDs selected from lists, such as SharePoint sites/lists, Teams teams/channels, or other x-ms-dynamic-list / x-ms-dynamic-values parameters.

Pass the dynamicMetadata object returned by describe_live_connector, the connection id from list_live_connections, and any already-resolved dependent parameters.

get_live_dynamic_properties

Resolves live schema/field properties for connector parameters. Use this for dynamic field sets such as SharePoint list item columns after the site and list are known.

Useful parameters:

• parameters: dependent values, for example { "dataset": "<site-url>", "table": "<list-id>" }.
• propertyName: request one field after inspecting the compact response.
• includeRaw: include raw connector schema only when needed; it can be large.

Run History & Monitoring

get_live_flow_runs

Response: direct array of runs (newest first).

top defaults to 30 and auto-paginates for higher values. Set top: 300 for 24-hour coverage on flows running every 5 minutes.

Run ID field is name (not runName). Use this value as the runName parameter in other tools.

get_live_flow_run_error

Response: structured error breakdown for a failed run.

failedActions is ordered outer-to-inner — the last entry is the root cause. Use failedActions[-1]["actionName"] as the starting point for diagnosis.

get_live_flow_run_action_outputs

Response: array of action detail objects.

actionName is optional: omit it to return top-level actions in the run. Provide it for a specific action. If that action runs inside a foreach, the tool can return every repetition of that action across iterations; pass iterationIndex to pin to one zero-based iteration.

Outputs can be very large (50 MB+) for bulk-data actions. Use 120s+ timeout.

Run Control

resubmit_live_flow_run

Response: { flowKey, resubmitted: true, runName, triggerName }

cancel_live_flow_run

Cancels a Running flow run.

Do NOT cancel runs waiting for an adaptive card response — status Running is normal while a Teams card is awaiting user input.

HTTP Trigger Tools

get_live_flow_http_schema

Deprecated. Prefer get_live_flow and inspect the Request trigger’s inputs.schema plus any Response actions directly from the definition.

Response keys:

The request body schema is in requestSchema (not triggerSchema).

get_live_flow_trigger_url

Deprecated. Prefer trigger_live_flow when you need to run a flow; it fetches the callback URL internally for HTTP triggers and uses the connector runtime for Button and PowerApps triggers, which have no callback URL.

Returns the signed callback URL for HTTP-triggered flows. Response includes flowKey, triggerName, triggerType, triggerKind, triggerMethod, triggerUrl.

trigger_live_flow

Response keys: flowKey, triggerName, triggerKind, invocation, triggerUrl, requiresAadAuth, authType, responseStatus, responseBody, runName, and warning when a required trigger input was not supplied.

Works for Request triggers (HTTP request, Button, PowerApps) and for scheduled (Recurrence) flows. A scheduled flow runs immediately, like the portal’s “Run flow” button, and takes no body — one is refused. Automated connector triggers only fire from their source event and return an error.

HTTP triggers go through the signed callback URL (invocation: callbackUrl). Button and PowerApps triggers have no callback URL; with a body they run through the Power Platform connector runtime (connectorFlowToken or connectorApihubToken), which is the only route that delivers the inputs. With no body they use the cheaper direct run (directRun).

runName is returned only for connector-runtime runs. Otherwise look the run up with get_live_flow_runs.

Power Automate does not enforce a trigger’s required list. A missing input still starts the run with a null value; warning names the missing keys and the body shape to retry with.

Browser-extension keys cannot reach the connector runtime, so Button and PowerApps triggers run only with an empty body over that key type. The error lists the alternatives (resubmit a past run, default the inputs inside the flow with coalesce(), or use a standard key).

responseStatus + responseBody contain the flow’s Response action output. AAD-authenticated triggers are handled automatically.

Content type: body is sent as application/json, so triggerBody() and the trigger schema see the object you passed. Verified 2026-08-27 on server 1.2.43 against Button, PowerAppV2, and Skills triggers with required schemas.

Flow State Management

set_live_flow_state

Start or stop a Power Automate flow in any environment you have access to. Reads the current state first and only issues the start/stop call if a change is actually needed.

Parameters: environmentName, flowName, state ("Started" | "Stopped") — all required.

Response:

Use this tool — not update_live_flow — to start or stop a flow. update_live_flow only changes displayName/definition; the PA API ignores state passed through that endpoint.

set_store_flow_state

Start or stop a flow via the live PA API and persist the updated state back to the Power Clarity cache. Same parameters as set_live_flow_state but requires a Power Clarity workspace.

Response (different shape from set_live_flow_state):

Prefer set_live_flow_state when you only need to toggle state — it’s simpler and has no subscription requirement.

Use set_store_flow_state when you need the cache updated immediately (without waiting for the next daily scan) AND want the full updated governance record back in the same call — useful for workflows that stop a flow and immediately tag or inspect it.

Store Tools — FlowStudio for Teams Only

get_store_flow_summary

Response: aggregated run statistics.

get_store_flow_runs

Cached run history for the last N days with duration and remediation hints.

get_store_flow_errors

Cached failed-only runs with failed action names and remediation hints.

get_store_flow_trigger_url

Trigger URL from cache (instant, no PA API call).

update_store_flow

Update governance metadata (description, tags, monitor flag, notification rules, business impact).

list_store_makers / get_store_maker

Maker (citizen developer) discovery and detail.

list_store_power_apps

List all Power Apps canvas apps from the cache.

Behavioral Notes

Non-obvious behaviors discovered through real API usage. These are things tool schemas cannot tell you.

get_live_flow_run_action_outputs

• actionName is optional: omit to get top-level actions, provide to get one action. For actions inside foreach loops, a named action may return multiple repetitions; use iterationIndex to pin to one iteration.
• Outputs can be 50 MB+ for bulk-data actions — always use 120s+ timeout.

update_live_flow

• Required fields can vary by server version; confirm with tool_search (select:update_live_flow) before create/update. If description is required, preserve the existing description when patching.
• error key is always present in response — null means success. Do NOT check if "error" in result; check result.get("error") is not None.
• On create, created = new flow GUID (string). On update, created = false.
• Cannot change flow state. Only updates displayName, definition, and connectionReferences. Use set_live_flow_state to start/stop a flow.

trigger_live_flow

• Works for HTTP, Button, PowerApps, and scheduled (Recurrence) triggers. A scheduled flow runs with no body. Automated connector triggers error.
• Pass trigger inputs as body. A warning in the result means a required input was missing and the run started with it null.
• AAD-authenticated triggers are handled automatically (Bearer token attached).

get_live_flow_runs

• top defaults to 30 with automatic pagination for higher values.
• Run ID field is name, not runName. Use this value as runName in other tools.
• Runs are returned newest-first.

Teams PostMessageToConversation (via update_live_flow)

• “Chat with Flow bot”: body/recipient = "user@domain.com;" (string with trailing semicolon).
• “Channel”: body/recipient = {"groupId": "...", "channelId": "..."} (object).
• poster: "Flow bot" for Workflows bot identity, "User" for user identity.

list_live_connections

• environmentName is required; the platform cannot list connections across environments. top is applied after search and the result carries truncated + matchedCount when the cap drops matches.
• Use search=<connector/account> to get smaller output and paste-ready connectionReferenceTemplate / hostTemplate values.
• id is the value you need for connectionName in connectionReferences.
• connectorName maps to apiId: "/providers/Microsoft.PowerApps/apis/" + connectorName.