Power Automate MCP Server by Flow Studio

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

Annotations already indicate idempotentHint=true and destructiveHint=false, so the description adds context about the specific API used and error handling (no migration if already in solution). It does not elaborate on success response or permission requirements, but given annotation coverage, the description provides moderate added 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 two sentences, front-loaded with the primary action and API, then covers the condition and optional parameter. Every sentence is informative with no redundancy or 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?

While the description covers prerequisites and error case, it does not mention what a successful migration returns (no output schema exists). The tool modifies state, so success outcome and resulting flow ID would be helpful. Without that, completeness is adequate but slightly lacking.

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 already describes all three parameters with 100% coverage. The description adds nuance for solutionId (optional, defaults to default solution). For flowName and environmentName, no additional semantics beyond the schema are provided.

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 exactly what the tool does: migrate a non-solution flow into a solution via the admin migrateFlows API. It distinguishes itself from sibling tools (none of which are migration-focused) and provides the specific condition that the flow must not already be in a solution.

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 indicates when to use the tool (for non-solution flows) and what happens if already in solution (error). It also explains the optional solutionId parameter and its default behavior. However, it does not discuss prerequisites like permissions or compare to other migration approaches.

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 adds context beyond annotations: it is a cancellation action that requires a preceding get step and only applies to Running runs. Annotations already mark it as destructive and idempotent, so the description provides useful behavioral constraints without 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?

Two sentences, front-loaded with the core action, then usage guidance. No redundant words; 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?

For a straightforward cancellation tool, the description covers the essential context: action, prerequisite, precondition. It does not elaborate on error handling or asynchronous behavior, but given the simplicity and presence of annotations, it is sufficiently 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?

Schema coverage is 100% with descriptions for all three parameters. The description adds meaningful context for runName by explaining it comes from get_live_flow_runs, which aids correct invocation. This goes beyond what the schema alone 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 clearly states the action: cancel a currently running Power Automate flow run. It specifies the API ('live PA API') and references a prerequisite tool (get_live_flow_runs). The precondition ('Only runs with status Running can be cancelled') further clarifies scope. This distinguishes it effectively from sibling tools, especially read-oriented ones and other action 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?

Explicitly states when to use: after get_live_flow_runs to obtain the run name. It also specifies the condition for success (run must be Running). However, it does not explicitly compare with similar sibling tools like resubmit_live_flow_run or set_live_flow_state, so the guidance is clear but not exhaustive.

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=true, and the description describes read-only behaviors (describing, returning metadata, hints). It adds behavioral context beyond annotations, such as the behavior of search across connectors and the variant parameter, without 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?

The description is front-loaded with the main purpose and then elaborates on modes and parameters. Every sentence is informative, though slightly lengthy. It is well-structured but could be slightly more concise.

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 complexity (9 parameters, multiple modes, no output schema), the description is comprehensive. It covers all modes, parameter interactions, and hints for related tools. It does not detail return value structure but provides sufficient context for an AI agent.

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 baseline is 3. The description adds significant meaning by explaining parameter interactions (e.g., search with/without connectorName, mode purposes, variant behavior), providing value beyond 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?

The description clearly states the tool describes a live Power Platform connector/API and its operations, with specific verbs and resource identification. It distinguishes from siblings by aligning with Canvas MCP describe_api and detailing distinct modes (summary vs full, operationId, search).

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 instructs when to use each mode: summary for compact catalog, operationId for one operation, search without connectorName for cross-connector search, and full for raw metadata. It provides clear context but does not explicitly state when not to use the tool or list 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 indicate readOnlyHint=true (safe read). The description adds context about resolving dynamic options, non-destructive nature, and specific metadata types, exceeding annotation info without 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?

Three well-structured sentences, front-loaded with verb and purpose. Every sentence adds value without 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?

