Power Automate MCP Server by Flow Studio

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

Annotations already mark this as a mutating (readOnlyHint=false), non-destructive, idempotent operation. The description adds the non-obvious guard behavior that an already-solutioned flow is rejected, and clarifies that omitting solutionId targets the default solution, which is useful beyond annotation data. No contradiction with 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 short sentences, no filler, with the main action and key guard placed first. The second sentence gives the one parameter nuance worth calling out before invoking.

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?

Given that all parameter semantics are fully documented and the guard behavior is disclosed, this is reasonably complete for a mutating tool without an output schema. It does not describe return values, but the absence of an output schema and the simple success/failure behavior makes that a minor 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 description coverage is 100%, so the schema already explains all three parameters, including how to discover solutionId. The description adds only a restatement that solutionId is optional for the default solution, which is already 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 description opens with a specific verb and resource ('Move a flow into a solution') and immediately distinguishes itself from siblings like update_live_flow or set_live_flow_state by naming the solution-migration operation. It also specifies the key guard condition, so the tool's function is unambiguous.

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 clarifies the main conditional for invoking it ('Refuses if the flow is already in one') and explains the optional parameter's behavior, but it never points to any sibling or states when an alternative should be used instead. The usage context is implied from the name and action rather than explicit.

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 indicate destructiveHint=true and idempotentHint=true, so the mutation risk is known. The description adds value by disclosing the running-status requirement and the prerequisite call, which are not visible in the annotations or schema. It does not contradict any annotation.

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 operation, followed by the required sequence and constraint. Every sentence earns its place and there is no redundant wording.

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?

Given the tool's simple parameter set (all documented), the acknowledged destructive hint, and the absence of an output schema, the description covers what an agent needs to call it correctly: the precondition, the parameter source, and the target state. No significant missing context.

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 each parameter already has a clear description (e.g., runName is identified as the name field from get_live_flow_runs). The description reinforces the relationship to get_live_flow_runs but adds no new parameter-level semantics 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?

Description states a specific action (cancel) on a clearly defined resource (currently running Power Automate flow run) via the live PA API. It is distinct from sibling tools like resubmit_live_flow_run or set_live_flow_state because the target and operation are unambiguous.

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 tells the agent to call get_live_flow_runs first to obtain the run name, and states the only valid precondition: status 'Running'. This gives clear when-to-use guidance and a when-not-to-use condition (non-Running runs).

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 safety is covered. The description adds meaningful behavioral detail beyond annotations: what each mode returns, that operationId includes dynamic parameter metadata, that nextTool hints route to resolve_live_parameters, and that variant handling exists for authored variants like shared_teams/PostMessageToConversation.

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 every sentence earns its place. It front-loads the primary purpose and then systematically explains mode usage, search behavior, and when to use full mode, without repeating schema field descriptions or 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?

There is no output schema, so the description carries the burden of explaining return value semantics. It covers the compact catalog, expanded operation details, dynamic parameter metadata, nextTool hints, and canonical example shapes, while also linking to sibling tools. The parameter interactions are sufficiently covered by the schema and description together.

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 combinatorial and workflow semantics: how mode, operationId, search, connectorName/apiName, and variant interact, and what each returns. It clarifies that connectorName/apiName can be omitted when search is used, and that full mode is for raw metadata only.

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.' It clearly distinguishes the tool by its modes (summary, operationId, cross-connector search, full) and references alignment with Canvas MCP describe_api, making its purpose immediately identifiable relative to sibling get/list tools.

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?

Provides explicit when-to-use guidance for each mode: mode=summary for a compact catalog, operationId for one operation, search without connectorName/apiName for cross-connector search, and mode=full only when raw OpenAPI metadata is required. It also names downstream tools (resolve_live_parameters, update_live_flow), giving practical routing context.

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 tool's safety profile is clear. The description adds value beyond annotations by stating it returns the raw properties object exactly as the PA API returns it and that it includes the complete definition, which helps the agent expect unfiltered, exact output.

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 three sentence-fragments long, with no filler. It front-loads the core purpose, then states the return behavior, then gives usage guidance. Every sentence contributes useful, non-redundant 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?

This is a simple read-only getter with two fully described parameters and no output schema. The description explains what the return value is, what it contains, and how it should be used in a larger workflow. Nothing essential is missing for an agent to select and invoke the tool 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 both parameters (flowName and environmentName) are already documented in the input schema. The description does not add meaning about the parameters themselves, so the baseline score of 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 uses a specific verb ('Fetch') and names the exact resource: the full native Power Automate flow JSON from the PA API, including triggers, actions, parameters, and outputs. This distinguishes it clearly from related flow tools like get_live_flow_runs, get_live_flow_http_schema, 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?

