Power Automate MCP Server by Flow Studio

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

The description adds meaningful behavior beyond the annotations: it discloses that an already-solution flow returns an error without attempting migration, and that omitting solutionId migrates to the default solution. This supplements the idempotentHint and destructiveHint annotations with concrete edge-case behavior, though it does not mention success return format or admin permission requirements.

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

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

Three short sentences: purpose/mechanism, error behavior, and optional parameter guidance. Every sentence carries distinct value and the most important intent 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?

For a relatively simple three-parameter write operation with rich schema descriptions and safety annotations, the description is nearly complete. It covers the core operation, the non-solution prerequisite, the already-solution error case, and default solution behavior. The only notable omission is what a successful response looks like, but the absence of an output schema makes this a minor gap rather than a critical one.

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

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

Schema description coverage is 100%, so the baseline is 3; the schema already documents flowName, solutionId, and environmentName well. The description reinforces that solutionId is optional and defaults to the default solution, but it largely repeats information already present in the input schema rather than adding substantial new meaning.

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

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

The description opens with a specific verb and object: 'Migrate a non-solution Power Automate flow into a solution via the admin migrateFlows API.' This clearly identifies the operation and distinguishes it from the read/list/update-focused sibling tools, especially set_live_flow_state and update_live_flow.

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

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

It provides clear context: use this for non-solution flows, and it explicitly states the failure behavior when the flow is already in a solution. It does not explicitly name an alternative check or when-not scenario, but the boundary is clear enough for an agent to decide when to invoke 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 destructiveHint=true and idempotentHint=true, so the mutation risk is known. The description adds value by disclosing the running-status requirement and the prerequisite call, which are not visible in the annotations or schema. It does not contradict any annotation.

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

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

Three short sentences, front-loaded with the operation, followed by the required sequence and constraint. Every sentence earns its place and there is no redundant wording.

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

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

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

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

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

Schema description coverage is 100%, and each parameter already has a clear description (e.g., runName is identified as the name field from get_live_flow_runs). The description reinforces the relationship to get_live_flow_runs but adds no new parameter-level semantics beyond the schema.

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

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

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

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

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

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

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false, destructiveHint=false, so the safe-read profile is covered. The description adds substantial behavior beyond that: the default mode behavior, what an operationId response includes (inputs, outputs, dynamic parameter metadata, nextTool hints, authored hint + canonical example), variant selection behavior when omitted, and cross-connector suggestion semantics.

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

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

The description is about 150 words and front-loads the core purpose in the first sentence. Every subsequent sentence adds new information—mode semantics, operationId expansion, variant hints, and the full-mode exclusion. There is no repetition of schema content and no filler.

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

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

For a 9-parameter tool with no output schema, the description is notably complete: it covers the two modes, the cross-connector search path, variant dispatch, and the downstream tool hints. Minor gaps remain: it does not explicitly describe the shape of the returned operation catalog/search results, nor the interaction between mode=full and operationId, but these are minor given the rich schema and known sibling context.

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

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

Schema description coverage is 100%, so the baseline is 3. However, the description enriches operationId beyond the schema—it not only says 'expanded inputs and outputs' but also mentions dynamic parameter metadata and the nextTool/hint integration. It also clarifies the search/connectorName relationship ('Use search without connectorName/apiName to search operations across connectors') beyond what's in the schema.

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

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

The description opens with a specific verb-resource pairing: 'Describe a live Power Platform connector/API and its operations.' It clearly differentiates the tool from siblings such as get_live_flow (flow-level details), get_live_dynamic_options (dynamic option resolution), and update_live_flow (flow editing). The reference to Canvas MCP describe_api also pins down the intent distinctly among the many sibling introspection 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?

The description gives explicit routing: use mode=summary by default for a compact catalog, use operationId to get one operation with expanded details, use search without connectorName/apiName to search across connectors, and a clear exclusion—'Use mode=full only when raw OpenAPI connector metadata is required.' It also names the next hop tool (get_live_dynamic_options) and mentions the output shape going into update_live_flow.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is established. The description adds useful behavioral context about what the tool does ('resolve ... options'), which metadata types it operates on, and provides concrete examples like Teams/SharePoint IDs. No contradiction with annotations.

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

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

Two sentences, front-loaded with the core purpose and then the exact invocation trigger. Every sentence earns its place, with no filler or repetition of schema details. The examples are useful but compact.

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 rich 100%-covered schema and safe annotation profile, the description is largely complete: it tells the agent what this tool is, when to invoke it, and what metadata shapes it applies to. It doesn't describe the return value shape or pagination behavior, but for a dropdown-options resolver that is a minor gap, not a blocking one.

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

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

Schema description coverage is 100%, so all 8 parameters are already documented in detail. The description refers conceptually to parameters and metadata but does not add meaning beyond the schema. The baseline of 3 applies because the schema carries the load 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 uses a specific verb ('Resolve') and a precise resource ('live dynamic dropdown/list options for a connector operation parameter'). It clearly differentiates itself from sibling tools by mentioning the exact trigger (nextTool=get_live_dynamic_options) and the relevant metadata types (x-ms-dynamic-list/x-ms-dynamic-values), which an agent can distinguish from get_live_dynamic_properties.

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

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