Given a read-only dynamic options resolver with fully described parameters in schema and no output schema, the description is complete. It covers purpose, trigger condition, and examples, sufficient for an AI agent to invoke 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 parameters are well-documented in schema. The description adds examples (Teams, SharePoint) but does not significantly enhance parameter meaning beyond what schema 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 clearly states it resolves dynamic dropdown/list options for a connector operation parameter, using specific metadata types. It distinguishes from siblings by specifying it is for dynamic list/values resolution, not general connector operations.

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 states when to use: when describe_live_connector returns nextTool=get_live_dynamic_options. Provides context with examples (Teams, SharePoint) but lacks explicit when-not-to-use or alternative 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 indicate readOnlyHint=true, so no contradiction. The description adds that it works with specific metadata types (x-ms-dynamic-properties, x-ms-dynamic-schema) but does not disclose any other behavioral traits beyond the obvious read operation. No additional context about side effects, auth needs, or rate limits is necessary for a read-only tool, but the description could be slightly more informative about the output nature.

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 two sentences long, front-loading the core purpose and then providing usage context. Every sentence earns its place with no wasted words.

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 has 12 parameters and no output schema. The description explains the purpose and usage context well but does not describe the return format or behavior (e.g., what the resolved properties look like, pagination, errors). Given the complexity and lack of output schema, the description should at least hint at the output structure to be fully 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?

Input schema has 100% description coverage, so baseline is 3. The description adds value beyond schema by explaining the usage context for parameters like propertyName ('useful for a progressive follow-up with includeRaw=true') and gives practical examples (SharePoint). This enhances understanding of how parameters interact.

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 'Resolve' and the resource 'live dynamic schema/properties for a connector operation parameter'. It distinguishes from siblings by specifying the condition when to use (when describe_live_connector returns dynamicProperties with nextTool=get_live_dynamic_properties) and gives a concrete example (SharePoint item fields).

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 states the trigger condition: 'Use this when describe_live_connector returns a dynamicProperties entry with nextTool=get_live_dynamic_properties.' This is clear and context-specific. However, it does not mention when not to use or provide explicit alternatives, though the sibling list implies alternatives exist.

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 readOnlyHint=true, so the description's behavioral disclosure is minimal. The description adds that it 'Returns the raw properties object exactly as the PA API returns it,' which is useful but doesn't elaborate on error handling, rate limits, or authorization requirements. No contradiction with annotations. Adequate but not exceptional.

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 two sentences: the first efficiently states what it does, and the second provides the usage purpose. No fluff, front-loaded with key action, and every sentence earns its place. Perfect conciseness.

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 mentions return type as 'raw properties object,' which is somewhat vague but sufficient for a read-only tool. It doesn't cover error cases or pagination, but context from siblings and annotations fills some gaps. For a simple fetch operation, it is complete enough to be useful.

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 descriptions for both parameters. The description does not add any additional semantics or constraints beyond what the schema already provides. Baseline 3 is appropriate as the description adds no extra parameter value.

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 'Fetch' and the resource 'full native Power Automate flow JSON', including specifics like triggers, actions, parameters, outputs. It also distinguishes itself from siblings by explicitly mentioning its use before update_live_flow, which differentiates it from other get tools like get_live_flow_http_schema or 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 context for when to use the tool: 'Use this to inspect the full definition before calling update_live_flow with a modified definition.' This implies a specific usage scenario. While it doesn't explicitly state when not to use it, the sibling list and the use case make it clear that this tool is for fetching full definitions, not for other get operations. Minor lack of explicit exclusions 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?

Builds on readOnlyHint annotation by stating no test call is made to the trigger URL, and information is read via the PA API. Also includes deprecation status, which is important behavioral context.

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?

Description is informative with each sentence adding value, starting with deprecation warning. Could be slightly more concise but efficient overall.

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?

Comprehensive for a simple read tool with 2 parameters. Explains what is returned (JSON schema, headers, method, response schemas) and deprecation status. No output schema needed as description covers it.

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 descriptions for both parameters. The description does not add additional meaning beyond what the schema provides, so 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?

Description clearly states the tool inspects the HTTP interface of a Power Automate Request-triggered flow, returning specific details like JSON schema, headers, method, and response schemas. It distinguishes itself from siblings like trigger_live_flow and get_live_flow_trigger_url.

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 advises to use this before trigger_live_flow to understand the body to send. Provides context on what it does but does not explicitly exclude other scenarios or mention when not to use.

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=true, which is consistent. The description adds behavioral details beyond annotations: it explains the use of SAS blob links, the PA repetitions endpoint, and the structure of repetition records (repetitionIndexes, status, error, inputs/outputs blobs). It also clarifies how iterationIndex matched against innermost itemIndex. 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?

