Power Automate MCP Server by Flow Studio

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

Adds real behavioral context beyond the annotations: the tool refuses when the flow is already in a solution, which tells the agent how failure states arise. Annotations already declare it is a non-destructive, idempotent write, so without a return format or permission requirements it lands at 4.

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

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

Three short, front-loaded sentences with no filler. The core action leads, the failure condition follows, and the optional-parameter note closes it out.

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

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

For a simple three-parameter mutation with no output schema and full schema coverage, the description covers the action, a failure mode, and the optional parameter default. It could still note what the call returns or the connection prerequisites, but nothing essential is missing.

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

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

Schema description coverage is 100%, so all three parameters including the discovery path for solutionId are already documented in the schema; the description only restates the optionality of solutionId. Baseline 3 applies when the schema carries the parameter burden.

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

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

States a specific verb and resource — moving a flow into a solution — which is unambiguous. No sibling tool performs a solution-assignment action, so differentiation is implicit rather than stated, keeping it at a 4 rather than a 5.

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

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

Usage is only implied; the description never says when an agent should reach for this tool versus other flow tools in the family. The 'omit for the default solution' note gives a small conditional hint but is not a when-to-use statement.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety and repeat-call profile is covered structurally. The description adds a useful eligibility constraint (only 'Running' runs), but says nothing about side effects on the run itself (terminated vs. rolled back), partial results, or any permission requirements beyond the status check.

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

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

Three short sentences, each earning its place: the action, the upstream call, and the precondition. The core action is front-loaded and nothing is repeated from the schema or annotations.

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

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

For a destructive, idempotent mutation with only three well-documented parameters and no output schema, the description supplies the key operational context (prerequisite tool, eligibility rule). It is nearly complete, though it omits any note on the effect on the run or error behavior when the status precondition fails.

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

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

Schema description coverage is 100% and all three parameters carry descriptions, so the schema does the heavy lifting; baseline 3 applies. The description merely echoes that runName comes from get_live_flow_runs, which the schema already states, and adds no format, casing, or identifier details for environmentName/flowName.

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

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

The description names a specific verb and resource ('Cancel a currently running Power Automate flow run') plus the scope qualifier 'via the live PA API', making it clearly distinct from siblings like resubmit_live_flow_run, trigger_live_flow, and set_live_flow_state. An agent can identify exactly what the tool operates on without opening the schema.

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

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

It gives an explicit prerequisite and sequencing rule ('Use after get_live_flow_runs to obtain the run name') and a precondition ('Only runs with status "Running" can be cancelled'), which tells the agent both when to call it and when it will fail. It stops short of naming a fallback when the precondition is unmet (e.g., what to do with non-Running runs), so it is a strong 4 rather than a 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds real context beyond them: it returns 'the raw properties object exactly as the PA API returns it' (no normalization), and the includeTriggerUrl credential warning is reinforced in the schema. It does not discuss size/rate limits for very large flows outside the depth hint.

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

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

Three sentences, no filler: what it fetches, the exact return shape, and the intended workflow use. The most decision-relevant information (raw native definition, use before update) is front-loaded.

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

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

There is no output schema, and the description compensates by stating the return is the raw PA properties object covering triggers/actions/parameters/outputs. Combined with 100% schema coverage and the readOnly annotations, an agent has enough to call it correctly. The only minor gap is guidance on handling very large flows, partly mitigated by the depth enum in the schema.

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

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

Schema description coverage is 100% and the schema itself documents depth, actions, includeTriggerUrl, flowName and environmentName in detail, including the credential nature of the trigger URL. The description only generally restates what the definition contains ('triggers, actions, parameters, outputs'), adding little beyond the schema. Baseline 3 applies.

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

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

States a specific verb and resource ('Fetch the full native Power Automate flow JSON from the PA API') and enumerates what the definition contains (triggers, actions, parameters, outputs). This distinguishes it from list_live_flows and the store-flow siblings, which return summaries or store metadata rather than the raw native definition.

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

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

Explicitly routes the agent: 'Use this to inspect the full definition before calling update_live_flow with a modified definition.' That names the sibling and the workflow context. There is no explicit when-not guidance (e.g., when to prefer the summary depth or a store-flow variant), which keeps it from a 5.

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

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