The description gives an explicit, actionable condition: 'Use this when describe_live_connector returns a dynamic parameter with nextTool=get_live_dynamic_options.' This is strong context for when to call it. However, it does not explicitly state when not to use it or name an alternative tool as the preferred choice.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the read-only safety profile needs no repetition. The description adds valuable behavior context beyond annotations: it resolves live metadata, works with specific metadata formats, and gives a concrete SharePoint example. It does not describe pagination or error behavior, but those are not critical for a read-only resolve operation.

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

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

Three tight sentences: define the action, state the exact trigger, then give metadata types and an example. No wasted words, the most important guidance is front-loaded, and every sentence contributes to successful invocation.

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 12-parameter tool with no output schema, the description plus fully described schema parameters leaves little ambiguity about what input is required and why. The main gap is that the return shape is not explicitly described, but the schema's includeRaw, propertyName, and contextParameterAlias parameters implicitly clarify the response behavior.

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

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

Schema description coverage is 100%, so the schema already explains each parameter well. The description adds meaningful workflow guidance beyond the schema by explaining the progressive propertyName/includeRaw=true follow-up pattern and by grounding the parameters object in a realistic SharePoint site/list/view example.

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

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

The description opens with a specific verb and resource ('Resolve live dynamic schema/properties for a connector operation parameter') and immediately ties it to a concrete trigger from describe_live_connector. It clearly separates this tool from the sibling get_live_dynamic_options by scoping it to dynamicProperties and x-ms-dynamic-properties/x-ms-dynamic-schema.

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

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

It states an explicit use condition: call this when describe_live_connector returns a dynamicProperties entry with nextTool=get_live_dynamic_properties. This is strong guidance for when to invoke the tool. It does not explicitly mention when not to use it or name alternatives like get_live_dynamic_options, but the trigger is sufficiently clear and directive.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the tool's safety profile is clear. The description adds value beyond annotations by stating it returns the raw properties object exactly as the PA API returns it and that it includes the complete definition, which helps the agent expect unfiltered, exact output.

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

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

The description is three sentence-fragments long, with no filler. It front-loads the core purpose, then states the return behavior, then gives usage guidance. Every sentence contributes useful, non-redundant information.

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

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

This is a simple read-only getter with two fully described parameters and no output schema. The description explains what the return value is, what it contains, and how it should be used in a larger workflow. Nothing essential is missing for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, so both parameters (flowName and environmentName) are already documented in the input schema. The description does not add meaning about the parameters themselves, so the baseline score of 3 is appropriate.

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

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

The description uses a specific verb ('Fetch') and names the exact resource: the full native Power Automate flow JSON from the PA API, including triggers, actions, parameters, and outputs. This distinguishes it clearly from related flow tools like get_live_flow_runs, get_live_flow_http_schema, and update_live_flow.

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

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

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

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

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

Beyond the readOnlyHint and destructiveHint annotations, the description clearly discloses a meaningful behavior: all data is read from the live flow definition via the PA API and no test call is made to the trigger URL. It also warns that the tool is deprecated and scheduled for removal. This is useful behavioral context beyond the annotations, though it does not cover failure modes or authorization requirements.

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

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

The description is compact and front-loaded with the core purpose, then adds the key safety/behavior detail ('no test call'), then ends with a direct usage recommendation. Every sentence earns its place and there is no padding.

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

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

For a two-parameter, read-only introspection tool without an output schema, the description provides adequate context: what is returned, how it is obtained, and when to use it. A little more context would be given by naming a non-deprecated alternative or clarifying what happens when the flow is not a Request-triggered flow, but the description is sufficient for safe 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?

The input schema already contains descriptions for both parameters with 100% coverage, so the baseline of 3 applies and the description does not need to repeat parameter explanations. The prose clarifies the context of the parameters (quickly Request-triggered flow, live flow definition) but does not add meaningful semantics about individual parameters themselves.

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 specifies a clear verb ('Inspect') and concrete resource ('HTTP interface of a Power Automate Request-triggered flow'), then enumerates exactly what will be returned: request JSON schema, required headers, HTTP method, and response action schemas. This makes its purpose distinct from siblings like get_live_flow_trigger_url even without opening any schemas.

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

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

It explicitly says to use this tool before calling trigger_live_flow to understand what body to send, and it notes that no test call is made, which helps an agent choose it over trigger_live_flow. It does not name alternatives or explicitly state when not to use it, so it falls just short of full prescriptive 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?

Beyond the readOnlyHint and destructiveHint annotations, the description discloses substantial behavior: the use of the PA repetitions endpoint, the fields included in each repetition record (repetitionIndexes, status, error, resolved inputs/outputs blobs), and iterationIndex matching against the innermost itemIndex. It adds meaningful behavioral context without contradicting the annotations.

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

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