The description is well-structured with clear separation of behaviors. It is front-loaded with the main purpose and then details parameter effects. While it is somewhat lengthy, every sentence adds value and no information is redundant. It could be slightly more concise, but overall it is effective.

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 explains the return format for repetitions, including repetitionIndexes, status, error, and blobs. It also explains pagination with top. However, the description is less detailed about the non-repetition case (top-level actions), only mentioning it returns top-level actions optionally filtered. It would benefit from describing the structure of top-level action outputs, but overall it is fairly complete for a complex 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%, baseline 3. The description adds significant meaning: it explains that actionName filters the top-level list when omitted, and triggers repetition fetching when provided. It details that iterationIndex pins to a single iteration by matching innermost itemIndex. It also describes the content of repetition records, which is not in the schema. This goes beyond simple parameter 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?

The description clearly states the tool downloads inputs and outputs for actions in a flow run via SAS blob links. It distinguishes two modes: without actionName returns top-level actions (optionally filtered by name), with actionName returns all repetitions across foreach iterations. This is specific and differentiates from sibling tools like get_live_flow_run_error or 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 explicit guidance on when to use actionName vs not, and how iterationIndex works. It explains that omitting actionName gives top-level actions, while providing actionName with optional iterationIndex returns specific repetitions. However, it does not explicitly contrast with other tools for similar purposes, but the context is clear enough for an AI 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?

Annotations already declare readOnlyHint=true. Description adds that it lists every failed action with error code and message, which is additional behavioral detail beyond read-only nature.

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: first defines purpose, second details output. Highly concise and front-loaded with critical 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?

Covers purpose, output, and scope. Does not mention pagination or top parameter explicitly, but the schema handles that. Adequate for a simple fetch tool without output 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%, baseline 3. Description adds meaning by explaining the output (error details per action) and connecting parameters to the specific run, slightly compensating for lack of param-specific elaboration.

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 explicitly states 'Fetch error details for a specific flow run' and specifies it lists every failed action with error code and message. Distinguishes from sibling tools like get_live_flow_run_action_outputs and get_store_flow_errors.

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?

Implied usage for diagnosing errors on a specific run, but no explicit when-not-to-use or alternative tools mentioned. Context is clear from the purpose.

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 readOnlyHint=true. The description adds significant context: it fetches via API using impersonation, which implies authentication requirements, and specifies it returns specific fields. 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 concise with two short sentences that efficiently convey purpose, source distinction, and return fields. Every sentence adds value.

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 lists returned fields (run name, status, startTime, endTime, trigger name/code, error). It covers the live vs cached distinction and mentions impersonation. Sufficient for an agent to understand the tool's behavior and output.

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 descriptions for all parameters. The description does not add new information beyond what is in the schema, so 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 clearly states the verb 'Fetch' and the resource 'live run history for a flow'. It distinguishes itself from the cached store (sibling get_store_flow_runs) by specifying 'directly from the Power Automate API using impersonation — not the cached 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?

The description provides clear context by contrasting with the cached store, implying when to use this tool (live data) vs alternatives (cached data). It does not explicitly state when not to use it or list alternative tool names, but the context is sufficient.

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; description adds deprecation status, endpoint information, and return behavior for non-HTTP triggers. Consistent and adds value beyond 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 deprecation warning upfront, purpose clearly stated, and return details included. No wasted words.

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?

Covers deprecation, return values, and behavior for non-HTTP triggers. Lacks error handling or authorization notes, but given simplicity and existing annotations, it is mostly 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?

Schema coverage is 100% for both parameters (flowName, environmentName), and description does not elaborate on them beyond what the schema provides. Baseline score 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 it fetches the live trigger URL/method for HTTP-triggered flows, distinguishes from sibling get_flow_trigger_url by noting the different endpoint used. Provides clear verb+resource with specificity.

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 compares to get_flow_trigger_url, notes deprecation, and explains behavior for non-HTTP triggers. Lacks explicit when-not-to-use beyond deprecated status, but 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?

Annotations provide `readOnlyHint: true`, which the description reinforces. It adds non-obvious behavioral traits: requires Pro+ plan, and data is from stored snapshot—not live. 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 sentences, front-loaded with requirement, no redundant information. Every word contributes value.

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 no output schema, the description enumerates returned fields (trigger URL, owners, state, run statistics, governance metadata). Combined with the 100% schema description coverage and readOnlyHint annotation, the description is fully informative for a read-only retrieval 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% with clear parameter descriptions. The tool description does not add additional parameter-specific meaning beyond the schema, but it provides helpful context about the cached nature. 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 states the tool retrieves full details for a single Power Automate flow, listing specific contents (trigger URL, owners, state, run statistics, governance metadata). It distinguishes from sibling tools like `get_store_flow_summary` 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?