Annotations already cover the read-only/safe profile, and the description adds substantial context beyond them: what a repetition record contains (repetitionIndexes, status, error, resolved inputs/outputs), the "no Compose workaround needed" note, and why a checkId yields WorkflowRunNotFound from run tools.

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

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

Purpose is front-loaded and every clause carries information, but the ALL-CAPS labels (TRIGGER PAYLOADS, TRIGGER CHECKS) and multiple clauses make it denser than strictly necessary. Sized reasonably for an 8-parameter tool with interacting modes.

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

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

No output schema exists, so the description must convey returns, and it does name the key fields (repetitionIndexes, status, error, resolved inputs/outputs). The exact response envelope/shape is only sketched, leaving minor gaps for an 8-param tool.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds cross-parameter meaning the schema can't: the actionName/iterationIndex interaction and the runName-vs-checkId distinction with its error consequence. It stops short of richer format/syntax detail.

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

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

States a specific verb+resource ("Read the recorded inputs and outputs of actions in one flow run") and immediately distinguishes scoping modes: top-level actions without actionName vs. all foreach repetitions with actionName. This differentiates it cleanly from siblings like get_live_flow_run_error and get_live_flow_runs.

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

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

Explicit when-to-use guidance for every mode: iterationIndex to pin one iteration, trigger=true for trigger payloads, checkId for trigger evaluations that never became runs, plus a named source (get_live_flow_runs -> triggerChecks) and an exclusion ("Do not supply runName with a checkId").

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description usefully discloses that it hits the live Power Automate API and that results are per failed action, but says nothing about rate limits, empty-result behavior, or error cases for the call itself.

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

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

Two tight sentences with the core purpose and the payload shape front-loaded; nothing is redundant or padded.

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

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

For a read-only diagnostic tool with no output schema, the description gives an adequate picture of what comes back and the schema fully documents inputs. Minor gap: no guidance on what to do with a successful run (no failures) or how errors in the lookup itself surface.

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

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

Schema description coverage is 100%, so all four parameters (including the 'latest' shortcut and auto-pagination for top) are already documented in the schema. The description adds no parameter-level meaning beyond that, which is the expected baseline.

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

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

States a specific verb (Fetch) and resource (error details for a specific flow run) and even describes the return payload — failed actions with error code and message. This implicitly separates it from get_live_flow_runs (lists runs) and get_live_flow_run_action_outputs, though no sibling is named explicitly.

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

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

The phrase 'to help diagnose what went wrong' implies a debugging context, but there is no explicit when-to-use vs. when-not, no mention of the alternative tools for run data, and no stated prerequisites (e.g., run must have failed).

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description goes far beyond that by disclosing the return shape, the critical caveat that no runs does not mean the flow is healthy, the trigger-check mechanism, and the extra API-call cost of includeTriggerChecks.

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

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

The description is front-loaded with purpose, then return shape, then the important caveat. Most sentences earn their place, but there is mild redundancy in the two sentences explaining trigger checks, and the warning could be tightened slightly.

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

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

With no output schema, the description adequately explains the return object (runs, runCount, triggerChecks) and the fields of each run. It also covers the critical interpretation nuance about trigger checks, leaving nothing essential missing for correct invocation and understanding.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds real meaning for includeTriggerChecks by explaining when trigger check history is returned and why it matters (distinguishing 'nothing ran' from 'the trigger is failing'), which goes beyond the schema's brief note.

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

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

The description states a specific verb (Fetch) and resource (run history for a flow) and sources it to Power Automate, which implicitly separates it from store-flow siblings. However, it never explicitly names or contrasts with siblings like get_live_flow_run_error or get_store_flow_runs, so sibling differentiation is left to inference.

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

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

There is no explicit when-to-use versus alternatives; the agent must infer that this tool is for retrieving run history. The directive 'Read triggerChecks.byStatus before concluding a flow is fine' is a useful scenario cue, but it does not guide selection among sibling tools.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds material context beyond them: a Pro+ plan entitlement requirement and the important staleness caveat that the data is a cached snapshot rather than a live read.

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

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

Three front-loaded sentences with no waste: entitlement flag, core purpose, and the snapshot caveat in descending order of importance. Every sentence earns its place.

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

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

There is no output schema, and the description compensates by enumerating the returned fields. Combined with the entitlement and caching notes, an agent has everything needed to call it correctly.

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

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