The description explicitly recommends using this tool to inspect the full flow definition before calling update_live_flow with a modified definition. This gives the agent a concrete usage context, though it does not explicitly state when not to use it or compare it against other read-only flow siblings.

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 flag this as read-only and non-destructive, and the description adds meaningful behavioral detail beyond that: it explains that a checkId is not a run id and would otherwise return WorkflowRunNotFound, how repetitions are surfaced, and how trigger evaluations that never became runs can be inspected. It also clarifies the return contents such as status, error, and resolved inputs/outputs.

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 well-organized, with clear mode labels and front-loaded purpose. Despite the length, each sentence contributes necessary usage detail; the structured breaks for trigger payloads and trigger checks make the complexity navigable rather than overwhelming.

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, so the description carries the burden of explaining return behavior. It does so well: it names the per-repetition fields, explains trigger input/output returns, describes how to retrieve failed trigger checks, and connects to get_live_flow_runs for obtaining checkId and runName. Given the tool's complexity, this is unusually complete.

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?

Although the input schema already documents all 8 parameters at 100% coverage, the description adds crucial cross-parameter semantics: actionName and iterationIndex interaction, runName required unless checkId is supplied, trigger requiring runName, and the checkId provenance. These relationships are not obvious from the schema alone and materially improve correct invocation.

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 opens with a specific verb and resource: 'Read the recorded inputs and outputs of actions in one flow run.' It then clearly distinguishes the main modes (top-level actions, per-action repetitions, trigger payloads, trigger checks), making it easy for an agent to tell this from siblings like get_live_flow_runs or get_live_flow_run_error.

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 description gives explicit conditional guidance: when to omit actionName, when to provide iterationIndex, when to use trigger=true, and when to pass checkId instead of runName. It even states the exclusion directly: 'Do not supply runName with a checkId.' This is strong when-to-use versus when-not-to-use 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 declare readOnly and non-destructive behavior. The description adds value by disclosing what the tool returns: each failed action with its error code and message. It does not cover pagination behavior or empty results, but the annotation safety picture is already complete.

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 no filler: the first identifies the operation and resource, the second identifies the output shape and purpose. It is front-loaded and 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?

All required parameters are documented, the output semantics are described, and the read-only behavior is covered by annotations. There is no explicit mention of the empty/no-error response, but the definition is complete enough for an agent to call the tool 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 every parameter is already well documented. The description does not add new parameter-level semantics beyond the overall context of retrieving failures, so the 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?

States a specific action ('Fetch error details'), a specific resource ('a specific flow run from the live Power Automate API'), and a concrete outcome ('Lists every failed action with its error code and message'). This clearly differentiates it from sibling tools that list runs or fetch action outputs.

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?

Provides clear context: this is the tool to use when diagnosing what went wrong in a flow run. It does not explicitly name alternatives or state when-not-to-use them, so it stops short of a 5, but the intended use is evident.

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 the tool as read-only and non-destructive, so the description adds substantial value on top: it explains that a trigger can fire without creating a run, that trigger checks are reported when there are no runs, and that the agent must read triggerChecks.byStatus before concluding a flow is fine. This is exactly the kind of non-obvious behavioral disclosure that annotations cannot capture.

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 focused and front-loaded with the core action and return shape. The IMPORTANT caveat is long but earns its place because it prevents a common misinterpretation of the results. It is slightly redundant with the schema's includeTriggerChecks note but still well structured.

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 supplies the return object shape, per-run fields, trigger check semantics, and the key interpretation trap. Combined with complete schema parameter documentation and read-only annotations, an agent has enough information to call the tool correctly and interpret its results meaningfully.

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 does reinforce the meaning of includeTriggerChecks and explains the significance of triggerChecks in the response, but it does not add new parameter-level constraints or syntax beyond what the schema already states.

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 opens with a specific verb and resource: 'Fetch run history for a flow directly from Power Automate.' It also names the exact return shape ({ runs, runCount, triggerChecks }), which clearly distinguishes it from per-run detail tools like get_live_flow_run_error and from store-flow run tools like get_store_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?