The description explicitly notes data is from a cached snapshot, not live, guiding agents to use this for cached data and implying `get_live_flow` for live updates. However, it does not explicitly state when not to use or name direct alternatives beyond 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?

The description adds significant behavioral context beyond the annotations: data comes from a stored snapshot (not live), it returns 'failedActions' and 'remediation hint', and it is a wrapper with status=Failed. This aligns with the readOnlyHint annotation and provides transparency.

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 four sentences, front-loaded with critical info (plan requirement, deprecation, purpose), and no unnecessary words. Every sentence adds value.

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 simplicity (3 parameters, wrapper around another tool), the description is complete. It mentions output fields (failedActions, remediation hint) despite no output schema, and provides deprecation notice and alternative, making it fully self-contained.

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 baseline is 3. The description does not add new per-parameter meaning beyond what the schema already provides, but it does provide overall context about the parameters being used for the wrapper.

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 tool as a convenience wrapper that gets cached failed run history for a flow. It specifies the verb 'Get' and the resource 'failed run history', and distinguishes itself from the sibling tool 'get_live_flow_runs' by noting the alternative.

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 states the tool is deprecated and recommends using 'get_live_flow_runs' with a status filter instead. It also notes the Pro+ plan requirement and that it is a convenience wrapper, providing clear when-to-use and 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 provide readOnlyHint=true. Description adds behavioral context: requires Pro+ plan, uses cached data, and lists specific return fields. No contradictions. Explains that data is from stored snapshot, not live API, which is valuable.

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?

Description is three sentences, front-loaded with requirement and purpose. Every sentence adds value. No redundancy. Structure is clear 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 read-only tool with complete schema and annotations, description covers all essential aspects: purpose, data source, time defaults, returned fields, and plan requirement. No output schema but return fields are listed. Adequate for agent decision.

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 descriptions. Description adds context about defaults (startTime defaults to 7 days ago) and reiterates status filter behavior. Does not add new parameter meaning beyond schema, but reinforces key details. Baseline 3 due to full schema coverage.

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 uses specific verb 'Get' and resource 'cached run history for a flow', clearly distinguishing from sibling tool get_live_flow_runs which fetches live runs. It states the source (Power Clarity store) and that it returns cached data, not 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?

Description mentions requirement (Pro+ plan), default behavior (last 7 days), and notes the data source (cached snapshot not live). While not explicitly stating when not to use, the contrast with 'live' implies alternatives like get_live_flow_runs. No explicit 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 already indicate readOnlyHint=true. The description adds that data is from a stored snapshot, not live, informing the agent about potential staleness. 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 sentences, no wasted words. Efficiently conveys purpose, requirement, and data source.

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 lists the statistics returned (total runs, success count, etc.), so the agent knows what to expect. Could be more explicit about the structure, but adequate for a summary 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% with descriptions for all parameters. The description adds minimal extra meaning beyond schema, only hinting at a time window that maps to startTime/endTime. 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 states it gets aggregated run statistics for a flow from the Power Clarity cache, listing specific metrics like total runs, success count, etc. It distinguishes from siblings by noting data is from a stored snapshot, not live.

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 mentions the Pro+ plan requirement and contrasts with live API data, providing clear context. However, it does not explicitly state when to use this tool versus alternatives, though the distinction is implied.

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 indicate readOnlyHint=true, and the description adds that no live API call is made—it reads from cache. This provides behavioral insight beyond annotations. 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?

Very concise: two sentences with important flags (Pro+ plan, deprecation) at the start. No wasted words, and key information 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?

The description covers prerequisites, deprecation, behavior (cached vs live), and what is returned (trigger URL and type). No output schema is provided, but the description states what the tool returns, which is sufficient for this 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?

Schema coverage is 100%, so the description does not need to add parameter details. It implicitly references the two parameters (flowName, environmentName) through the tool name and context, but adds no extra semantic value 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?

