Power Automate MCP Server by Flow Studio

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

Annotations already declare the mutation, idempotency, and non-destructive profile, so the description's job is to add behavior detail. It does so by explaining that an unassigned flow falls into the default solution when `solution` is omitted, and that the operation is additive rather than a move ('stays in the one it is in'), which is context the agent could not infer from hints alone. It still says nothing about permissions or what the call returns.

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 tight sentences, front-loaded with the purpose and followed by the two conditional cases. The repetition of 'and stays in the one it is in' is slightly wordy but earns its place by preventing an incorrect 'move' mental model.

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 four-parameter mutation tool with no output schema, the description covers purpose, input selection, and the nuanced assignment semantics adequately. It does not describe permissions requirements or failure modes, which would round out an otherwise complete definition.

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; the description exceeds it by clarifying the condition under which `solution` can be omitted (unassigned flow) versus when it is needed, and by stating the mutual exclusivity of `flowName` and `app` in behavioral terms rather than just field notes. The default-solution outcome is genuinely new information not in 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?

The opening sentence names a specific verb and both supported resource types ('Add a flow or a canvas app to a solution'), which is precise enough that an agent can identify the operation without opening the schema. No sibling tool in the list performs solution assignment, so no explicit sibling contrast is needed.

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 the selection rule between the two mutually exclusive inputs ('Pass flowName or app') and describes the conditional behavior for flows not yet in a solution versus entities already assigned. What is missing is explicit guidance on when this tool should be chosen over an update-style sibling or what prerequisites the caller must satisfy.

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 only declare readOnly=false, openWorld=false, destructive=false, leaving the interaction model unexplained. The description fills that gap by disclosing that a sign-in card is surfaced to a human, that the agent must not authenticate on the user's behalf, the signInLink fallback, and that key/account-detail connectors are refused outright.

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, front-loaded with the primary action and its variant before the interaction and refusal rules. Slightly dense and mildly telegraphic ("Without the card"), but every sentence carries a distinct operational rule.

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 reasonably implies a returned signInLink and a sign-in prompt without exhaustively describing the response. For a non-destructive write with sparse annotations it covers the human-in-the-loop requirement and refusal cases well, though it doesn't state permissions or what state results after the person signs in.

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 are already documented in the schema, including connectionName's "existing connection to sign in again" meaning. The description repeats that semantic and adds no format, naming, or environment scoping detail beyond the schema, so the 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 ("Create a connection") and adds a second mode ("sign an existing one in again (pass connectionName)"), which tells an agent exactly what this tool produces. It never names a sibling such as list_live_connections or test_live_connection, so the differentiation from neighbors is inferred 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?

Gives explicit when-to-use, agent-behavior constraints ("you never sign in for them"), a fallback path ("give the person signInLink to open"), and a hard when-not rule with a named alternative destination ("Connectors that use a key or account details ... are refused: create those in Power Automate"). Routing decisions are fully determined by the text.

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, openWorldHint=false and destructiveHint=false, so the safety profile is covered; the description usefully adds what each mode returns (compact catalog, expanded inputs/outputs, dynamic parameter metadata, nextTool hints). It does not mention auth or permission requirements, and it references a non-existent 'mode' parameter when the schema calls it 'depth', which slightly muddies invocation.

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 core purpose and then organized by mode, with no filler. It is dense and slightly repetitive ('Use ... Use ... Use') and the depth/mode term drift is a small structural wart, but nothing is 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?

For a 9-parameter, no-output-schema tool this covers the decision space well: mode selection, cross-connector search, per-operation expansion, and nextTool handoffs. The main gap is the unexplained divergence between the description's 'mode' and the schema's 'depth' parameter, which an agent must resolve on its own.

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 real cross-parameter semantics beyond the schema: search without connectorName switches to cross-connector search, operationId enables expanded output, and variant selects among authored hints/examples. The only loss is the depth-vs-mode naming mismatch.

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 (describe a live Power Platform connector/API and its operations) and scopes it against the flow-oriented siblings like get_live_flow and update_live_flow. An agent can pick this out as the connector-metadata tool 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?