The description provides excellent context about when trigger checks are included and warns that no runs does not mean the flow is healthy. However, it does not explicitly state when to use this tool versus siblings such as get_live_flow_run_error, get_live_flow_run_action_outputs, or get_store_flow_runs. Usage is implied rather than stated as a decision rule.

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 and non-destructive, so the bar is lower. The description adds useful context beyond that, including a plan requirement and the cache/snapshot behavior. It doesn't describe error cases or staleness, but for a safe read operation this is sufficient.

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 compact and front-loaded: first the action and resource, then the key caveats. Every sentence contributes value, and there is no repetition of the tool name 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?

For a simple read operation with only two string parameters, the description covers the source, the scoping, and the general content of the response. It could explicitly mention what happens if the flow is not in the cache, but the overall guidance is 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?

The input schema fully documents both parameters with descriptions, and schema coverage is 100%. The description does not add any parameter-level meaning, so the baseline of 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 clearly states what the tool does: 'Get full details for a single Power Automate flow from the Power Clarity cache.' It further distinguishes itself by specifying the data source is a stored snapshot, not the live API, which separates it from siblings like 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?

The description communicates when to use this tool: when full flow details are needed from the cached snapshot rather than live API data. It doesn't explicitly list alternative tools, but the 'not live from the Power Automate API' clause provides a clear exclusion criterion that helps route the agent.

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 annotations already indicating readOnlyHint=true and destructiveHint=false, the description adds valuable context: Pro+ plan requirement, cached snapshot behavior, default 7-day window, and the exact returned run fields. It also clarifies the data source limitation, which is genuinely useful beyond what annotations 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?

The description is compact and well-structured. The key distinction (cached vs live) and usage precondition appear first, while the return fields are listed efficiently. Every sentence earns its place without unnecessary detail.

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 query with no output schema, the description covers the essential missing context: return fields and units of measure. Together with the fully described input schema, annotations, and the Pro-plan requirement, an agent has enough to invoke 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?

The input schema has 100% description coverage, so the schema already explains each parameter. The description adds the default time window and return-field context, but does not add deeper parameter semantics beyond what the schema provides. A 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 clearly identifies the operation: getting cached run history for a flow from the Power Clarity store. It distinguishes this from live-flow tools by explicitly saying the data is from a stored snapshot, not live from the Power Automate API, which separates it from siblings like 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?

The description provides clear usage context: it is for cached run history, defaults to the last 7 days, and requires Pro+ plan. It implies the alternative is a live API call by saying the data is 'not live', but it does not explicitly name get_live_flow_runs or state when to choose one over the other.

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 indicate the operation is read-only and non-destructive. The description adds valuable behavioral context: results come from a stored snapshot rather than live API calls, which informs freshness expectations. The Pro+ plan prerequisite is also disclosed. No contradiction with 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 tight sentences: the first states what stats are returned, the second clarifies the cached nature and disambiguates from live data. No filler or repetition of schema content.

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 the fields returned. The CEO at cached data and caches. The only minor gap is not pointing to sibling tools for live access or detailed run logs, but the essential calling information is present.

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 are already documented clearly. The description only reinforces that statistics are aggregated over a time window, which maps to startTime/endTime, but adds no new parameter 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?

Description opens with a specific verb+resource: 'Get aggregated run statistics for a flow from the Power Clarity cache.' It precisely enumerates the statistics returned (total runs, success/failure counts, rates, durations), and explicitly contrasts with live Power Automate API data, which separates it from the live flow 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?

Clear context is provided: the tool returns cached aggregated stats, not live data, and requires a Pro+ plan. This implies when it should be used over live equivalents, though it does not explicitly name alternative tools such as get_live_flow_runs or get_store_flow_runs.

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, and the description adds useful behavioral context by noting it requires a Pro+ plan and reads from a cache, which signals that data could be cached rather than live. It also previews the included data (flow/app counts, deleted status), going beyond 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?

The description is a single, dense sentence that conveys the plan requirement, action, source, key type, and certain return fields. There is no fluff, no repetition of the tool name, and every clause has informational or serving value. It is appropriately sized and easy to parse.

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 single-parameter getter with no output schema and very simple input, the description covers the essential context: input form, cache nature, and in summary of return data. It does not describe what happens when the maker key is not found or whether the cache is refreshed, but those are minor for a simple lookup 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 description coverage is 100% with makerKey documented as 'Maker RowKey (AAD object ID of the user).' The description adds a small but valuable reinforcement—italics 'by the maker (usually the AAD object ID)'—which helps the agent understand what to pass. Since the schema already covers the parameter, the description adds a little extra rather than a lot, so 4 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 states a specific verb ('Get'), resource ('details for a single maker'), and scope ('from the Power Clarity cache by their key'). It also names the distinguishing return contents (flow/app counts, deletion status), and the singular/scoped phrasing clearly separates it from other getters like get_store_flow or list_store_makers.

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 usage context is clear: call this tool when you already have the maker's key and want details for that single maker, rather than using list_store_makers. It does not explicitly name alternatives or exclusions, but the 'single maker by key' phrasing strongly implies the appropriate scenario.

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 readOnlyHint=true and destructiveHint=false, so the description adds behavioral value by disclosing search behavior, automatic pagination, the paste-ready nature of templates, and the full createdBy object. This enriches the agent's understanding beyond the structured annotation 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?