Schema description coverage is 100%, so flowName and environmentName are already documented in the schema. The description lists output fields rather than adding syntax or semantics for the two parameters, so baseline 3 applies.

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

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

States a specific verb+resource — 'Get full details for a single Power Automate flow from the Power Clarity cache' — and enumerates the payload (trigger URL, owners, state, run statistics, governance metadata). It also distinguishes itself from the live siblings by noting data comes from a snapshot, not the live API.

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

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

The 'stored snapshot — not live from the Power Automate API' clause gives a clear context for when this is the right tool versus a live-fetch sibling like get_live_flow. It stops short of naming that alternative or stating exclusions explicitly, so it is clear context rather than full routing guidance.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), and the description adds real context beyond them: a plan gate, the fact that results come from a stored snapshot rather than the live API, and the default time window. It does not disclose truncation or pagination behavior for the 5000-row cap, which keeps it below a 5.

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

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

Four tight sentences, front-loaded with the plan requirement, then purpose, then scope/default, then return shape. No redundancy or filler; each sentence carries distinct information.

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

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

With no output schema, the description usefully enumerates the per-run fields returned and warns that data is snapshot-based, which is exactly what an agent needs before calling. It omits that results can be capped by the default top=5000, a minor gap for a read tool whose safety profile is already in annotations.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters including defaults and the status enum behavior. The description only restates the 7-day default window and lists returned fields, adding little parameter-level meaning beyond the schema.

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

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

States a specific verb and resource ('Get cached run history for a flow from the Power Clarity store') and uses 'cached' plus 'not live from the Power Automate API' to separate it sharply from sibling get_live_flow_runs. An agent can pick between them without opening either schema.

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

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

Gives the prerequisite ([Requires Pro+ plan]), the default window (last 7 days), and the key selection condition — use this for stored snapshot data rather than live API data. It stops short of explicitly naming get_live_flow_runs as the alternative when freshness is required, so it is clear context without a hard exclusion.

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

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

Annotations already declare the safe read profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the description's added value is the plan gating and the key staleness disclosure that the data comes from a cache snapshot rather than live API. That is genuinely useful behavioral context an agent could not infer from the annotations.

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

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

Two sentences with zero filler; the plan requirement and cache-vs-live caveat are front-loaded rather than buried. Every clause earns its place.

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

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

There is no output schema, but the description explicitly enumerates the returned metrics, so the agent knows exactly what it gets back. Combined with the plan gate, time-window scope, and cache caveat, nothing needed to call or interpret the result is missing.

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

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

Schema description coverage is 100%, including the startTime default of '7 days ago', so the schema already documents all four parameters. The description only says 'over a time window' and adds no format or semantics beyond the structured fields, matching the baseline 3 when the schema does the heavy lifting.

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

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

Specific verb+resource ('Get aggregated run statistics for a flow') with an enumerated list of the exact metrics returned (runs, success/failure counts, rates, avg/max duration). The 'aggregated ... from the cache' framing lets an agent separate this from raw-run siblings like get_store_flow_runs without opening either schema.

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

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

Clarifies the data source boundary ('stored snapshot — not live from the Power Automate API'), which implicitly routes the agent to live-API siblings when freshness is needed, and states a prerequisite ('[Requires Pro+ plan]'). It stops short of naming the alternative tool explicitly or stating when-not-to-use beyond the staleness caveat.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false). The description adds genuinely useful context beyond that: a Pro+ plan gate, that results come from a cache (implying possible staleness), and that the payload includes flow/app counts and an account-deleted flag.

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

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

Two compact sentences with the plan requirement front-loaded and zero filler. Every clause carries information the agent can act on.

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

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

There is no output schema, but the description compensates by naming the key return contents (flow/app counts, deleted-account status). For a single-parameter read tool, an agent has everything needed to call it correctly.

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

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

Schema description coverage is 100%, so makerKey and its AAD object ID meaning are fully documented in the schema. The description's '(usually the AAD object ID)' only marginally reinforces what the schema already states, landing at the baseline.

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

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

The description gives a specific verb ('Get details') and resource ('a single maker'), plus the lookup key and data source ('Power Clarity cache'). It implicitly separates itself from the sibling list_store_makers by specifying a single maker, though it never names that sibling explicitly.

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

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