Gives explicit routing for each mode: summary as default, operationId for a single operation, search without connectorName for cross-connector lookup, and full only when raw OpenAPI metadata is required. It also names adjacent tools (resolve_live_parameters, update_live_flow) so the agent knows the natural next step.

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 readOnly/no-destructive, but the description goes well beyond by disclosing the response envelope, the fact that a trigger firing with no output produces a TRIGGER CHECK rather than a run, and the cost of includeTriggerChecks ('two extra API calls'). That is exactly the non-obvious behavioral context an agent cannot get from structured fields.

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 return shape, then the critical caveat, then the takeaway. Dense but every sentence carries a distinct point; the capitalized IMPORTANT and the closing restatement of the 'nothing ran vs trigger failing' distinction are slightly redundant.

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 still covers the returned fields, the trigger-check edge case, and the cost tradeoff of an optional parameter — enough for an agent to call it correctly and interpret the result without guessing.

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, but the description adds real meaning for includeTriggerChecks (checks are always reported when there are no runs, and the flag only matters when runs DO exist) and clarifies that time bounds apply to checks as well as runs. It says nothing about top/pagination semantics beyond the schema, keeping it from a 5.

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 run history for a flow directly from Power Automate') and immediately enumerates the return shape (runs, runCount, triggerChecks). The 'live' / 'directly from Power Automate' framing implicitly separates it from the store_* siblings, so an agent can select it 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?

Gives explicit interpretive guidance: when there are no runs, or when includeTriggerChecks is set, trigger check history is reported, and the agent is told to read triggerChecks.byStatus before concluding a flow is healthy. It does not, however, name when to prefer it over siblings like get_live_flow_run_error or get_store_flow_runs, so routing between related diagnostic tools is still 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 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?