The description is dense and front-loaded with the core action before enumerating return fields. The field list is long but earns its place given there is no output schema; the second sentence efficiently conveys search behavior and the downstream integration.

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 list tool with no output schema, the description is complete: it names the primary purpose, all return fields, parameter-specific effects, pagination, environment requirements, and how results feed into update_live_flow. 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?

Input schema coverage is 100%, so the description need not restate parameter basics. It adds meaningful downstream semantics: search triggers addition of connectionReferenceTemplate and hostTemplate, and these can be dropped directly into update_live_flow without edits, which goes beyond the schema text.

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'), scoped to an environment and 'directly from Power Automate', which distinguishes it from sibling list_store_connections. The description also enumerates the returned fields, making the tool's purpose concrete and unambiguous.

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?

Provides clear context for when to use the tool: pass search to narrow results, call list_live_environments if lacking an environment, and use the returned templates with update_live_flow. It does not explicitly contrast with list_store_connections, but the live-vs-store sibling naming and environment scoping largely carry that distinction.

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. The description adds transparency by specifying that mode=admin errors if access cannot be determined, and explains the semantic of isAdmin and isMember 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?

The description is well-structured with a summary and parameter details, but the mode explanation is repeated verbatim in the top-level description and parameter description, adding minor 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?

The description mentions the return fields (id, displayName, sku, location, state) and explains mode semantics sufficiently. No output schema is provided, but the description covers necessary context for a read-only list operation.

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 description enriches both parameters: top explains pagination and omission default; mode explains each enum value and the admin error case.

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?

Clearly states the verb 'list' and resource 'Power Platform environments', with return fields listed. Distinguishes from sibling list_store_environments by specifying 'live' directly from Power Automate.

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?

Provides explicit guidance on mode parameter values, defaults, and error behavior. Does not explicitly name alternative sibling tools, but the 'live' vs 'store' naming implies the distinction, and the mode conditions are clear.

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, and the description adds substantial behavioral context beyond that: the distinction between owner and admin modes (including permission requirements), the behavior of includeDeleted (returning soft-deleted flows), time-bounded pagination with nextLink, and the requirement for continuationUrl to match the original mode. No contradictions with 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?

The description is dense but well-organized, starting with the core purpose and moving through modes, filtering, and pagination. Every sentence adds value, and the structure is logical. It is slightly long but justified given the number of parameters and behaviors it must explain; still, it could be trimmed slightly without loss.

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 7 parameters and no output schema, the description carries the full burden of explaining what the tool returns and how pagination works. It lists the return fields (id, displayName, state, triggerType, lastModifiedTime), explains mode-dependent scoping, and covers the continuationUrl mechanism. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, but the description enriches several parameters: it clarifies that includeDeleted requires mode=admin and is off by default, that continuationUrl must match the original mode, that top paginates automatically, and that timeoutSeconds limits collection. These details are not in the schema descriptions and are essential for correct invocation.

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 clearly states the verb (list), resource (Power Automate flows), and scope (in an environment). It enumerates the returned fields and distinguishes modes (owner vs admin) and the inclusion of deleted flows. This sets it apart from siblings like get_live_flow (single flow) and list_store_flows (store flows), so an agent can immediately identify the correct 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?

The description gives explicit guidance on when to use each mode: owner for user-scoped flows, admin for all flows with admin privileges, and admin+includeDeleted for finding deleted flows, explicitly stating this is 'the only way to find a deleted flow.' It also explains the search filter and pagination continuation, leaving no ambiguity about when to call this tool.

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 readOnlyHint and destructiveHint false; the description adds value by specifying the return contents and the non-billable trait. It also explains that the tool only lists descriptions and member names, not full tool definitions, which is relevant behavioral context beyond 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?