Clearly states that the tool gets the trigger URL and trigger type for an HTTP-triggered flow from a cache. Distinguishes itself from the sibling tool 'get_live_flow_trigger_url' by noting it reads from cache rather than making a live API call.

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 mentions prerequisites (Pro+ plan), deprecation status, and provides a direct alternative ('get_live_flow_trigger_url') for a guaranteed-fresh URL. This helps the agent decide when to use 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 indicate readOnlyHint=true, and the description adds value by specifying that the tool returns 'flow/app counts' and 'whether the account has been deleted'. This provides behavioral context beyond the annotation. No contradictions present.

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, efficient sentence with no redundant words. It conveys the essential information (requirement, action, resource, key format, and return contents) in a compact manner. Perfectly front-loaded with the requirement.

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 one parameter and no output schema, the description adequately explains what the tool returns (flow/app counts and deletion status). It could mention that the result is a single object or provide more detail about the response structure, but it is sufficiently complete for a simple retrieval 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%, and the schema parameter description is already informative ('Maker RowKey (AAD object ID of the user)'). The tool description does not add new information about the parameter beyond restating the key format, so it meets the baseline but does not exceed it.

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 'Get details for a single maker' with a specific resource ('from the Power Clarity cache') and identifies the key format (AAD object ID). It distinguishes itself from sibling tools like 'list_store_makers' (which lists multiple makers) and other 'get_store_*' tools that target 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?

The description includes a prerequisite ('Requires Pro+ plan'), which aids usage decisions. However, it does not explicitly state when to use this tool versus alternatives like searching for a maker. The context is clear enough for an agent to infer usage when a specific maker key is known.

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 annotation, the description discloses the specific fields returned and the behavior when 'search' is used (adding connectionReferenceTemplate and hostTemplate). It does not mention authorization or rate limits, but the read-only nature is clear and the extra detail about output format adds transparency.

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 paragraph that front-loads the main purpose, then lists fields and parameter details. While it is somewhat long, every sentence provides distinct value and the information is well-organized. It could be slightly more concise, but it remains focused.

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 read-only annotation and 3 optional parameters, the description covers the tool's complete behavior: what it returns (field list), parameter effects (top, search, environmentName), and how the output integrates with another tool (update_live_flow). It also distinguishes from cached store tools, making the context complete for an agent.

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 significant value by explaining the 'search' parameter's purpose (narrow list and return templates), 'top' parameter (max connections, auto-pagination), and 'environmentName' (cross-environment when omitted). This enriches the agent's understanding beyond the schema 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?

The description clearly states 'List Power Platform connections in an environment directly from the Power Automate API — not the cached store', specifying the verb (list), resource (connections), and distinguishing it from the cached store sibling tool. It also lists the returned fields, leaving 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 description provides guidance by contrasting 'directly from the Power Automate API — not the cached store', implying real-time vs cached data. It also explains that using the 'search' parameter returns templates that can be directly used in 'update_live_flow', giving concrete usage context. However, it does not explicitly state when not to use this tool or compare to specific siblings like list_store_connections.

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?

Discloses return fields, pagination behavior via 'top' parameter, and that results are limited to environments visible to the impersonated service account, adding context beyond readOnlyHint 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?

Two sentences, front-loaded with purpose, no redundant words.

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 list tool with one optional param and no output schema, description covers source, return fields, auth context, and pagination completely.

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 covers parameter fully (100% coverage). Description adds mention of return fields but no new parameter details beyond 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?

Clear verb+resource ('List all Power Platform environments') with key distinction from cached store, differentiating it from sibling 'list_store_environments'.

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 states it's from the API (live) not cached, implying use case for fresh data. Doesn't explicitly mention when NOT to use, but sibling tool provides alternative 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?

The description adds detail beyond the readOnlyHint annotation: it discloses that owner mode returns full definitions, admin mode returns all flows, pagination is time-bounded, and search is case-insensitive. 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?

The description is concise and well-structured. It front-loads the main purpose, then covers modes, search, and pagination in a logical order. No unnecessary words.

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 lists returned fields and explains pagination. It covers all 6 parameters. However, it could be more explicit about the response structure (e.g., that nextLink is a top-level field) or the exact format of values. Still, it provides enough for an agent to use the tool effectively.

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 adds context: owner mode returns 'full definition', admin mode 'all flows', top is maximum, timeoutSeconds stops collection, continuationUrl must match mode, search is case-insensitive. This enhances understanding beyond the schema 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?

