power-automate-mcp

Overview Schema Source Related Servers Discussions Admin

update_flow_definition

DestructiveIdempotent

Replaces a Power Automate flow's complete definition after you edit it, without patch semantics. Use it to apply full flow changes and carry over or modify connection references.

Instructions

Replace a flow's definition. Send the COMPLETE definition - there is no patch semantics.

Standard use: get_flow -> edit the returned definition -> pass it here.

connection_references can be omitted on a flow already bound with bind_connection: the tool reads the live bindings and carries them over (get_flow shows {} for them, so there is nothing to copy by hand). Pass it explicitly only to CHANGE a binding, shaped like {"shared_office365": {"connectionName": "<32-hex connection id>", "source": "Embedded", "id": "/providers/Microsoft.PowerApps/apis/shared_office365"}}.

WHICH FLOWS THIS REACHES, corrected 2026-11-03. The old note here said any flow bound in the maker portal was out of reach. Measured 2026-07-28 on a flow built in My flows in the portal: its references come back with source "Embedded", and a PATCH carrying them succeeds. Keep the action hosts on connectionName exactly as stored. The real limit is SOLUTION flows. Their connections are Dataverse connection references: the PATCH wants connectionReferenceName, and the reference itself cannot be minted through this endpoint. For those, use update_solution_flow_definition in extras.py, which writes the Dataverse row.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "flow_id": "<flow_id>",
      "definition": "<definition>"
    },
    "name": "update_flow_definition"
  }
}

Input Schema

Name	Required	Description	Default
`flow_id`	Yes
`definition`	Yes
`connection_references`	No

Output Schema

Name	Required	Description	Default
`state`	No
`actions`	No
`flow_id`	No
`modified`	No
`triggers`	No
`warnings`	No
`definition`	No
`display_name`	No
`missing_connections`	No
`previous_definition`	No

Schema Changelog

Changes observed during successful MCP inspections.

First observedv2.1.0Nov 6, 2026

TDQS

A4.7/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructive/not-readOnly/idempotent, and the description adds substantial context beyond them: full-replacement semantics with no patch, live binding carry-over when connection_references is omitted, and the reachability limit for portal-bound versus solution flows. It loses a point for the dated changelog framing ('The old note here said...', 'corrected 2026-11-03'), which mixes historical correction narrative into what should be current behaviour.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The imperative and the canonical workflow are front-loaded, and each paragraph covers one concern. However, the closing section spends several sentences correcting a prior note rather than simply stating the current rule, and the capitalised heading style is inconsistent with the rest of the text.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive full-replace mutation with three loosely typed parameters, the description covers replacement semantics, the connection-reference special case, and the solution-flow escape hatch. An output schema exists, so return values need no explanation, and nothing needed for a correct call appears to be missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage the description carries the full burden and does so: definition is characterised as a complete replacement object, connection_references as omittable-with-carry-over unless a binding change is intended. It even supplies the literal payload shape ('connectionName', 'source', 'id') that the schema leaves undocumented.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The first sentence states a specific verb and resource ('Replace a flow's definition') and immediately qualifies the scope with 'Send the COMPLETE definition - there is no patch semantics.' It also names the neighbouring tools get_flow, bind_connection and update_solution_flow_definition, so the agent can distinguish this from siblings without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides an explicit canonical workflow ('get_flow -> edit the returned definition -> pass it here'), states when connection_references may be omitted versus when it must be passed, and routes solution flows to update_solution_flow_definition. When-to-use, when-not-to-use, and the alternative are all present.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server