The description is compact and information-dense. Every sentence contributes meaningful, non-redundant detail, leading with purpose and ending with iteration pinning behavior. No filler or repeated schema data is present.

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

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

For a tool with no output schema, the description pragmatically describes what the repetition records contain, while leaving top-level action record shape undescribed. It also relies on the schema for several parameter details, but the actionName/iterationIndex semantics and optional pagination context are already sufficient for most calls to be attempted 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 the baseline is 3. The description adds value by explaining the semantic interaction between actionName and iterationIndex, and by clarifying that iterationIndex must match the innermost nested repetition index. It goes beyond the schema descriptions but does not need to compensate for missing parameter docs.

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

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

The description opens with a specific verb and resource: 'Download inputs and outputs for actions in a flow run via SAS blob links from the live Power Automate API.' It then clarifies the two top-level modes based on actionName, making the tool’s purpose and scope unmistakable. This is clearly distinct 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 clearly separates when to provide actionName, when to omit it, and when iterationIndex should be used, which yields good context for invocation. It does not explicitly name alternative tools or provide when-not-to-use guidance, so it stops short of full 5 on this dimension.

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

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

Annotations already declare readOnly and non-destructive behavior. The description adds value by disclosing what the tool returns: each failed action with its error code and message. It does not cover pagination behavior or empty results, but the annotation safety picture is already complete.

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

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

Two sentences with no filler: the first identifies the operation and resource, the second identifies the output shape and purpose. It is front-loaded and every sentence earns its place.

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

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

All required parameters are documented, the output semantics are described, and the read-only behavior is covered by annotations. There is no explicit mention of the empty/no-error response, but the definition is complete enough for an agent to call the tool correctly.

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

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

Schema description coverage is 100%, so every parameter is already well documented. The description does not add new parameter-level semantics beyond the overall context of retrieving failures, so the baseline 3 is appropriate.

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

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

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

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

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

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

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

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

Annotations already mark the tool as readOnly and non-destructive. The description adds value by stating that it pulls live data from Power Automate and by enumerating the returned fields, including 'any top-level error,' which is useful behavioral context. It does not contradict annotations and does not need to disclose destructive effects since none exist.

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 states the action, source, and return payload without wasted words. Every part contributes to understanding what the tool does.

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 simple read-only nature, no output schema, and full parameter coverage in the schema, the description supplies the key missing context: what the run history contains. It is complete enough for an agent to know what to expect, though it could be slightly stronger on how it differs from related error/action-output tools.

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

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

Schema description coverage is 100%, so the parameters are already well documented. The tool description adds no additional parameter-level meaning beyond what the schema provides, so the baseline score of 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Fetch run history for a flow directly from Power Automate.' It names the expected return fields (run name, status, startTime, endTime, trigger name/code, top-level error), and the phrase 'directly from Power Automate' distinguishes it from sibling store-flow tools like get_store_flow_runs.

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

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

The description implies usage by saying 'directly from Power Automate,' which suggests it is for live flows rather than store flows. However, it does not explicitly state when to choose this over siblings such as get_live_flow_run_error or get_live_flow_run_action_outputs, nor does it mention 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 mark this as read-only and non-destructive, and the description adds behavioral value by stating that it calls the PA listCallbackUrl endpoint and always returns the current URL. It also discloses the null-return behavior for non-HTTP triggers, though it does not cover issues like failures, rate limits, or auth requirements.

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

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

The deprecation notice is front-loaded and then followed by compact, useful sentences covering purpose, endpoint behavior, return fields, and invalid-trigger behavior. Every sentence adds distinct information, and none of the description is wasted.

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

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

With only two schema-covered parameters and no output schema, the description is complete enough for safe selection and invocation. It explains the returned fields, the null behavior for unsupported triggers, and the deprecation status, so the agent can interpret results and inform the user.

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 both required parameters with 100% coverage, so the description does not need to add parameter-level detail. The description only helps by framing those parameters in the context of an HTTP-triggered live flow, which is adequate but no more than the baseline.

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

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

The description names a clear action and resource: fetching the live trigger URL and method for an HTTP-triggered flow directly from the Power Automate API. The endpooint distinction and the HTTP-trigger scope help differentiate this tool from related trigger and schema tools such as get_store_flow_trigger_url and get_live_flow_http_schema.

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

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

It gives explicit usage boundaries: this is for HTTP-triggered flows, and non-HTTP triggers will return null triggerMethod and triggerUrl. It also warns that the tool is deprecated and compares its listCallbackUrl behavior with get_flow_trigger_url, giving an agent enough context to decide between 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 mark this as read-only and non-destructive, so the bar is lower. The description adds useful context beyond that, including a plan requirement and the cache/snapshot behavior. It doesn't describe error cases or staleness, but for a safe read operation this is sufficient.

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

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

The description is compact and front-loaded: first the action and resource, then the key caveats. Every sentence contributes value, and there is no repetition of the tool name or schema.

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

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

For a simple read operation with only two string parameters, the description covers the source, the scoping, and the general content of the response. It could explicitly mention what happens if the flow is not in the cache, but the overall guidance is adequate.

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

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