It states a real prerequisite ('[Requires Pro+ plan]') and reveals that the lookup goes through a cache, which hints at when it is appropriate. However, it never says when to prefer this over list_store_makers or get_store_flow, leaving alternative selection to inference.

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

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

Annotations cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), but the description adds behavior the annotations cannot: the exact returned field set and the search-triggered side effect that each connection gains a paste-ready connectionReferenceTemplate plus hostTemplate. No contradiction.

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

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

Front-loaded with the purpose and tightly packed, but the long enumeration of return fields makes the opening sentence dense. Since there is no output schema the list earns its place; it is still slightly list-heavy rather than prose-efficient.

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

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

With no output schema present, the description carries the return shape, the search-triggered enrichment, and the downstream integration target. Nothing an agent needs to call this correctly or use its result is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description earns above it by explaining the intent behind search (produces templates that drop straight into update_live_flow) rather than restating the parameter. It omits detail on top's pagination ordering beyond what the schema already says.

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

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

States a specific verb+resource+scope: 'List Power Platform connections in an environment directly from Power Automate.' The scope phrase separates it from the store-side sibling list_store_connections and from list_live_environments, so an agent picks the right list tool without opening a schema.

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

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

Gives concrete usage direction: pass search=<term> to narrow the list, and names the downstream consumer (update_live_flow's connectionReferences and inputs.host). It does not state an explicit when-not or contrast against list_store_connections, so it stops short of a 5.

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

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

Annotations already cover read-only/non-destructive safety, yet the description adds genuinely non-obvious behavior: admin mode errors rather than returning a short list, isAdmin is null never false when the platform is silent, and isMember is always true. This is exactly the edge-case context an agent needs to interpret results.

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

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

Front-loads purpose and return fields, then layers mode semantics and field-flag caveats in a tight sequence. Some mode wording is duplicated verbatim between description and schema, which is the only waste.

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

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

With no output schema, the description carries the return-value burden and discharges it fully: it names the returned fields, explains pagination via 'top', and clarifies the isAdmin/isMember flag semantics. Nothing needed to call or interpret this tool is missing.

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

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

Schema coverage is 100% and the mode enum is fully documented in the schema; the description largely restates the same mode definitions. It adds a little by tying admin mode to the ListAnyFlow permission, but for the two parameters the schema does the heavy lifting, so baseline 3 applies.

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

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

States a specific verb and resource ('List all Power Platform environments you belong to, directly from Power Automate') and immediately enumerates the returned fields (id, displayName, sku, location, state). An agent knows exactly what this returns and how it differs from flow/connection listing siblings.

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

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

The three modes are spelled out with their selection conditions (member = environments you belong to; admin = only those you administer), and it cross-references list_live_flows mode=admin which needs this capability. It stops short of naming alternative tools such as list_store_environments, so no explicit when-not guidance.

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

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

Adds real behavior beyond the readOnly/destructive annotations: admin mode requires an admin account, deleted flows only surface via admin+includeDeleted, and pagination is time-bounded with a continuationUrl for resumption. It does not mention rate limits or result-size limits, keeping it from a 5.

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

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

Front-loaded with purpose then return fields, followed by mode semantics, filtering, and pagination in a logical order. Dense but nearly every sentence earns its place; the mode explanation is stated twice (sentence and schema) which is slight redundancy.

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

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

With no output schema, the description correctly compensates by naming the returned fields, and it covers the pitfalls an agent needs: admin requirement, deleted-flow access, and continuation-based pagination. Nothing essential for a correct call is missing.

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

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

Schema coverage is 100% and each parameter already carries a detailed description, so the schema does the heavy lifting. The description largely restates mode/search/includeDeleted semantics rather than adding new syntax or format detail, matching the baseline 3.

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

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

Opens with a specific verb+resource ('List Power Automate flows in an environment') and enumerates the returned fields (id, displayName, state, triggerType, lastModifiedTime). This clearly separates it from get_live_flow and the list_store_flows sibling.

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

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

Strong condition-based guidance: mode=owner for own/shared flows, mode=admin for environment-wide (requires admin account), and includeDeleted=true as 'the only way to find a deleted flow'. It does not address sibling alternatives like list_store_flows, so it stops short of a 5.

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

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

Annotations already cover readOnlyHint/destructiveHint/openWorldHint, so the safety profile is handled. The description adds genuinely new context beyond them: the return shape (one-line description plus tool names per bundle) and the non-billable cost note, which matters for an agent deciding whether to call it. It doesn't need to cover auth or rate limits for a zero-param listing.

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

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

Front-loads the definition, then the return shape, then the usage rule and alternative, ending with the cost note. Every sentence does work; the bundle-name enumeration is directly useful for routing rather than padding.

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

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

No output schema exists, but the description explicitly says what is returned (each bundle's one-line description and tool names) and where to get deeper definitions. With zero parameters and annotations covering safety, nothing needed to invoke this correctly is missing.

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

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

The tool takes no parameters, so the baseline of 4 applies. The description correctly avoids inventing parameter detail and instead spends its words on what the empty-input call yields.

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

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

States a specific verb (list) and resource (skill bundles), then defines what a bundle actually is and enumerates the available ones. This is clearly distinguishable from siblings like tool_search, which the description explicitly contrasts.

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

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

Gives an explicit trigger ('Use it when unsure which tools fit a request') and names the alternative with exact syntax ('tool_search "skill:<name>"') plus what that alternative returns instead. Nothing about tool selection is left to inference.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds two genuinely new facts: an entitlement gate (Pro+ plan) and that results come from a cache rather than live data.

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

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

A single tight sentence; the entitlement requirement is front-loaded in brackets and the scope follows immediately. Nothing is wasted.

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

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

For a zero-parameter read-only list tool with annotations carrying the safety profile and no output schema, this covers the essentials (what, source, plan gate). The only real gap is failing to note that cached results may be stale relative to list_live_connections.

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

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

The tool takes zero parameters, so there is no parameter semantics for the description to compensate for. The 4 baseline applies.

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

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

States a specific verb (List) and resource (Power Platform connections) plus the data source (Power Clarity cache), which implicitly distinguishes it from the sibling list_live_connections. It stops short of naming that alternative explicitly, so an agent must infer the cache-vs-live split.

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

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

The only contextual cue is the '[Requires Pro+ plan]' tag. There is no guidance on when to prefer cached connections over list_live_connections, nor any freshness/staleness caveat that would let an agent choose correctly.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds genuinely new context beyond that: the Pro+ plan gating and the fact that results come from a cache rather than live state.

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

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

A single sentence with the plan constraint front-loaded in brackets. Nothing is redundant and nothing needs trimming.

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

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

For a zero-parameter read-only list tool with annotations covering safety, the definition is nearly sufficient. The remaining gap is cache freshness — the description says results are cached but not how stale they might be or whether a refresh is possible, which matters for a cached-data tool.

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

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

The tool takes zero parameters, so there are no parameter semantics to convey and the baseline of 4 applies. The description correctly avoids inventing filtering options that the schema does not support.

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

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

States a specific verb and resource ("List all Power Platform environments") and qualifies the source as the Power Clarity cache, which implicitly separates it from the live sibling (list_live_environments). It does not name that sibling explicitly, so the differentiation is inferable rather than stated.

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

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

The "[Requires Pro+ plan]" tag gives a real prerequisite, but there is no explicit guidance on when to prefer this cached listing over list_live_environments. Usage is implied by the word "cache" rather than explained.

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

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

Annotations already cover the safety profile (readOnly, non-destructive, closed-world). The description adds genuinely useful context beyond them: the Pro+ plan gate and the important warning that data comes from a stored snapshot and may be stale relative to the live API.

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

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

Four short sentences, each carrying distinct information: plan requirement, action and source, filterable facets, return fields, and the staleness caveat. Front-loaded with the gating requirement and no filler.

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

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

With no output schema, the description helpfully enumerates key returned fields (trigger URL, state, run failure rate) and clarifies the data's freshness. It does not mention result limits or pagination, which is a minor remaining gap for a list tool.

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

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

Schema coverage is 100%, so each filter parameter is already fully documented in the schema. The description only groups them under 'governance flags (monitor, notification rules)', adding minimal meaning beyond the structured fields, which matches the baseline 3.

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

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

States a specific verb and resource (list Power Automate flows), names the data source (Power Clarity cache), and explicitly contrasts it with live API data, which cleanly separates it from siblings like list_live_flows and get_live_flow.

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

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

Gives a prerequisite ([Requires Pro+ plan]) and clarifies the cache-vs-live distinction so the agent knows this returns snapshot data rather than fresh results. It never names the live alternative explicitly ('use list_live_flows when you need current state'), so it falls just short of full routing guidance.

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

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

Annotations already establish the safe read-only, closed-world profile. The description goes beyond them by disclosing a licensing prerequisite (Pro+ plan) and the provenance of the data (served from the Power Clarity cache), which is actionable context an agent needs before calling.

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

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

A single sentence with the gating prerequisite front-loaded in brackets and no filler. Every clause (verb, resource, gloss, source) carries information.

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

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

For a no-parameter read-only listing tool with annotations covering the safety profile and no output schema to explain, the definition is nearly sufficient. It stops just short of noting result ordering, size, or whether the cache can be stale, which is the only remaining gap.

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

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

The tool takes zero parameters, so per the rubric the baseline is 4. There is nothing for the description to clarify beyond what the empty schema already communicates.

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

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

Specific verb+resource ('List all makers') with a clarifying gloss of the domain term ('citizen developers / AAD users') and the data source (Power Clarity cache). It reads as the plural counterpart to the sibling get_store_maker, though it never explicitly names that alternative to disambiguate.

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

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

The '[Requires Pro+ plan]' prefix is a genuine prerequisite that tells the agent when the call is even permitted, which is more than most list tools offer. However, there is no explicit guidance on when to use this versus get_store_maker for a single maker or the other list_store_* tools.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds genuine context beyond that: the Pro+ plan licensing requirement and the fact that results come from a cache (implying possible staleness and no live refresh), which are behavioral traits the annotations do not convey.

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

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

A single tight sentence with no filler. The plan prerequisite is front-loaded in brackets, though placing the conditional bracket ahead of the actual purpose is slightly less ideal than leading with the verb and resource.

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

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

For a zero-parameter, no-output-schema list tool the description is close to sufficient. It still omits what the returned apps contain (names, ids, connection references) and whether the cache list is paginated or filtered, so an agent cannot fully anticipate the response shape.

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

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

The tool takes zero parameters, so there is nothing for the description to clarify; the baseline of 4 applies. Adding parameter detail would be meaningless here.

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

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

The description gives a specific verb and resource: 'List all Power Apps canvas apps'. 'Power Apps canvas apps' is distinct from the sibling list_store_flows/connections/makers tools, so an agent can differentiate. However it never names a sibling explicitly and the 'from the Power Clarity cache' phrasing adds ambiguity rather than precision.

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

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

There is no when-to-use or when-not-to-use guidance relative to the many sibling list_store_* tools. The only conditional information is the '[Requires Pro+ plan]' prerequisite, which is a gating requirement, not usage guidance about selecting this tool over alternatives.

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

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

Annotations declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false, so the safety profile is already covered. The description adds genuinely useful context beyond that: quota-independent availability and a security warning against including secrets. However, it omits key behavioral traits like the chunking workflow (chunk/final_chunk), what 'notify' and 'include_diagnostics' do, and workflow sequencing across the append actions.

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

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

Two sentences, front-loaded with the core capabilities and followed by the security caveat. Efficient for the tool's breadth, with no filler, though the action list could be sharpened to match the enum exactly.

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

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

For an 18-parameter, multi-action tool with chunked uploading and no output schema, the description is under-developed. It never explains the report/append/status/list workflow, chunk sequencing, or the purpose of most parameters, so an agent would have to infer a lot from a sparse schema.

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

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

Schema description coverage is only 22% for 18 parameters, so the description must compensate and largely does not. It hints at the text-attachment path ('append text evidence') and warns about sensitive content, but leaves most parameters (ticket, notify, severity, category, environment_name, flow_name, tool_name, include_diagnostics, final_chunk, etc.) unexplained.

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

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

The description names concrete verbs and resources: reporting a bug or missing capability, appending text evidence, and checking reports. This maps reasonably to the multi-action enum (report/append/status/list) and is clearly distinguishable from the flow-oriented siblings. It loses a point because the four enum actions (especially the distinction between 'status' and 'list') aren't disambiguated.

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

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

Usage is implied by listing the three things you can do, and it notes the tool is 'Free and available even after quota is reached,' which is a useful when-to-use signal. There are no explicit exclusions or alternative routing, but no realistic siblings compete with it either.

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

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

Annotations declare non-read-only, non-idempotent, open-world, non-destructive; the description adds valuable behavior beyond that — it reuses the original trigger payload and auto-discovers the trigger name. It still omits whether a new run ID is created, what failure returns, or any permission requirements.

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

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

Two tight sentences, front-loaded with the action and scope, followed by the mechanism and the parameter-elimination note. No filler.

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

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

For a three-parameter mutation tool with no output schema, the description covers purpose, precondition, and payload handling adequately. It leaves minor gaps around post-resubmit behavior and error cases, but nothing an agent must know to invoke it is missing.

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

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

Schema description coverage is 100% (including the 'latest' shorthand for runName), so the baseline is 3. The description's note that no trigger-name parameter is needed adds context but is behavioral rather than clarifying an existing parameter's meaning.

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

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

States a specific verb and resource ('Resubmit a failed or cancelled Power Automate flow run') plus the key scope constraint (only failed or cancelled runs) and the mechanism (live PA API, re-using the original trigger payload). This cleanly separates it from siblings like trigger_live_flow (creates a new run) and cancel_live_flow_run.

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

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

Gives clear usage context: use it on a failed or cancelled run, and the original payload is reused rather than supplied. It does not explicitly name alternatives (e.g., trigger_live_flow for a fresh run) or state what happens if the run isn't in a resubmittable state.

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

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

Annotations already declare idempotentHint=true and destructiveHint=false, but the description adds real interpretation: it reads current state and skips the Power Automate call when no change is needed. That explains why the operation is idempotent and what actually happens on a no-op, which the hint alone does not convey.

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

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

Two short sentences, action front-loaded, with no restatement of the title. Minor waste in 'the flow you name,' which merely gestures at a parameter the schema already names precisely.

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

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

For a 3-parameter mutation with no output schema, the description covers what it does and the no-op behavior but says nothing about the outcome the agent gets back (confirmation, prior state, error on bad flow name). Adequate but with a visible gap.

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

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

Schema coverage is 100% with all three parameters documented, including the Started/Stopped enum, so the schema carries the load and baseline 3 applies. The description adds only the vague phrase 'the flow you name' and nothing about environmentName or accepted state values.

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

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

States a specific verb pair and resource ('Start or stop the flow you name'), so an agent knows this flips a named flow's state rather than describing or triggering it. It does not differentiate itself from siblings like trigger_live_flow or update_live_flow, which is the only thing keeping it off a 5.

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

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

There is no guidance on when to reach for this versus trigger_live_flow (run once) or update_live_flow (configuration change). The 'only calls Power Automate if a change is needed' sentence is behavioral detail, not a usage condition or exclusion.

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

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

Annotations already cover the safety profile (readOnlyHint, destructiveHint=false, openWorldHint=false). The description adds a genuinely new trait — 'Non-billable' — and characterizes query behavior (free text is 'ranked against name and description'), which the structured fields do not convey.

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

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

Front-loaded purpose sentence followed by a compact numbered list of query forms; every clause carries information and none is redundant. Appropriate length for a two-parameter tool with three distinct modes.

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

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

For a read-only search tool with no output schema, the description covers invocation modes, the result kind ('get its definition'), the max_results caveat, and cost. Nothing an agent needs before calling is missing, and sibling list_skills is named for the discovery edge case.

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

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

Schema coverage is 100%, so baseline is 3. The description goes slightly beyond the schema by giving a concrete free-text example ('cancel run') and stating the ranking basis, clarifying how the query parameter actually behaves rather than just restating the accepted forms.

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

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

States a specific verb+resource: 'Find a tool listed here... and get its definition', with the explicit motivation 'instead of guessing its name'. This distinguishes it cleanly from siblings like list_skills or get_live_flow, which retrieve different resources.

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

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

Gives the selection condition up front ('instead of guessing its name'), enumerates all three query modes, and routes the agent to list_skills for the skill names. Explicit when-to-use plus a named alternative, with nothing left to inference.

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

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

Annotations already cover the safety profile (readOnlyHint=false, idempotentHint=false, non-destructive). The description adds genuine behavioral context beyond them: scheduled recurrence flows execute immediately, take no inputs, and refuse a `body`, while automated connector triggers cannot be manually fired at all. It omits auth/permissions and expected success behavior.

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

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

Two dense sentences, front-loaded with the primary purpose and the portal analogy, then the trigger-type constraints. Every clause carries constraint information, though the middle sentence is information-packed.

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

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

No output schema exists, but the description covers the invocation-critical concerns for a non-idempotent mutation: which trigger types accept it, what inputs are valid, and what is rejected. It could say more about what is returned (e.g., a run id) but is otherwise adequate.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaning on top by clarifying that trigger inputs are passed as `body` and that `body` is refused for scheduled flows, tying the parameter to trigger-type behavior.

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

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

States a specific verb+resource (run/trigger a flow) and anchors it to the maker portal's "Run flow" button, making intent unambiguous. It clearly distinguishes the action from read/update siblings like get_live_flow and update_live_flow.

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

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

Explains precisely when the tool applies (Request triggers, manual Button, PowerApps) and when it cannot be used (automated connector triggers only fire from their source event), plus the scheduled-recurrence case. It stops short of naming sibling alternatives for the cases where it doesn't apply.

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

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

Annotations declare destructiveHint=true and idempotentHint=true, and the description adds real context beyond them: dryRun writes nothing on either path, Power Automate rejects contentless PATCH so rename re-saves the unchanged definition, operations apply to the LIVE definition, and the ' #flowstudio-mcp' suffix is appended to description. These are non-obvious behavioral traits, not restatements.

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

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

Front-loaded with the create/update split and dense throughout, but several details (operations path syntax, op meanings, connectionReferences edge cases) duplicate the schema's own descriptions, making it longer than strictly necessary. Every sentence is still informative, so it stops short of 5.

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

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

For an 8-parameter, nested-object, no-output-schema mutation tool, the description covers all the branching modes (create, update, surgical, whole-definition, rename, dry-run) plus connectionReferences sticking caveats. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is already 100%, but the description adds the exclusive/mutual relationships the schema cannot express: 'Provide EITHER operations OR definition', connectionReferences may accompany either and lands in the same save, and expectedLastModifiedTime is a concurrency guard. op semantics (set/add/remove/merge behaviors) are also spelled out.

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

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

States a specific verb+resource ('Update or create a flow') and immediately disambiguates the two modes via flowName presence. An agent can distinguish it from the read-only get_live_flow and the separate update_store_flow siblings without opening a schema.

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

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

Explicit when-to-use guidance: omit flowName to create (definition+displayName required), supply flowName to update, use dryRun to preview, use operations for surgical edits versus a whole definition, and pass displayName alone to rename. It also routes to get_live_flow as the source for a whole-definition update.

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

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

Annotations already declare idempotentHint=true, destructiveHint=false and openWorld=false, so the safety profile is covered; the description adds genuine context beyond that with merge semantics ('only fields provided are updated') and the fact that writes land in the cache rather than the live Power Automate API. It does not explain how a field is cleared or what the response contains.

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

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

Two tightly written sentences with the plan requirement and target resource front-loaded and the merge/cache behavior appended. No filler, though the bracketed plan notice interrupts the leading purpose statement slightly.

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

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

For an 18-parameter mutation tool with no output schema and low schema coverage, the description covers the safety and merge semantics well but omits clearing/removal semantics, tag overwrite vs append behavior, and return value. Adequate but with clear gaps.

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

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

With 18 parameters and only 33% schema description coverage, the schema leaves most fields undocumented (tier, security, critical, businessValue, businessJustification, supportEmail, supportGroup, ownerBusinessUnit). The description names a handful of updatable concepts and clarifies merge behavior, but does not explain what the undocumented fields mean or their expected value formats.

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

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

States a specific verb (update) plus the resource and the narrow field category (governance/metadata fields on a flow record in the Power Clarity store). The 'store' qualifier implicitly separates it from update_live_flow, but no sibling is named explicitly, so routing still requires inference.

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

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

Gives two real usage constraints: a Pro+ plan prerequisite and the note that it writes to cache rather than calling the Power Automate API, which helps an agent decide between this and update_live_flow. However, it never states when to prefer this tool over that sibling or what happens if used outside Pro+.

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