The description is concise and well-structured: the main purpose is front-loaded, followed by return value details, and then an explicit usage handoff. Every sentence earns its place, and the skill bundle examples help the agent understand the domain without 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 no-parameter read-only listing tool, the description is complete: it states what is returned, the context for calling it, the recommended follow-up action, and cost implications. No required information appears missing for an agent to correctly invoke and use this 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 document; the schema and signal data fully cover this. The description appropriately focuses on behavior and usage rather than empty parameter documentation.

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 skill bundles' with a precise definition of what a skill bundle is and what the call returns (description and member tool names). This clearly differentiates it from the many list_* sibling tools that enumerate concrete resources like flows, apps, or connections.

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 instructs when to use it: 'Call this first when you are unsure which tools apply to a request.' It also tells the agent exactly what to do next, calling tool_search with 'skill:<name>', and notes the operation is non-billable. This leaves no ambiguity about its role versus 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 flag this as read-only and non-destructive, and the description adds useful context: the Pro+ plan requirement and the fact that data comes from a cache rather than live systems. It could be more transparent about possible staleness or output behavior, but the provided context goes beyond the structured 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?

The description is a single, tightly packed sentence with the access requirement front-loaded and the core operation clear. Every part of the sentence adds information; there is no redundancy or 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 zero-parameter, read-only list operation, the description covers the essential information: what it lists (Power Platform connections), where it gets them (Power cache), and the access requirement (Pro+ plan). It does not explain what Power Clarity is or whether cached results may be stale, but these are minor gaps for such a simple 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 has zero parameters and the schema has 100% coverage, so there are no parameter semantics to clarify. The description correctly implies a no-argument list operation. This matches the baseline for a parameterless tool.

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 action and resource: 'List all Power Platform connections,' with a clear source ('from the Power Clarity cache'). It is readable and distinguishes itself from live connection listing implicitly through the cache qualifier, though it does not explicitly name siblings or contrast with list_live_connections.

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?

No when-to-use or when-not-to-use guidance is provided. It does not mention alternatives like list_live_connections or explain when the cached list is appropriate instead of the live one. The only context is the Pro+ requirement.

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, and the description stays consistent with them. It adds value beyond annotations by disclosing a Pro+ plan requirement and 'from the Power Clarity cache,' implying cached, possibly stale 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 declarative sentence that front-loads the access requirement and describes the exact resource and source. There is no redundant or extraneous text.

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 tool it is adequate, but there is no explicit comparison to the near-sibling list_live_environments, and since no output schema exists, the description could have briefly noted what the returned list represents. The missing return-shape context leaves a modest 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 has zero parameters and schema description coverage is 100%, so there are no parameter semantics to add. The baseline of 4 applies because there is no input surface requiring documentation.

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 ('List'), resource ('Power Platform environments'), and source ('Power Clarity cache'). This clearly distinguishes it from sibling list_live_environments by implying a cached data store.

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?

No guidance is given on when to use this tool instead of alternatives. The Pro+ plan requirement is an eligibility gate, not a usage condition, and the description does not mention the relevant alternative or exclusion criteria.

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?

Beyond the readOnlyHint and destructiveHint annotations, the description adds important behavioral nuance: it reads from a cache rather than live API, so result freshness is qualified. It also discloses plan requirements and the key fields returned. This meaningfully informs an agent about behavioral consequences beyond the annotations alone.

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 compact and front-loaded: plan requirement, core action, filters, return fields, and caching caveat appear in two tight sentences. Every sentence adds useful information and none of it repeats the 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?

The tool is simple with three optional boolean parameters and no output schema. The description covers plan requirements, data source, filters, and representative return fields. Some additional detail about the full return shape or pagination would improve completeness, but the description is largely sufficient for an agent to invoke this tool 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 each parameter is already documented by the schema. The description's mention of 'governance flags (monitor, notification rules)' reinforces that the parameters are filters, but it does not add detail beyond what the input schema already provides. 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 uses a specific verb ('List'), identifies the resource ('Power Automate flows from the Power Clarity cache'), and notes the caching behavior, which distinguishes it from live-flow tools such as list_live_flows. It also states optional filtering by governance flags. This is specific and differentiates the tool from its 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 description clearly states the Pro+ plan requirement and the key usage context: data comes from a stored snapshot, not the live Power Automate API. This strongly implies when the tool should be used over a live alternative, though it does not explicitly name an alternative such as list_live_flows or state when to prefer one.

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 read-only and non-destructive behavior, so the description adds value by disclosing the Pro+ plan requirement and the cache-based source, which implies the data may reflect cached state. It does not repeat the annotation flags, avoiding redundancy.

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 a single sentence that front-loads the plan requirement, then gives the resource, action, and context. Every word adds meaning; there is no filler or repetition.

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 list operation, the description gives sufficient context: the resource, scope, source, and access requirement. No output schema is provided, but the phrase 'List all makers' inherently conveys the return value as a collection of makers.

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 and schema coverage is complete, so there is no missing parameter documentation. The description still adds slight semantic value by clarifying what entity a 'maker' is (citizen developers / AAD users), but no parameter-specific meaning is needed.

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

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