The input schema fully documents both parameters with descriptions, and schema coverage is 100%. The description does not add any parameter-level meaning, so the baseline of 3 is appropriate.

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

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

The description clearly states what the tool does: 'Get full details for a single Power Automate flow from the Power Clarity cache.' It further distinguishes itself by specifying the data source is a stored snapshot, not the live API, which separates it from siblings like get_live_flow.

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

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

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

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: it is a cached snapshot (not live), it returns failedActions and remediation hints, and it is deprecated/scheduled for removal. This goes well beyond the annotations.

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

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

Every sentence earns its place: plan requirement, deprecation warning, functional purpose, return content, data freshness caveat, and alternative suggestion. The content is front-loaded with the most critical usage constraints and remains concise relative to the amount of context covered.

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 no output schema, the description still explains what the return value contains (failedActions and remediation hint). It fully covers the operational context (cached vs live), the deprecation status, and the recommended replacement. Nothing an agent needs for correct invocation is missing.

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

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

The input schema already provides full (100%) parameter descriptions for environmentName, flowName, and startTime. The description itself does not add additional parameter-level semantics beyond implying the flow's name is used. Baseline 3 is appropriate because the schema handles the parameter documentation burden.

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

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

The description clearly identifies the verb ('get'), resource ('cached failed run history for a flow from the Power Clarity store') and scope, distinguishing it from get_store_flow_runs and get_live_flow_runs. It also specifies that this is a convenience wrapper around get_store_flow_runs with status=Failed, making its 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 explicitly says the tool is deprecated and directs users to use get_live_flow_runs and filter by status=Failed instead. It also clarifies that the data is from a stored snapshot, not live from the Power Automate API, giving 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?

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

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

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

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

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

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

For a read-only query with no output schema, the description covers the essential missing context: return fields and units of measure. Together with the fully described input schema, annotations, and the Pro-plan requirement, an agent has enough to invoke it correctly.

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

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

The input schema has 100% description coverage, so the schema already explains each parameter. The description adds the default time window and return-field context, but does not add deeper parameter semantics beyond what the schema provides. A baseline 3 is appropriate.

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

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

The description clearly identifies the operation: getting cached run history for a flow from the Power Clarity store. It distinguishes this from live-flow tools by explicitly saying the data is from a stored snapshot, not live from the Power Automate API, which separates it from siblings like get_live_flow_runs.

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

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

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

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

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

Annotations already indicate the operation is read-only and non-destructive. The description adds valuable behavioral context: results come from a stored snapshot rather than live API calls, which informs freshness expectations. The Pro+ plan prerequisite is also disclosed. No contradiction with annotations.

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

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

Two tight sentences: the first states what stats are returned, the second clarifies the cached nature and disambiguates from live data. No filler or repetition of schema content.

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

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

With no output schema, the description helpfully enumerates the fields returned. The CEO at cached data and caches. The only minor gap is not pointing to sibling tools for live access or detailed run logs, but the essential calling information is present.

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

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

Schema description coverage is 100%, so all four parameters are already documented clearly. The description only reinforces that statistics are aggregated over a time window, which maps to startTime/endTime, but adds no new parameter meaning beyond the schema.

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

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

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

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

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

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

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

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

The annotations already mark this as read-only and non-destructive, but the description adds behavioral context beyond them: it reads from a stored flow record, makes no live Power Automate API call, requires Pro+, and is deprecated. This clearly sets expectations about staleness, side effects, and availability.

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

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

The description is compact and front-loaded: the key constraints are stated first, followed by the operational detail, then the alternative. Every sentence add meaningful guidance with no filler.

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

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

For a simple two-parameter read-only tool, the description covers the source of data, the fact no live call is made, the plan requirement, the deprecation status, and the alternative tool. The only minor gap is that the exact return shape is not described, but the tool name and first sentence already tell the agent what it returns: the trigger URL and trigger type.

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

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

Schema description coverage is 100%, so both flowName and environmentName are already documented in the schema. The description does not add much parameter-level detail, but it does not need to since the schema provides sufficient meaning. Baseline 3 is appropriate.

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

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

The description names a specific verb and resource: retrieving the trigger URL and trigger type for an HTTP-triggered flow. It also explicitly distinguishes itself from the live version by stating it reads from the Power Clarity cache rather than making a live API call, which makes it immediately identifiable among sibling 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?

The description provides explicit usage context: it is a cached read returning the stored trigger URL, and it points directly to get_live_flow_trigger_url when a guaranteed-fresh URL is needed. It also surfaces the Pro+ requirement and deprecated status, helping an agent decide whether to invoke it at all.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds useful behavioral context by noting it requires a Pro+ plan and reads from a cache, which signals that data could be cached rather than live. It also previews the included data (flow/app counts, deleted status), going beyond the annotations.

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

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

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

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

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

For a single-parameter getter with no output schema and very simple input, the description covers the essential context: input form, cache nature, and in summary of return data. It does not describe what happens when the maker key is not found or whether the cache is refreshed, but those are minor for a simple lookup tool.

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

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