The description clearly states 'List Power Automate flows in an environment' with specific returned fields (id, displayName, state, triggerType, lastModifiedTime). It distinguishes between owner and admin modes, providing a clear purpose and scope. This differentiates it from sibling tools like get_live_flow which retrieves a single 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 explains when to use owner vs admin mode and that admin requires an admin account. It describes pagination behavior with time-bounded collection and continuationUrl. However, it does not explicitly tell when to avoid this tool in favor of alternatives like get_live_flow for a single flow detail.

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 read-only. The description adds that the tool is non-billable and explains the returned data. 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 sentences, front-loaded with the primary action, then additional context. No wasted words.

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 list tool with no parameters, the description fully covers the purpose, usage, return information, and next steps. No output schema needed as return is described.

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 0 parameters and 100% schema coverage, the description does not need to add parameter details. It adds value by describing the return content (description and member tool names).

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 it lists all skill bundles, including their descriptions and member tool names. It distinguishes itself from siblings by providing a specific use case and workflow step.

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 instructs to call this tool first when unsure about applicable tools, then to call tool_search with a skill-specific query. This provides clear when-to-use and next-step 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 readOnlyHint=true, so the description adds minimal behavioral context (the cache source). It does not contradict annotations, but provides no additional safety or side-effect details.

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, front-loaded sentence that conveys essential info (prerequisite and action) without any filler. Every word 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?

For a simple tool with no parameters and no output schema, the description is fairly complete, but it lacks details about return format or pagination, though these are not critical given the annotations and 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?

With zero parameters, the description is not required to add parameter meaning. The schema coverage is 100%, so the baseline is 4; the description does not need to compensate.

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 lists all Power Platform connections from a specific cache, but it does not explicitly differentiate from the sibling tool 'list_live_connections', which may cause confusion.

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 mentions a prerequisite (Pro+ plan) but provides no guidance on when to use this tool versus alternatives like 'list_live_connections', leaving the agent without context for tool 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 indicate read-only behavior. The description adds the caching source and plan requirement, which are useful but lacks details on data freshness or potential limitations.

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, front-loaded with the requirement, and contains no unnecessary words. Every part 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?

While the description covers the source and requirement, it lacks details about the output format or structure. Given no output schema, the description could be more helpful by hinting at what fields are returned.

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 no parameters and schema coverage is 100%, so the description correctly adds no further parameter information. Baseline for zero parameters is 4.

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 lists all Power Platform environments from a cache. It uses a specific verb and resource, and the mention of 'Power Clarity cache' helps distinguish from sibling 'list_live_environments'.

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 includes a prerequisite (Pro+ plan) but does not explicitly state when to use this tool versus alternatives like list_live_environments. Usage context is implied but not detailed.

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. Description adds key behavioral traits: data from cache, not live API, and mentions return fields. 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 sentences, no wasted words. Front-loaded with requirement and purpose. Efficient and clear.

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-param optional filter tool with no output schema, it mentions key return fields and data freshness (snapshot). Covers all essential aspects without extra fluff.

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 description groups parameters under 'governance flags'—adding context beyond the schema's individual descriptions. This helps agents understand they are filters.

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 it lists Power Automate flows from a cache, with optional filtering by governance flags. It distinguishes from sibling tools like list_live_flows (live API) by specifying the data 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?

Includes requirement (Pro+ plan) and context (stored snapshot, not live). Implicitly guides agents to use this for cached data, but does not explicitly mention alternatives like list_live_flows for live data.

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 annotation readOnlyHint=true already indicates it's read-only. The description adds context about the data source ('Power Clarity cache'), implying it may not be real-time, which is valuable beyond the 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?

The description is a single concise sentence that front-loads the requirement and clearly states the purpose. No unnecessary words.

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, the description is adequate. It explains what is listed and from where. It does not mention the return format, but zero output schema makes this acceptable.

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 zero parameters and 100% schema description coverage, the description doesn't need to add parameter details. The baseline score of 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 clearly states the verb 'List' and the resource 'makers', with specific context 'from the Power Clarity cache'. It distinguishes from the sibling 'get_store_maker' which likely retrieves a single 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 mentions a prerequisite '[Requires Pro+ plan]', which is useful guidance. It implies when to use this tool (to list all makers) vs alternatives like 'get_store_maker' for a specific maker, but does not explicitly state when not to use it.

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 readOnlyHint=true. The description adds that data comes from a cache, implying it may not reflect live state. Also notes the Pro+ plan requirement, which is useful beyond 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?