The description states a specific verb ('List'), a clear resource ('makers'), and scope ('all'), while clarifying that makers are citizen developers/AAD users. It also identifies the data source (Power Clarity cache), making the tool easily distinguishable from siblings like get_store_maker.

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 description conveys the invocation context via 'Requires Pro+ plan' and the collection-scoped word 'all', but it does not explicitly contrast this with get_store_maker for single-maker retrieval or any other sibling. Usage is implied rather than stated.

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 required Pro+ plan is an important licensing precondition disclosed beyond annotations. The phrase "from the Power Clarity cache" also adds behavioral context, indicating the data is sourced from a cache rather than live or direct sources. The readOnlyHint and destructiveHint annotations already cover safety, so the bar is lower and the description adds meaningful value.

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 a single, efficiently structured sentence that front-loads the licensing requirement before stating the exact function. Every part is relevant and there is no filler or redundant repetition of the tool name.

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 list-all operation, the description provides enough guidance: the scope (Power Apps canvas apps), the source (Power Clarity cache), and the access requirement. No output schema exists, but the operation is simple enough that an agent can safely invoke it without further explanation.

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 input schema has zero parameters, so there is no parameter semantics to cover. The description does not need to document parameters, and the baseline of 4 applies since there is nothing to add 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?

The description uses a specific verb and resource: "List all Power Apps canvas apps from the Power Clarity cache." This clearly identifies what the tool does and distinguishes it from related siblings like list_canvas_apps by naming the cache source.

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 usage context is implied: this tool is for retrieving all canvas apps from the Power Clarity cache, and it requires a Pro+ plan. However, it does not explicitly explain when to choose this tool over alternatives such as list_canvas_apps or get_canvas_app.

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 convey read-only/destructive intent, and the description adds meaningful behavioral context beyond them: the tool remains available after quota, it handles evidence appending, and it warns against including secrets. It does not fully describe side effects such as ticket creation or what happens when diagnostics are included, which keeps 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?

The description is three short, front-loaded sentences: purpose, key availability fact, then security guidance. Every sentence earns its place, and the most important information comes first.

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 tool with no output schema and low schema coverage, the description leaves too much implicit. It does not explain what each action returns, which parameters apply to report versus append versus status/list, or how chunked evidence should be assembled. An agent would need to infer a good deal of invocation behavior from names and enums.

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%, so the description must compensate for the many undocumented parameters. It does not explain the meaning of action values, ticket, category, severity, chunking, or the various contextual fields. The enums and defaults provide some structure, but the tool description adds essentially no parameter-level semantics.

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 ('Report a Flow Studio MCP bug or missing capability') and explicitly covers the three modes: new report, append text evidence, and status/list. No sibling tool is about bug reporting, so it is cleanly distinguished from the surrounding operation-focused tools.

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 provides clear usage context: use this tool for bug reports or missing capabilities, append evidence, and check prior reports. The note about being free even after quota is reached gives a useful when-to-use signal. It does not explicitly state when not to use it or name alternatives, but the sibling tools are unrelated and the context is clear.

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 description discloses several important behaviors beyond the annotations: inputs with unknown parents return status 'needs', match is case-insensitive and never fuzzy, matchCount 0 yields status 'nomatch', long lists are marked truncated, and addressing inputs inside objects by key is explained. Annotations only convey read-only/non-destructive intent, while the description adds the operational nuances an agent needs.

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 every sentence earns its place: it front-loads the core purpose and scope, then packs parameter behavior, examples, and edge cases into compact statements. Despite the length, there is no filler or repetition of the schema, so it remains scannable and 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?

Given 16 parameters, nested objects, and no output schema, the description covers the key behaviors the agent must understand: match semantics, statuses like 'needs' and 'nomatch', truncation, connection selection, and the outputs include option. It even addresses the dynamicMetadata exception. The description is complete enough for a complex live-resolution 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%, yet the description still adds meaningful semantics: match examples, browse structure, folder /path behavior, the difference between search and a pick, and dynamicMetadata's special use case. It also clarifies aliases like apiName for connectorName and the flowName/actionName shortcut. The description significantly enriches the schema definitions.

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

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