Schema description coverage is 100% with makerKey documented as 'Maker RowKey (AAD object ID of the user).' The description adds a small but valuable reinforcement—italics 'by the maker (usually the AAD object ID)'—which helps the agent understand what to pass. Since the schema already covers the parameter, the description adds a little extra rather than a lot, so 4 is appropriate.

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

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

The description states a specific verb ('Get'), resource ('details for a single maker'), and scope ('from the Power Clarity cache by their key'). It also names the distinguishing return contents (flow/app counts, deletion status), and the singular/scoped phrasing clearly separates it from other getters like get_store_flow or list_store_makers.

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

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

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

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

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

Annotations already establish readOnlyHint=true and destructiveHint=false, so the description adds behavioral value by disclosing search behavior, automatic pagination, the paste-ready nature of templates, and the full createdBy object. This enriches the agent's understanding beyond the structured annotation data.

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

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

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

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

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

For a read-only list tool with no output schema, the description is complete: it names the primary purpose, all return fields, parameter-specific effects, pagination, environment requirements, and how results feed into update_live_flow. Nothing essential for a correct call is missing.

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

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

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

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

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

States a specific verb ('List') and resource ('Power Platform connections'), scoped to an environment and 'directly from Power Automate', which distinguishes it from sibling list_store_connections. The description also enumerates the returned fields, making the tool's purpose concrete and unambiguous.

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

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

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

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false, so the description is free to add behavioral details without redundancy. It does so by explaining the effect of each mode on the result set (admin mode errors on refusal rather than returning a shorter list, member mode skips the admin sweep), and by noting that isAdmin and isMember can be null when the corresponding scope was not queried. These details go beyond the schema and are valuable for the agent.

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 slightly longer than ideal but every sentence contributes to understanding the tool's behavior. The opening sentence states the core function and return fields, followed by a clear breakdown of modes. The structure is logical and front-loaded, and while it is verbose, it avoids redundancy. A 4 is appropriate because it is efficient but not extremely terse.

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 having no output schema, the description lists the fields returned (id, displayName, sku, location, state) and the additional contextual flags (isAdmin, isMember). It fully explains the three modes and their implications, including error behavior for admin mode. The tool's complexity is well covered; an agent can call it correctly without additional information.

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 both parameters already described in the schema. The description adds meaningful semantic depth by elaborating on the mode parameter's behavior (e.g., default, performance implications, error handling) and the interpretation of the returned flags (isAdmin/isMember null when scope not queried). It also clarifies that 'top' controls pagination, though that is already in the schema; the description reinforces the default behavior for mode. This exceeds the baseline for 100% 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?

The description states a clear, specific action ('List all Power Platform environments') and resource, and distinguishes itself from sibling tools by specifying 'directly from Power Automate' (i.e., live environments) as opposed to store-based tools like list_store_environments. It also enumerates the exact fields returned, making its scope 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 gives concrete guidance on when to use each mode: mode=all is the default, mode=member is recommended for speed in large tenants (skips admin sweep), mode=admin requires admin credentials and errors on refusal. It does not explicitly compare to sibling list_store_environments, but the tool name and the 'live' vs 'store' distinction make the alternative obvious. The usage context is well specified for the modes.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false; the description adds meaningful behavioral context such as admin account requirements, owner-mode scoping to personal + team flows with full definitions, and time-bounded pagination semantics. It doesn't cover auth failures or rate limits, but the main behavioral traits are disclosed.

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 tightly written and well structured: it front-loads the core purpose and return fields, then layers mode, search, and pagination details in a logical order. Every sentence earns its place without repeating what the schema already documents.

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

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

There is no output schema, but the description names the returned fields and sufficiently explains modes, search, and pagination for a listing tool. The reference to 'full definitions' is slightly ambiguous relative to the listed return fields, and edge/error cases aren't covered, but overall it is adequate for the tool's complexity.

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 adds value by clarifying that mode=owner is the default and includes personal + team flows with full definitions, that admin mode requires an admin account, and how timeoutSeconds and continuationUrl work together for pagination. This goes beyond the schema's existing descriptions.

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

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

States a specific verb and resource ('List Power Automate flows in an environment') and enumerates the returned fields, which clearly distinguishes it from generic list tools. It doesn't explicitly differentiate from sibling list_store_flows, so it stops short of a 5.

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

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

Provides strong conditional guidance: mode=owner vs admin with the admin account requirement, search filtering by displayName, and time-bounded pagination with continuationUrl handoff. It gives clear context for how to use the tool, though it doesn't explicitly state when to prefer this tool over list_store_flows.

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

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

Annotations already establish readOnlyHint and destructiveHint false; the description adds value by specifying the return contents and the non-billable trait. It also explains that the tool only lists descriptions and member names, not full tool definitions, which is relevant behavioral context beyond the annotations.

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

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

The description is concise and well-structured: the main purpose is front-loaded, followed by return value details, and then an explicit usage handoff. Every sentence earns its place, and the skill bundle examples help the agent understand the domain without padding.

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

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