Single sentence with no wasted words. The prerequisite is placed at the beginning, making it immediately visible.

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 with no output schema, the description covers the key aspects: requirement, resource type, and data source. Lacks details on response format or pagination, but acceptable given simplicity.

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?

No parameters in schema; baseline is 4. Description does not need to add parameter info since there are none.

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 tool lists Power Apps canvas apps from the Power Clarity cache, using specific verb and resource. Siblings like list_store_flows, list_store_connections show clear differentiation.

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?

Mentions the Pro+ plan requirement upfront, providing essential context for when the tool can be used. Does not explicitly state when not to use, but the requirement implies a restriction.

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 indicate non-read-only, non-idempotent, non-destructive. The description adds value by revealing the automatic trigger discovery behavior, which is not captured in annotations. 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?

Two sentences only, front-loaded with the core purpose. Each sentence provides essential information without redundancy. The description is well-structured 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 the tool has 3 simple parameters, no output schema, and clear annotations, the description covers purpose, usage, and behavioral nuances adequately. It is complete for an agent to select and invoke 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% with clear parameter descriptions. The description adds context by stating that no trigger name is needed, which is not in the schema. This extra guidance enhances parameter understanding.

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 resubmits a failed or cancelled Power Automate flow run reusing the original trigger payload. It specifies the verb 'resubmit' and the resource 'flow run', and distinguishes from siblings like cancel_live_flow_run and trigger_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 states use cases: 'failed or cancelled' runs. It also notes that the trigger name is discovered automatically, avoiding user error. However, it does not provide explicit when-not-to-use or list alternative 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?

The description adds significant behavioral context beyond annotations: it explains the read-check-then-act pattern ('Reads the current flow state first and only issues the start/stop call if a state change is actually needed'), which aligns with the idempotentHint=true annotation. It also details the output format, providing transparency without 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?

The description is concise at three sentences, each with distinct value: action, scope, behavior, and output. It is front-loaded with the primary purpose, making it easy for an AI agent to parse quickly.

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 three required parameters and no output schema, the description covers purpose, usage context, behavioral details, and return values. It explains authentication context (impersonated account) and the state-change check, providing sufficient completeness for agent selection and invocation.

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 does not add parameter-specific semantics beyond the schema descriptions, but it does mention 'impersonated service account' as a general authentication context, which is not tied to a specific parameter. No significant additional value for parameter understanding.

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 core action: 'Start or stop a Power Automate flow via the live Power Automate API using an impersonated service account.' It specifies the verb (start/stop), resource (flow), and context (live API, impersonated account), effectively differentiating it from sibling read tools 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 provides useful context: 'Does not require a Power Clarity workspace — works for any flow the impersonated account can access.' This indicates when to use the tool, but it lacks explicit exclusions or alternatives. However, the mention of reading current state implies idempotent usage, which guides correct invocation.

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. The description adds important behavioral context: it uses impersonation via a cached service account, requires a Pro+ plan, and returns the updated stored record. 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 concise at three sentences, with the deprecation and plan requirement placed first. It efficiently conveys all necessary information without redundancy, though a minor improvement could be removing the phrase 'via the live Power Automate API' as it is implied.

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 mutability (destructive, modifies state), the description covers return value (updated record), authentication approach (impersonation), deprecation status, and the preferred alternative. No output schema is needed as the return is described. Everything an agent needs to invoke this tool correctly is provided.

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 descriptions for each parameter. The description does not add new semantic details beyond the schema; it only restates the tool's function. Baseline score of 3 is appropriate as the schema already documents the parameters adequately.

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 action ('Start or stop a Power Automate flow'), the resource (flow via live API persisted to Power Clarity store), and explicitly distinguishes from the sibling tool 'set_live_flow_state' by recommending its use instead. The verb 'set' combined with the state enum makes the purpose 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?

The description provides explicit guidance: the tool is deprecated and agents should 'Use set_live_flow_state instead'. It also notes preconditions (Pro+ plan, impersonation with specific service account roles), which helps the agent decide when not to use 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?