The annotations already declare this is not read-only but also not destructive and not open-world; the description adds the crucial context that this is a user-facing interactive card rather than a data mutation, and that it 'creates nothing.' It also discloses the auth path (the dashboard's own sign-in) and the retry loop after the card reports granted. It does not say what happens if the person declines or never responds, which keeps it 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 sentences, front-loaded with the action, then the trigger, then the follow-up. Every sentence carries distinct information (what, when, and next step) with no restatement of the title or schema.

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 parameters, no output schema, and annotations covering the safety profile, the description supplies the pieces an agent actually needs: the user-facing nature of the card, the absence of creation, and the retry instruction. The only meaningful omission is the failure/decline path, which is a minor but real gap for an interactive consent flow.

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 disambiguate and the baseline of 4 applies. The description does not invent parameter-like behavior that would mislead an agent into passing arguments.

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 concrete action and resource: show a card so the person can grant Flow Studio access as themselves via the dashboard's sign-in. That is specific enough that an agent knows exactly what the tool does, and no sibling tool in the list does anything comparable. It stops short of explicitly contrasting with a named alternative, which keeps it at 4 rather than 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?

The trigger condition is stated precisely: 'Use it when a reply says one more sign-in is needed.' The description also gives the post-condition ('after the card says granted, retry the call that asked for it'), so the agent knows both when to invoke and what to do next. There are no plausible alternatives to route to, so the absence of exclusions is not a gap.

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 mark this as read-only, non-destructive, and closed-world. The description adds useful behavioral context beyond those fields: what the return contains, the non-billable cost profile, and how to escalate to tool_search for detailed guidance.

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 definition is front-loaded, then moves to return shape, then to usage and follow-up. Each sentence adds distinct value; the parenthetical examples are compact enough to aid recognition without dominating.

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 discovery tool with no output schema, the description is complete: it explains what the bundles are, what listing returns, when to use it, and how to get more detail via tool_search.

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?

There are zero parameters, so there is no per-parameter semantics to explain. The schema is empty and fully described, and the description correctly spends no space on nonexistent inputs.

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 resource (skill bundles), defines what they are, and names the exact return content. It also distinguishes this discovery tool from tool_search by explaining the different role each plays.

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 explicitly says when to use it: when unsure which tools fit a request. It also names tool_search as the follow-up path for full guidance and definitions, so the agent knows both the trigger and the alternative.

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 already declare readOnlyHint=true, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description still earns credit by disclosing the return shape ('rows, columns and nextLink'), which tells the agent how pagination and result inspection work — information not present in the annotations or schema.

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 with the read-only constraint and return shape front-loaded; little waste. The reference to 'update_canvas_app addDataSource' is the one slightly muddy clause, since that tool is not among the visible siblings, so an agent cannot act on it directly.

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 10-parameter, multi-connector tool with no output schema, the description does enough: it identifies the data sources, flags read-only, and names the return fields including the pagination link. What is missing is connector-specific caveats (e.g. that connector is omitted for Dataverse), though the schema already carries that.

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 every parameter including top, skip, filter, select, continuationUrl and connector is already documented at the field level. The description adds only the cross-reference to addDataSource for parameter alignment, which is a minor increment — baseline 3 is appropriate.

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 (read rows) and enumerates the concrete resource types it works against (Dataverse table, SharePoint list, SQL table, Excel table). An agent can tell this is a generic tabular read tool, though the only disambiguation offered is against the out-of-list 'update_canvas_app addDataSource' rather than any actual sibling tool.

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 'Read-only' and that it takes the same table/connector/dataset/connection as addDataSource, which implies it is the companion read operation to a canvas-app data source binding. But there is no explicit when-to-use versus when-to-use-something-else guidance and no stated preconditions or exclusions.

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?

The annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, but the description adds useful behavioral context: it runs the same lookups as the designer and never runs an action. It also mentions status behavior such as needs and how an unspecified connection is chosen.

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 dense but front-loaded: the core read-only resolution behavior comes first, followed by practical usage details. Every sentence contributes useful information for a complex 16-parameter tool.

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 complex tool with no output schema, the description explains the main return concepts such as dropdown options, columns, pickers, and statuses like needs and nomatch. It is not fully exhaustive about the response shape, but it is sufficient alongside complete schema descriptions.

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 16 parameters. The description still adds cross-parameter meaning, including that nested inputs are addressed by key and that omitting connectionName causes one to be chosen.

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 uses a specific verb and resource: it resolves a connector action's inputs the way the flow designer does. It also distinguishes the tool from actually running an action by stating it is read-only and never executes an action.

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 clearly explains usage modes: resolve every input in one call or a single input with parameterName, pass known values in parameters, and use match to turn a display name into a value. It does not explicitly compare against sibling tools, 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 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?

With readOnlyHint=false and destructiveHint=false already declared, the description adds the crucial nuance that despite executing an operation, only GET-style reads/lookups are permitted and non-conforming calls are refused pre-flight — this reconciles the mutation-capable annotation with safe behavior. It stops short of covering auth requirements, rate limits, or failure semantics.

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 core two-mode behavior, then constraints, then parameter provenance — a good information order with no filler sentences. The enumeration of lookup kinds ('dropdown, list, schema or folder picker') is dense but earns its place by bounding what is allowed.

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 6-parameter tool with a nested free-form 'parameters' object and no output schema, the description covers modes, the pre-flight rejection rule, and return shape at a high level ('returns the raw reply'). The gap is what the no-operationId test result looks like and pagination behavior, which is left entirely to the schema's continuationUrl note.

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 beyond it by documenting the omission semantics of operationId (falls back to the connector's own test) and the provenance of connectionName (list_live_connections) and operation ids (describe_live_connector).

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 ('Test a connection') and immediately splits it into two precise modes: connector self-test without operationId, single-operation invocation with operationId. It is unambiguous what the tool does, though sibling differentiation is only indirect (it names other tools as parameter sources rather than as alternatives it replaces).

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 explicit when-to-use rules for both modes ('Without operationId ... With operationId ...') plus an explicit exclusion: only GET operations and connector-declared lookups are allowed, and 'Anything else is refused before a call is made.' It also tells the agent where to obtain connectionName and operation ids, removing guesswork.

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?

Goes well beyond the annotations: explains that Power Automate rejects a PATCH with no flow content and that the tool re-saves the unchanged definition, that a connectionReferenceLogicalName save can return success without storing, that unreferenced connection references get pruned, and that ' #flowstudio-mcp' is appended to definition.description. These are exactly the non-obvious side effects an agent needs before a destructive write.

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, then organized under labeled modes (SURGICAL EDIT, WHOLE definition, RENAME). Dense but nearly every clause carries a decision rule; some statements about path arrays and connectionReferences duplicate the schema descriptions, which costs a point.

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 highly complex 8-parameter mutation tool with a nested operations object and no output schema, the description covers creation, update, rename, surgical edits, dry-run semantics, connection-reference edge cases, and the failure mode of empty PATCHes. An agent has enough to invoke it correctly without opening 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 coverage is 100% so the baseline is 3, but the description adds cross-parameter rules the schema does not state at the top level: operations requires flowName, connectionReferences may accompany either path and wins on key collision, and dryRun behaves differently with and without flowName. Only expectedLastModifiedTime is left to the schema alone.

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 pair and resource ('Update or create a flow') and immediately distinguishes the two modes by parameter (omit flowName to create, provide it to update). The surgical-edit path is named as a distinct operation mode, so an agent can tell what this does versus get_live_flow or set_live_flow_state in the sibling list.

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 for every mode: dryRun for preview, omit flowName to create, flowName alone to rename, operations vs definition mutual exclusivity ('Provide EITHER operations OR definition'), and a recommended workflow ('call get_live_flow, mutate properties.definition, pass it here'). Alternatives and prerequisites are named rather than inferred.

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.