For a no-parameter read-only listing tool, the description is complete: it states what is returned, the context for calling it, the recommended follow-up action, and cost implications. No required information appears missing for an agent to correctly invoke and use this tool.

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

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

The tool takes zero parameters, so there are no parameter semantics to document; the schema and signal data fully cover this. The description appropriately focuses on behavior and usage rather than empty parameter documentation.

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

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

States a specific verb and resource: 'List all skill bundles' with a precise definition of what a skill bundle is and what the call returns (description and member tool names). This clearly differentiates it from the many list_* sibling tools that enumerate concrete resources like flows, apps, or connections.

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

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

Explicitly instructs when to use it: 'Call this first when you are unsure which tools apply to a request.' It also tells the agent exactly what to do next, calling tool_search with 'skill:<name>', and notes the operation is non-billable. This leaves no ambiguity about its role versus alternatives.

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

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

Annotations already flag this as read-only and non-destructive, and the description adds useful context: the Pro+ plan requirement and the fact that data comes from a cache rather than live systems. It could be more transparent about possible staleness or output behavior, but the provided context goes beyond the structured annotations.

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

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

The description is a single, tightly packed sentence with the access requirement front-loaded and the core operation clear. Every part of the sentence adds information; there is no redundancy or filler.

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

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

For a zero-parameter, read-only list operation, the description covers the essential information: what it lists (Power Platform connections), where it gets them (Power cache), and the access requirement (Pro+ plan). It does not explain what Power Clarity is or whether cached results may be stale, but these are minor gaps for such a simple tool.

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

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

The tool has zero parameters and the schema has 100% coverage, so there are no parameter semantics to clarify. The description correctly implies a no-argument list operation. This matches the baseline for a parameterless tool.

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

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

The description states a specific action and resource: 'List all Power Platform connections,' with a clear source ('from the Power Clarity cache'). It is readable and distinguishes itself from live connection listing implicitly through the cache qualifier, though it does not explicitly name siblings or contrast with list_live_connections.

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

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

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

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description stays consistent with them. It adds value beyond annotations by disclosing a Pro+ plan requirement and 'from the Power Clarity cache,' implying cached, possibly stale data.

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

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

A single declarative sentence that front-loads the access requirement and describes the exact resource and source. There is no redundant or extraneous text.

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

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

For a zero-parameter read-only tool it is adequate, but there is no explicit comparison to the near-sibling list_live_environments, and since no output schema exists, the description could have briefly noted what the returned list represents. The missing return-shape context leaves a modest gap.

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

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

The tool has zero parameters and schema description coverage is 100%, so there are no parameter semantics to add. The baseline of 4 applies because there is no input surface requiring documentation.

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

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

The description names a specific verb ('List'), resource ('Power Platform environments'), and source ('Power Clarity cache'). This clearly distinguishes it from sibling list_live_environments by implying a cached data store.

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

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

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

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

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

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

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

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

The description is compact and front-loaded: plan requirement, core action, filters, return fields, and caching caveat appear in two tight sentences. Every sentence adds useful information and none of it repeats the schema.

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

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

The tool is simple with three optional boolean parameters and no output schema. The description covers plan requirements, data source, filters, and representative return fields. Some additional detail about the full return shape or pagination would improve completeness, but the description is largely sufficient for an agent to invoke this tool correctly.

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

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

Schema description coverage is 100%, so each parameter is already documented by the schema. The description's mention of 'governance flags (monitor, notification rules)' reinforces that the parameters are filters, but it does not add detail beyond what the input schema already provides. Baseline 3 is appropriate.

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

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

The description uses a specific verb ('List'), identifies the resource ('Power Automate flows from the Power Clarity cache'), and notes the caching behavior, which distinguishes it from live-flow tools such as list_live_flows. It also states optional filtering by governance flags. This is specific and differentiates the tool from its siblings.

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

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

The description clearly states the Pro+ plan requirement and the key usage context: data comes from a stored snapshot, not the live Power Automate API. This strongly implies when the tool should be used over a live alternative, though it does not explicitly name an alternative such as list_live_flows or state when to prefer one.

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

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

Annotations already declare read-only and non-destructive behavior, so the description adds value by disclosing the Pro+ plan requirement and the cache-based source, which implies the data may reflect cached state. It does not repeat the annotation flags, avoiding redundancy.

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

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

The description is a single sentence that front-loads the plan requirement, then gives the resource, action, and context. Every word adds meaning; there is no filler or repetition.

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

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

For a no-parameter, read-only list operation, the description gives sufficient context: the resource, scope, source, and access requirement. No output schema is provided, but the phrase 'List all makers' inherently conveys the return value as a collection of makers.

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

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

There are zero parameters and schema coverage is complete, so there is no missing parameter documentation. The description still adds slight semantic value by clarifying what entity a 'maker' is (citizen developers / AAD users), but no parameter-specific meaning is needed.

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

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

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

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

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

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

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

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

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

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

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