Beyond the readOnlyHint annotation, the description adds that the tool is non-billable, explains query forms (skill:, select:, free-text), and specifies output (full JSON schemas). 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?

The description is informative and front-loaded with the key preference statement. It uses a single paragraph but is well-organized. Minor improvement could be bullet points for query forms, but it remains concise for its 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?

Given the tool's complexity (two parameters, no output schema), the description covers all necessary context: when to use, query forms, output details, and non-billable nature. It is fully adequate 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?

The description elaborates on the query parameter with three explicit forms and notes that max_results is ignored for select: and skill: queries. This adds significant meaning beyond the schema's brief parameter descriptions, even though schema coverage is 100%.

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 searches Flow Studio MCP tools by keyword, skill bundle, or selector and returns full JSON schemas. The verb 'Searches' and resource 'Flow Studio MCP tools' are specific, and the opening line distinguishes it from guessing tool names among 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?

Explicit guidance: 'Call this whenever the user request maps to functionality you are not 100% sure about, OR when you want to load a whole skill bundle.' Also advises using list_skills first for bundles, providing clear when-to-use and when-not-to 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?

The description goes beyond annotations by detailing the internal steps (fetches signed URL via listCallbackUrl, POSTs body), automatic AAD authentication handling, and return fields (status, body, auth flags). This justifies the destructiveHint and provides comprehensive behavioral info.

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 paragraph of moderate length, front-loading the main purpose. It is efficient but could be slightly more structured for easier parsing.

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 moderate complexity (3 params, destructive action, no output schema), the description covers prerequisites (HTTP trigger), authentication, internal steps, and return values. An agent has sufficient information 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?

While schema coverage is 100%, the description adds value by explaining the body parameter's role and that it can be omitted for flows expecting empty body. This contextualizes the parameters beyond 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 clearly states the tool triggers an HTTP-triggered Power Automate flow by posting to its callback URL. It specifies the flow type restriction, distinguishing it from sibling tools like get_live_flow_trigger_url.

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 (to trigger flows) and its limitation to HTTP-triggered flows. However, it does not explicitly mention alternatives or when not to use it, so it misses a point for full 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?

The description contradicts the annotation idempotentHint: true because creating a new flow with a generated GUID each time is not idempotent. Per rules, description contradicting annotations leads to score 1.

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 (~150 words), well-structured with logical sections (create vs update, side effects, modification guidance). Every sentence adds value without 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 no output schema, the description covers all necessary aspects: create/update logic, required parameters, how to obtain and modify definition, side effects, and tracking. It provides enough context 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 baseline is 3. The description adds meaningful extra context, especially for definition (reusing description on update) and flowName (creation vs update) beyond the schema 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?

The description clearly states 'Update or create a Power Automate flow via the live PA API' and distinguishes from siblings by referencing the live API and related tool get_live_flow. It provides specific verb+resource scope.

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 explains when to create (flowName omitted/blank) vs update (flowName provided), and guides users on how to modify a definition by calling get_live_flow first. Mentions side effects (cache mirroring, tracking string). No ambiguity.

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 that writes go to cache only, not the Power Automate API, which is a key behavioral detail beyond annotations. No contradiction with annotations (idempotentHint=true aligns with merge semantics). It does not mention error handling or authorization details, but the plan requirement is stated.

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 cover purpose, example fields, merge behavior, and cache explanation. No unnecessary words. Efficient and 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?

Given the complexity (18 parameters, no output schema), the description provides essential context: plan requirement, merge semantics, cache write, and scope (metadata fields). Lacks details on each parameter but sufficient for an update tool. Could mention return value or error cases, but not required.

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 only 33% schema description coverage, the description adds some meaning by grouping parameters as governance/metadata fields and noting merge semantics. However, many parameters (tier, critical, security, etc.) are not explained beyond their names. The description partially compensates but not fully.

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 updates governance/metadata fields on a flow record in the Power Clarity store, listing example fields. It distinguishes from siblings like update_live_flow and set_store_flow_state by specifying the target (store flow) and the type of update (metadata vs state).

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 mentions the prerequisite (Pro+ plan) and semantics (merge, only provided fields updated). It implies usage for updating metadata, not state, but does not explicitly compare to alternatives like set_store_flow_state. Still clear enough.

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