The description states a specific verb ('Resolve') and resource ('a connector operation's live input values') and enumerates concrete input kinds: dropdown options, list and table columns, folder and file pickers. It also clarifies the two modes: every input in one call or a single input via parameterName. This clearly distinguishes it from sibling tools like describe_live_connector or 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?

The description provides clear context on when to use the tool: pass existing values in parameters, use match to convert display names to values, and omit connectionName to let one be chosen. It explicitly states dynamicMetadata is not needed for the operation's own inputs and only needed for lookups the connector does not define. It doesn't name alternative sibling tools, but the usage context is still well-defined.

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 convey that this is a non-read-only, non-idempotent action. The description adds meaningful behavior beyond that: it automatically discovers the trigger name from the flow definition, which explains why the trigger name is not a parameter. It does not mention potential side effects like creating a new run instance, but the annotations plus the 'resubmit' verb cover the core safety profile.

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 no redundant wording. The main purpose and key behavioral detail are front-loaded, and the note about trigger name discovery is concise and useful.

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

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

For a simple three-parameter action with clear annotations and full schema coverage, the description provides enough context to invoke the tool correctly. It does not describe the return value or outcome, but given the straightforward 'resubmit' semantics and lack of output schema, this is a minor 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 description coverage is 100%, so the three parameters are already well documented. The description adds extra value by explaining that no trigger name parameter is needed and why (automatic discovery), which is semantic context not available 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 description uses a specific verb ('Resubmit') with a clear resource ('failed or cancelled Power Automate flow run') and method ('via the live PA API'). It also states a distinguishing behavior ('re-using the original trigger payload') that separates it from sibling tools like trigger_live_flow or 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?

The description gives clear usage context: it is for failed or cancelled runs and reuses the original payload, implicitly telling agents when this tool is appropriate. It does not explicitly name alternatives or state when not to use it, but the conditions are evident enough to guide selection.

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 provide idempotentHint and destructiveHint, but the description adds valuable context by explaining how idempotency is achieved (reads current state first, only calls Power Automate if a change is needed). This goes beyond the hints and is consistent with them. No contradictions.

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 concise sentences: one gives the purpose, the second explains a key behavioral trait. No redundant words, front-loaded, and easily scannable.

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

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

For a simple state-toggle tool with fully documented parameters and idempotency annotations, this description is complete enough. It doesn't describe return values, but no output schema exists and that is not necessary here. The only minor gap is lack of explicit alternatives or preconditions, but the tool is simple.

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 each parameter already has a clear description in the schema. The tool description adds no meaning beyond that baseline, so a 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 states a specific verb and resource (start/stop a flow) and is clearly distinct from siblings like trigger_live_flow, which runs a flow, and update_live_flow, which modifies flow settings. No ambiguity about what the tool does.

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 purpose implies when to use it (when you want to start or stop a flow), but it never explicitly contrasts with sibling tools or states cases where it should not be used. The read-before-write note is more behavioral than usage guidance, so coverage is adequate but not rich.

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 state readOnlyHint=true, so the description need not restate that. But it adds the non-billable trait synchronously, which is extra context. It does not describe return format details, but the schema coverage is highley explanatory.

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 concise, with no filler. It front-loads the purpose before query forms. Every sentence adds value, making it efficient and scannable.

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?

Given that this is a search tool with a simple input schema and no output schema, the description covers all necessary aspects: how to query, what to expect, and scope. No critical information is missing for correct use.

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 parameter is fully described in the schema. The description adds extra meaning about query forms and behaviors (e.g., max_results ignored for select and skill) that go beyond the schema, enhancing semantics.

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 clearly states the tool's purpose: finding the right tool rather than guessing its name. It specifies the action (search), the resource (tools), and the output (full JSON schemas), which distinguishes it from siblings like list_skills.

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 description provides explicit query forms with examples ('skill:<name>', 'select:name1,name2', free text) and conditions for use. It also mentions that 'skill:' queries should be used with list_skills for names, giving clear guidance on when to use this tool versus 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 mark this as a non-read-only, non-idempotent action with open-world effects. The description adds useful behavioral detail: it triggers execution, refuses body for scheduled flows, and notes the trigger-type limitation. No contradiction with annotations. Slight gap: it doesn't mention what happens if the flow run fails, but that's minor.

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 sentences, all purposeful, with the core purpose front-loaded and the trigger-type constraint stated early. No redundancy; each sentence adds 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?

Given no output schema, the description covers the tool's action, constraints, and parameter nuances adequately. It could have mentioned what the tool returns (e.g., a run ID), but that's not required without an output schema. The description is sufficiently complete for an agent 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 coverage is 100%, so baseline is 3. The description adds value by explaining that body carries trigger inputs and is refused for scheduled flows, and clarifies connections are for flows whose connections are provided by the runner. This goes beyond the schema's field descriptions.

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 ('Run a flow on demand') and resource (a live flow), and references the maker portal's 'Run flow' button as an analogy. It distinguishes itself from sibling tools like cancel/resubmit by focusing on triggering execution, and clarifies which trigger types it applies to.

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 says it works with Request triggers and scheduled recurrence flows, and that automated connector triggers only fire from their source event—so agents know when not to use it. It also warns that passing body to a scheduled flow is refused, preventing a common misuse.

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 mark this as destructive and idempotent, but the description adds substantial behavioral context: Power Automate's rejection of PATCH with no flow content, the forced re-save of unchanged definition for rename, the #flowstudio-mcp suffix on description, the requirement to re-read after adding a connectionReferenceLogicalName, and the merging behavior of connectionReferences. No contradictions with 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?

The description is long but well-organized with visual emphasis (SURGICAL EDIT, WHOLE definition, RENAME) that front-loads key decisions. Every section carries essential information for a complex tool, and there is negligible redundancy. It could be condensed slightly, but the density is justified by the many modes and edge cases.

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 tool with high complexity, no output schema, and many nuanced behaviors, the description covers all critical aspects: the create/update distinction, dryRun behavior, the two update paths, rename handling, connection reference quirks, and the description suffix requirement. The only minor gap is a lack of explicit return-value description, but the schema's dryRun description already covers that, and the tool's purpose implies the return.

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?

Despite 100% schema coverage, the description significantly enhances parameter understanding: it clarifies that definition must be a parsed object (not stringified), details the path array semantics for literal '/' and how to address SharePoint/Dataverse columns, explains the meaning of each operation (set/add/remove/merge), and describes the exact structure required for connectionReferences. It adds far more than the schema provides.

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 opens with 'Update or create a flow', using a specific verb and resource, and immediately distinguishes the two modes based on flowName presence. It further differentiates from siblings (e.g., update_store_flow) by explicitly focusing on live flows, and explains the surgical-edit vs whole-definition approaches, making the tool's purpose unmistakable.

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 description provides explicit when-to-use guidance: dryRun for previewing, get_live_flow for whole definition edits, displayName alone for rename, and clearly states 'Provide EITHER operations OR definition' and that operations requires flowName. It also implicitly excludes use for store flows by naming live-flow siblings. Highly actionable.

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 signal readOnlyHint=false and idempotentHint=true. The description adds valuable behavioral detail beyond annotations: 'Only fields provided are updated (merge semantics)', 'Writes to the cache', and 'does not call the Power Automate API' — all important for predicting side effects. It doesn't cover error/response behavior, but that's a minor gap given the rich context provided.

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 tightly scoped sentences front-load the plan requirement and key behavior. Every sentence earns its place: what it updates, the merge semantics, and the cache/API distinction. No filler or 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?

Despite strong behavioral context, the tool has 18 parameters with only 33% schema coverage and no output schema. The description does not fully specify expected formats or meanings for several undocumented governance fields, nor does it state return behavior. For a high-complexity metadata update tool, this leaves notable gaps an agent would need filled.

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 33%, so the description must compensate for the 12 undocumented parameters. It only names a subset ('description, business impact, owner team, tags, monitor flag, notification settings, etc.') and leaves ambiguous fields like 'tier', 'security', 'critical', and 'businessValue' unexplained. The merge-semantics note helps operationally but doesn't clarify individual parameter 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?

The description clearly states the verb and resource: 'Update governance/metadata fields on a flow record in the Power Clarity store' and gives concrete field examples. It inherently distinguishes this from sibling tools like update_live_flow by anchoring on the store and explicitly noting it 'does not call the Power Automate 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 description gives clear context for when to use this tool: updating stored governance/metadata fields, with the plan requirement and the cache-only behavior. It does not explicitly name alternatives or exclusion cases, but the store vs. live distinction is strong enough to guide selection.

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