The description is a single, efficiently structured sentence that front-loads the licensing requirement before stating the exact function. Every part is relevant and there is no filler or redundant repetition of the tool name.

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

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

For a zero-parameter list-all operation, the description provides enough guidance: the scope (Power Apps canvas apps), the source (Power Clarity cache), and the access requirement. No output schema exists, but the operation is simple enough that an agent can safely invoke it without further explanation.

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

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

The input schema has zero parameters, so there is no parameter semantics to cover. The description does not need to document parameters, and the baseline of 4 applies since there is nothing to add beyond the schema.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Schema description coverage is only 22%, so the description must compensate for the many undocumented parameters. It does not explain the meaning of action values, ticket, category, severity, chunking, or the various contextual fields. The enums and defaults provide some structure, but the tool description adds essentially no parameter-level semantics.

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

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

The description names a specific verb and resource ('Report a Flow Studio MCP bug or missing capability') and explicitly covers the three modes: new report, append text evidence, and status/list. No sibling tool is about bug reporting, so it is cleanly distinguished from the surrounding operation-focused tools.

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

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

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

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

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

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

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

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

Two sentences with no redundant wording. The main purpose and key behavioral detail are front-loaded, and the note about trigger name discovery is concise and useful.

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

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

For a simple three-parameter action with clear annotations and full schema coverage, the description provides enough context to invoke the tool correctly. It does not describe the return value or outcome, but given the straightforward 'resubmit' semantics and lack of output schema, this is a minor gap.

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

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

Schema description coverage is 100%, so the three parameters are already well documented. The description adds extra value by explaining that no trigger name parameter is needed and why (automatic discovery), which is semantic context not available in the schema.

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

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

The description uses a specific verb ('Resubmit') with a clear resource ('failed or cancelled Power Automate flow run') and method ('via the live PA API'). It also states a distinguishing behavior ('re-using the original trigger payload') that separates it from sibling tools like trigger_live_flow or cancel_live_flow_run.

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

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

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

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

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

Annotations already provide idempotentHint=true (with readOnlyHint=false and destructiveHint=false), but the description adds meaningful behavioral context beyond them: it discloses the pre-read mechanism ('Reads the current flow state first and only issues the start/stop call if a state change is actually needed') and documents the return payload even though no output schema exists. This is genuinely useful, non-redundant disclosure.

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

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

Three tight sentences with zero filler. The core purpose is front-loaded in sentence one, scope in sentence two, and behavioral/return details in sentence three. 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 3-parameter mutation tool with no output schema, the description covers purpose, scope, idempotent behavior, and return values. The only notable gap is that it doesn't specify behavior in the no-op case (when the flow is already in the desired state), though the pre-read sentence strongly implies a safe skip.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters, including the Started/Stopped enum for state. The description's 'start or stop' phrasing mirrors the enum values rather than adding new meaning, so it doesn't compensate or extend beyond the schema. 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 opens with a specific verb phrase, 'Start or stop a Power Automate flow', identifying the exact action and resource. It further clarifies scope ('any environment you have access to') and is clearly distinguishable from siblings like trigger_live_flow (runs) and cancel_live_flow_run (run cancellation) without requiring schema inspection.

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 intended use is implied by the action phrase and the live-flow scope, but the description never names alternatives or exclusion conditions. Notably, it doesn't address the closely related set_store_flow_state sibling, so an agent must infer the live-vs-store distinction from tool naming alone rather than explicit 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 indicate mutation and destructiveness, but the description adds meaningful context: the operation performs a live API call, persists state back to the store, and returns the updated stored record. The deprecation flag is also valuable behavioral information.

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

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

The description is compact and front-loaded with the most decision-relevant facts: plan requirement, deprecation, and preferred alternative. Every sentence earns its place, and the replacement guidance is 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?

The description covers the action, alternative, prerequisite, and return value, which is sufficient for a simple 3-parameter tool. It does not describe error cases or side effects beyond what annotations imply, but these are not critical gaps here.

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 parameters are fully documented in the schema itself. The description adds no additional parameter-level meaning beyond what the schema already provides, which is acceptable but not exceptional.

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

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

The description states a specific action ('Start or stop a Power Automate flow'), names the resource, and explicitly distinguishes this tool from its sibling by directing users to 'Use set_live_flow_state instead.' The deprecation notice adds important purpose-related context.

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 recommends set_live_flow_state as the replacement, signaling that this tool should generally be avoided. It also notes the Pro+ plan prerequisite, giving the agent explicit preconditions for 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 already mark this read-only and non-destructive, so the description does not need to restate safety. It adds meaningful behavioral context beyond annotations: search is non-billable, returns full JSON schemas ready for use, supports distinct query forms, and uses a ranked match for free-text queries. 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 key guidance is front-loaded, with the prefer-this directive and purpose in the first few words. The rest is organized compactly: when-to-use, query forms with concurrent examples, and bundle names. Every sentence adds value and there is little redundant filler.

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

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

Given the low complexity of the tool (two parameters, one required, 100% schema coverage) and simple input schema, the description covers everything needed to invoke it correctly: query formats, behavior of max_results, what to do about skill bundle names, and expected output nature. The lack of an output schema is mitigated by explicitly revealing that it returns full JSON schemas for matched tools.

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

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

Schema coverage is 100%, but the description goes further by giving concrete query form syntax including 'skill:<name>', 'select:name1,name2', and real free-text examples like 'cancel run' or 'trigger url'. It also clarifies the relationship between query forms and max_results, noting it is ignored for select and skill forms.

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

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

The description opens with 'PREFER THIS...' and clearly identifies the resource being searched ('Flow Studio MCP tools'), the action ('Searches by keyword, skill bundle, or explicit selector'), and the deliverable ('returns full JSON schemas for matched tools'). It explicitly differentiates itself from the other tools on the server by framing itself as the meta-search tool for choosing among them.

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

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

It gives explicit when-to-use guidance: whenever you are not 100% sure how to map a user request to functionality, and when loading a whole skill bundle. It also names the three supported query forms with examples and directs users to use list_skills first for bundles, making alternative and prerequisite behavior clear.

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

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

The description substantially exceeds the minimal annotations (readOnlyHint=false, etc.) by disclosing side effects (runs a flow), return fields (httpStatus, response body, triggerKind, runName), and the refusal of body for scheduled flows. It also clarifies that runName may be absent and directs to get_live_flow_runs otherwise—information annotations cannot convey.

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

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

The description is longer than typical but every sentence earns its place: purpose first, then trigger-type details, then parameter guidance, then return notes, then exclusions. It is front-loaded and structured logically, though slightly dense for a quick scan.

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

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

For a tool that triggers flows with no output schema, the description covers all essential runtime concerns: what inputs to pass, how to handle flows that take no inputs, what the response contains, and which trigger types are unsupported. It also points to the sibling tool for run details, making it self-contained for correct 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?

While schema coverage is 100% and each parameter is already documented, the description adds critical usage semantics for the body parameter: 'Pass trigger inputs as `body`' and 'Omit for flows that expect an empty body,' plus the refusal rule for recurrence flows. This goes beyond the schema's generic 'JSON body to POST' and helps the agent construct correct calls.

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

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

States a specific verb-resource pair ('Run a flow on demand') and immediately distinguishes itself from siblings by naming the alternative tool for retrieving runs ('use get_live_flow_runs otherwise'). The trigger-type coverage (Request, recurrence) is explicit, so an agent can tell it apart from get_live_flow_trigger_url or get_live_flow without opening schemas.

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

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

Provides explicit when-to-use conditions: works with Request triggers (HTTP, Button, PowerApps) and recurrence flows, and clearly states when NOT to use it (Automated connector triggers) and what to do instead (they only fire from their source event). Also notes the refusal of body for scheduled flows, adding a behavioral caveat that prevents misuse.

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

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

Annotations declare idempotentHint=true, but the description explicitly says that when flowName is omitted or blank, a new flow is created via PUT with a generated GUID. Repeated identical calls would therefore create distinct flows, which is a direct contradiction of the idempotency annotation. Despite otherwise rich behavioral detail, the contradiction forces a score of 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 long but well-organized with bold labels and front-loaded core behavior. Some details, especially operations path guidance, are repeated in the input schema, but the complexity of the tool justifies most of the length.

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

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

With no output schema and 7 parameters including nested objects, the description compensates well: it covers create/update modes, response updated list semantics, dryRun behavior, cache mirroring, validation errors, and edge cases like connectionReferences accompanying operations. An agent has enough context to call the tool correctly in most scenarios.

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

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

Although the schema already covers all parameters, the description adds substantial meaning beyond the schema: it explains operations path semantics, connectionReferences merging and pruning behavior, dryRun behavior, the required definition.description, and the suffix appended for usage tracking. This is far beyond the baseline for 100% 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?

The description opens with a specific verb-resource pair: 'Update or create a Power Automate flow via the live PA API.' This immediately distinguishes the tool from siblings like get_live_flow and update_store_flow by naming the live API and the write/create capability.

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

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

The description gives explicit when-to-use guidance: omit flowName to create, provide flowName to update, use operations for surgical edits, and use definition for whole-definition replacements. It also names get_live_flow as the source for full definitions and states exclusions like 'Provide EITHER operations OR definition' and 'do not combine with definition.'

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

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

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

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

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

Three tightly scoped sentences front-load the plan requirement and key behavior. Every sentence earns its place: what it updates, the merge semantics, and the cache/API distinction. No filler or redundancy.

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

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

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

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

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

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

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

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

The description clearly states the verb and resource: 'Update governance/metadata fields on a flow record in the Power Clarity store' and gives concrete field examples. It inherently distinguishes this from sibling tools like update_live_flow by anchoring on the store and explicitly noting it 'does not call the Power Automate API'.

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

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

The description gives clear context for when to use this tool: updating stored governance/metadata fields, with the plan requirement and the cache-only behavior. It does not explicitly name alternatives or exclusion cases, but the store vs. live distinction is strong enough to guide selection.

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