Power Automate MCP Server by Flow Studio

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

Beyond the annotations (readOnlyHint=false, idempotentHint=true), the description adds valuable behavioral details: it mentions the specific API used ('migrateFlows'), the error behavior for already-solution flows, and the default behavior when solutionId is omitted. This exceeds what annotations alone provide and gives the agent a clear model of what will happen.

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 sentences, with the primary action stated first. Every sentence adds unique information: the migration action, the error condition, and the optional parameter behavior. 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?

Given the tool's moderate complexity and lack of output schema, the description is fairly complete. It covers the core action, the failure mode, and optional behavior. It does not mention prerequisites like required permissions or what happens to dependencies (e.g., connections), but those are not critical for the primary use case and the annotations provide safety hints. Overall, it is sufficiently complete for an agent to select and invoke the tool correctly.

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

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

The input schema already has 100% parameter description coverage, so the baseline is 3. The description does not add substantive new meaning about the parameters beyond what is in the schema—it rephrases the optional nature of solutionId and the purpose of flowName and environmentName, but those are already documented. There is no additional syntax, format, or example data provided.

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

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

The description clearly states the tool's function: 'Migrate a non-solution Power Automate flow into a solution via the admin migrateFlows API.' This is a specific verb plus resource, and it distinguishes itself from sibling tools (which are all get/set/trigger/update operations, not migrations). The optional default solution behavior adds further clarity.

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 non-solution flows, and explicitly mentions that if a flow is already in a solution, the tool returns an error without attempting migration, effectively telling users when not to use it. It also explains the optional solutionId behavior with 'omit to migrate into the default solution.' It stops short of naming alternative tools, but given the unique purpose, that is not a significant gap.

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

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

The description complements the annotations (destructiveHint=true, idempotentHint=true) by adding that only 'Running' runs can be cancelled, giving practical behavioral context. It does not contradict annotations and adds value beyond the structured hints.

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

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

The description is two compact sentences, front-loaded with the core purpose and followed by essential usage and condition. Every sentence earns its place with no redundancy.

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

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

Given the tool's simplicity (3 required params, no output schema), the description provides sufficient context: what it does, how to use it, and when it applies. It is complete for an agent to select and invoke correctly.

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

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

Schema coverage is 100%, so parameters are already well documented. The description adds a hint about deriving runName from get_live_flow_runs, which is helpful but does not significantly enhance parameter understanding 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 clearly states the action (cancel), the resource (a Power Automate flow run), and the scope (currently running). It distinguishes from sibling tools like resubmit_live_flow_run or trigger_live_flow by specifying the cancellation operation.

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 usage guidance: use after get_live_flow_runs to obtain the run name, and only runs with status 'Running' can be cancelled. This is clear context with a prerequisite and condition 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?

Although the annotation readOnlyHint=true already indicates a read-only operation, the description enriches this by disclosing output contents: compact operation catalog, expanded inputs/outputs, dynamic parameter metadata, nextTool hints, authored hints, example shapes, and raw OpenAPI metadata. It also notes connection-aware suggestions, going well beyond the annotation's basic safety signal.

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 compact paragraph of five sentences, each earning its place: purpose, alignment reference, summary mode, operationId mode, search/full mode. It front-loads the main purpose and immediately follows with operational guidance, with no filler or repetition of schema details.

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 9 parameters and no output schema, the description thoroughly covers the tool's modes, parameter interactions, and integration with sibling tools (get_live_dynamic_options, update_live_flow). It explains when to use search without connectorName, how variants work, and what each mode returns, leaving no major gaps 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?

With 100% schema description coverage, the baseline is 3, but the description adds substantial meaning beyond the schema. It explains how parameters combine: mode=summary vs full, operationId for individual operations, search behavior with and without connectorName, apiName as an alias, and variant handling for multiple authored variants. This contextualizes the flat parameter list into coherent usage patterns.

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 'Describe a live Power Platform connector/API and its operations,' which clearly identifies the verb (describe), resource (connector/API), and scope. It distinguishes itself from sibling tools by explicitly framing its modes and outputs, such as producing operation catalogs, operation details, and cross-connector search results, which are unique among the listed 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 precise, actionable guidance: use summary mode by default for a compact catalog, operationId for a single operation's details, search without connectorName for cross-connector search, and full mode only when raw OpenAPI metadata is required. It also references nextTool hints for calling get_live_dynamic_options and copyable shapes for update_live_flow, clarifying interactions with sibling tools.

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

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

The description adds behavioral context beyond the readOnlyHint annotation by explaining it works with x-ms-dynamic-list and x-ms-dynamic-values metadata and giving real-world examples like Teams and SharePoint. It doesn't describe output format, but that's acceptable given the annotation covers safety and the examples clarify expected behavior.

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

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

The description is two sentences, highly efficient, with the primary purpose in the first sentence and usage context in the second. No filler or 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?

The tool has a moderately complex schema with nested objects, but the description combined with full schema coverage provides sufficient context for correct invocation. It doesn't describe return values, but no output schema exists and the examples imply the type of data returned, so completeness 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 has 100% coverage, with detailed descriptions for all 8 parameters. The description adds some high-level context about parameter types (e.g., dynamicMetadata) but doesn't add significant new semantics beyond the schema, so a baseline score of 3 is appropriate.

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

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

The description clearly states the tool resolves live dynamic dropdown/list options for a connector operation parameter, which is a specific verb+resource combination. It distinguishes from sibling tools like get_live_dynamic_properties by mentioning the nextTool trigger and metadata types.

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 specifies when to use the tool: when describe_live_connector returns a dynamic parameter with nextTool=get_live_dynamic_options. This gives clear context and examples of applicable scenarios, although it doesn't explicitly list alternatives or exclusions, the condition is sufficient.

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

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

The readOnlyHint annotation already establishes safety, and the description adds the constraint that it works with specific metadata types (x-ms-dynamic-properties/x-ms-dynamic-schema). However, it does not disclose the return format, error behavior, or any side effects beyond what annotations cover. With no output schema, the description could provide more detail, but it is not misleading.

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

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

The description is two sentences, front-loaded with the main purpose and followed by precise usage guidance. Every clause adds meaningful information with 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?

Despite having 12 parameters and no output schema, the description covers the critical context: when to use it, what metadata it handles, and a representative use case. It does not enumerate return values, but the action of 'resolve' implies the output is the schema/properties, and the trigger condition ties it to describe_live_connector. Minor gap: no mention of optional parameters like propertyName or includeRaw, but these are well-documented in the schema.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds value by linking dynamicMetadata to describe_live_connector's output and illustrating the 'parameters' field with the SharePoint example. This clarifies the intended usage of several parameters beyond their schema descriptions.

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

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

The description states a specific verb and resource: 'Resolve live dynamic schema/properties for a connector operation parameter.' It further distinguishes from siblings by referencing describe_live_connector's dynamicProperties entry and explicitly mentions x-ms-dynamic-properties and x-ms-dynamic-schema, setting it apart from get_live_dynamic_options.

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 when-to-use condition: 'Use this when describe_live_connector returns a dynamicProperties entry with nextTool=get_live_dynamic_properties.' It also provides a concrete example (SharePoint item fields) and implies an alternative (describe_live_connector for initial metadata), making usage context clear.

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

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

Annotations already declare readOnlyHint=true, establishing it as a safe read operation. The description adds valuable behavioral context by stating it 'Returns the raw properties object exactly as the PA API returns it,' which clarifies the return format and fidelity. It also enumerates the included components (triggers, actions, parameters, outputs), providing useful expectations for the response.

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 exceptionally concise, consisting of three efficient sentences that each add value. It front-loads the primary action and includes necessary context about the return object and a specific use case. No redundant wording or excessive 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 simple read-only tool with fully described parameters, the description is complete. It specifies the output format (raw properties object), the content (full flow definition), and the intended usage context (before update_live_flow). With readOnlyHint annotation and no output schema, it covers all necessary information for an agent to invoke correctly.

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

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

Schema description coverage is 100%, with both flowName and environmentName clearly described in the schema. The description does not add additional meaning beyond the schema, as it focuses on the return value rather than parameter details. Baseline of 3 applies because the schema already handles parameter documentation effectively.

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

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

The description clearly states the tool's function: 'Fetch the full native Power Automate flow JSON from the PA API'. It specifies the resource (live flow) and scope (complete flow definition including triggers, actions, parameters, outputs). It distinguishes from sibling tools like get_live_flow_runs and update_live_flow, making its unique purpose evident.

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 a clear use case: 'Use this to inspect the full definition before calling update_live_flow with a modified definition.' This gives context on when to use the tool in a workflow. It does not explicitly mention exclusions or alternatives, but the specific scenario implies appropriate usage and differentiates it from related tools.

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

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

Annotations already indicate readOnlyHint=true, but the description adds crucial behavioral context: the tool reads from the live flow definition via the PA API and does NOT make a test call to the trigger URL. It also clarifies the scope of what is inspected, which goes beyond the annotation.

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

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

The description is two sentences, front-loaded with the deprecation warning, then a precise purpose, then a usage directive. Every sentence earns its place with no redundant or vague 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 simplicity (2 params, no output schema), the description fully covers what the tool does, what it returns, how it behaves (read-only via API, no test call), and how to use it in context (before trigger_live_flow). Deprecation status is also included.

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 clear parameter descriptions ('Name (ID) of the flow.', 'Name of the Power Platform environment.'). The description does not add additional parameter-level detail, but the schema is sufficient, so the baseline 3 applies.

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

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

The description uses a specific verb ('Inspect') and clearly identifies the resource ('HTTP interface of a Power Automate Request-triggered flow'). It enumerates the exact outputs (JSON schema, headers, method, response schemas), making it distinct from siblings like get_live_flow_trigger_url and trigger_live_flow.

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

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

Explicitly states when to use the tool: 'Use this before calling trigger_live_flow to understand what body to send.' Also clarifies a key constraint (no test call is made), which prevents misuse. The deprecation warning further guides usage.

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

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

The description goes beyond the readOnlyHint annotation by explaining the internal PA repetitions endpoint, the structure of repetition records (repetitionIndexes, status, error, resolved blobs), and the matching rule for iterationIndex against the innermost itemIndex. This 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 four sentences that are dense but efficient: the first sentence states the core function, the next two cover the two modes, and the last explains the iterationIndex logic. No filler, repetition, or irrelevant detail; it is front-loaded and well-structured.

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

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

For a complex tool with 6 parameters and no output schema, the description is remarkably complete. It covers the required inputs, two distinct behaviors, the return record structure, iteration pinning, and the resolved blob outputs. The readOnly annotation handles the safety profile, and pagination is captured in the schema's 'top' description, so no significant gaps remain.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by clarifying the interaction between actionName and iterationIndex, including how iterationIndex matches the innermost repetitionIndexes itemIndex, and by noting the 'top' parameter's automatic pagination. This supplements the static schema descriptions with operational semantics.

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

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

The description clearly states the tool downloads inputs and outputs for actions in a flow run via SAS blob links from the live Power Automate API. It distinguishes two modes (top-level actions without actionName vs all repetitions with actionName) and differentiates from sibling tools like get_live_flow_runs and get_live_flow_run_error.

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

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

The description provides explicit mode-based usage: without actionName returns top-level actions, with actionName returns all repetitions, and iterationIndex pins to a single iteration. It does not explicitly name alternatives or state when to prefer this tool over siblings, but the conditional logic is clear enough for an agent to apply correctly.

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

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

Annotations declare readOnlyHint=true, but the description adds valuable behavioral context by specifying that it lists every failed action with error code and message, and that it accesses the 'live Power Automate API'. This goes beyond what annotations alone communicate, though it does not cover pagination or error cases.

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

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

The description is two sentences, action-first, and every word serves a purpose. It states what it does, what it returns, and why, without any fluff or repetition of schema details.

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

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

Given the tool's moderate complexity (4 params, no output schema), the description provides sufficient context by describing the output behavior (lists failed actions with codes and messages) and the scope (specific flow run from live API). It could mention what happens if there are no errors, but this is not critical.

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 all 4 parameters already documented including detailed descriptions (e.g., runName field from get_live_flow_runs). The tool description does not need to add parameter semantics, so the baseline of 3 applies.

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

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

The description uses a specific verb 'Fetch' with a clear resource 'error details for a specific flow run' and mentions the output (every failed action with error code and message). This clearly distinguishes it from siblings like get_live_flow_runs (which lists runs) and get_live_flow_run_action_outputs (which retrieves 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?

The description implies diagnostic usage ('to help diagnose what went wrong') but does not explicitly state when to prefer this tool over alternatives or mention any exclusions. No sibling tools are referenced, so the guidance is only implicit.

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

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

Annotations only declare readOnlyHint=true; the description adds non-obvious behavioral context by disclosing that the tool uses impersonation, hits the live API rather than a cached store, and returns a specific set of fields. This goes beyond the annotation without overstating behavior.

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

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

Two tightly packed sentences: one states action and source, the second lists return fields. Every clause carries information, and the most important distinction ('not the cached store') appears early.

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 compensates by enumerating return fields. For a low-complexity filtered list tool with fully documented parameters and a read-only annotation, this is largely complete, though it does not specify output shape beyond field names or potential error 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 documents all three parameters. The description does not add any additional meaning to the parameters beyond reiterating what live run history contains, so it stays at the baseline.

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

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

Description opens with 'Fetch live run history for a flow' — a specific verb, resource, and source. It also differentiates from the sibling cached-store tool by adding 'directly from the Power Automate API using impersonation — not the cached store.'

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

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

The phrase 'directly from the Power Automate API using impersonation — not the cached store' gives clear context for when this live source is appropriate, implicitly distinguishing it from get_store_flow_runs. It stops short of explicitly naming the alternative or stating 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?

Beyond the readOnlyHint annotation, the description reveals the specific endpoint used, the exact return fields (triggerName, triggerType, triggerKind, triggerMethod, triggerUrl), and the behavior for non-HTTP triggers (triggerMethod and triggerUrl are null). This far exceeds what the annotation provides.

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

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

The description is concise and well-structured. It front-loads the deprecation notice and core purpose, then adds the alternative comparison, return fields, and edge-case behavior in a logical order. Every sentence earns its place 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?

The description fully covers the tool's behavior for a simple 2-parameter read-only operation. It explains the return values (since no output schema is provided) and handles edge cases (non-HTTP triggers). No important context is missing.

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

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

Schema description coverage is 100%, so both parameters are well-documented in the schema. The description does not add extra meaning to the parameters themselves; it only implies the flow must be HTTP-triggered, which relates to the flow, not the parameter format. Baseline 3 is appropriate.

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

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

The description clearly states the tool fetches the live trigger URL and method for an HTTP-triggered flow. It uses a specific verb ('fetch') and resource, and differentiates itself from 'get_flow_trigger_url' by noting it calls the listCallbackUrl endpoint, ensuring the URL is always current.

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

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

The description explicitly mentions being deprecated and scheduled for removal, which serves as a 'when not to use' guideline. It also points to an alternative ('get_flow_trigger_url') and explains the difference, giving clear context for choosing between them.

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, but the description adds critical behavior: data is from a stored snapshot, not live, and a Pro+ plan is required. It also lists the exact categories of data returned, providing transparency beyond the annotation.

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

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

Two sentences, front-loaded with the plan requirement, then clear purpose. No wasted words; every clause adds value.

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

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

With no output schema, the description enumerates the kinds of details returned (trigger URL, owners, state, run statistics, governance metadata) and clarifies the data source. It's sufficient for a single-item lookup, though it could mention cache freshness or absence 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 coverage is 100% with clear descriptions for both parameters. The tool description does not add parameter-specific meaning beyond the schema, so the baseline score of 3 applies.

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

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

The description uses a specific verb ('Get') and resource ('single Power Automate flow'), and explicitly states the source ('Power Clarity cache'). It distinguishes from siblings by emphasizing 'full details' and contrasting with live API data.

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 implies when to use this tool: when cached data is acceptable and full details are needed. It notes the Pro+ plan requirement and the distinction from live data, but doesn't explicitly name alternative sibling tools like get_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?

Beyond the readOnlyHint annotation, the description discloses that data is from a stored snapshot, not live, that the tool is deprecated and requires Pro+ plan, and that it returns failedActions and remediation hint. This adds significant behavioral context beyond the annotation.

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

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

The description is dense but well-structured with bracketed meta-info, purpose, caveats, and alternative. Every sentence earns its place, though the bracketed prefixes make it slightly less streamlined than a simpler two-sentence description.

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 deprecated cached read tool, the description covers purpose, output fields, data source caveat, and alternatives. It even mentions the convenience nature and deprecation. No output schema exists, but the description sufficiently explains what to expect.

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 descriptions for all three parameters (100% coverage), so the description does not need to explain them. It does not add further parameter-specific meaning, but the schema is sufficient.

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

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

The description clearly states the tool's function: 'Get cached failed run history for a flow from the Power Clarity store' with specific output ('failedActions and remediation hint'). It distinguishes itself from siblings by mentioning it's a convenience wrapper around get_store_flow_runs with status=Failed and pointing to get_live_flow_runs as an alternative.

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

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

It provides explicit usage guidance: identifies itself as a convenience wrapper, notes deprecation, and directly instructs to 'Use get_live_flow_runs and filter by status=Failed instead.' This clearly communicates when not to use it and names the preferred alternative.

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

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

Annotations only provide readOnlyHint: true. The description adds valuable context beyond that: the data is cached/snapshot-based (not live), requires a Pro+ plan, and returns specific fields. This enriches the agent's understanding of the tool's behavior and access requirements without contradicting the annotation.

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

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

The description is concise, front-loaded with the access requirement, and each sentence provides distinct value: what it does, default window, return fields, and the snapshot caveat. 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?

Even without an output schema, the description enumerates the returned fields (startTime, endTime, status, duration, failedActions, remediation hint). It also covers the data source, default time window, and access requirement, making the tool's behavior and expected output clear for an agent.

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

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

Schema coverage is 100% with descriptive parameter definitions, so the schema carries the parameter semantics. The description does not add parameter-specific details beyond what's already in the schema, such as the default startTime which is already documented 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 clearly states the tool gets cached run history for a flow from the Power Clarity store, with specific verbs and resource. It distinguishes itself from siblings like get_live_flow_runs by explicitly noting the data is from a stored snapshot, not live from 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 provides clear context: it's for cached run history, defaults to the last 7 days, and requires a Pro+ plan. It implies a use case distinct from live alternatives but does not explicitly name alternatives or provide when-not-to-use guidance, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true. The description adds that data comes from a 'stored snapshot — not live', which is valuable behavioral context about data freshness. This is consistent with annotations and gives a clearer expectation of what the tool accesses.

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

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

Two concise sentences: the first states the purpose and prerequisite, the second clarifies the data source caveat. Every clause is informative, with no redundancy or fluff.

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 summary tool with clear schema and annotations, the description covers what, where, and the data source caveat. No output schema exists, so return values need not be detailed. A minor gap is that units for durations are not specified, but that is not critical.

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 all parameters are already well-documented. The description only adds the phrase 'over a time window', which aligns with startTime/endTime but does not add new meaning beyond what the schema provides.

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

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

The description clearly states the verb 'Get aggregated run statistics' for a flow, lists the specific metrics returned, and distinguishes from the live API by noting 'stored snapshot — not live'. This differentiates it from sibling tools like get_store_flow_runs which provide raw run records.

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 by stating the Pro+ plan requirement and emphasizing that data is cached rather than live, implying it is for aggregate views. However, it does not explicitly name alternative tools or state when not to use it, so some exclusions are missing.

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

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

Beyond the readOnlyHint annotation, the description discloses key behavioral traits: it reads from the stored cache, makes no live API call, and is not guaranteed-fresh. It also notes the deprecation status and plan requirement, adding substantial context about access and lifecycle that annotations do not provide.

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 critical caveats (plan requirement, deprecation). It uses two sentences to convey purpose, source, behavioral distinction, and an alternative, with no wasted words.

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

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

For a simple getter with two parameters and no output schema, the description fully covers what the tool does, where it gets data from, its freshness limitations, and how it relates to the live alternative. The return values (trigger URL and trigger type) are explicitly stated, making the context complete.

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

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

The schema already provides 100% coverage of the two parameters (flowName and environmentName) with clear descriptions, so the baseline is 3. The tool description adds no additional parameter-specific meaning, but it does not need to since the schema is sufficient.

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

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

The description clearly states the tool gets the trigger URL and trigger type for an HTTP-triggered flow from the Power Clarity cache, using a specific verb and resource. It distinguishes itself from siblings by emphasizing the cached nature and explicitly naming the alternative get_live_flow_trigger_url for a fresh URL.

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

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

The description provides explicit usage guidance: it states the tool reads from cache and makes no live API call, and directs users to get_live_flow_trigger_url for guaranteed-fresh data. It also flags the tool as deprecated and requiring Pro+ plan, effectively telling users 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 mark readOnlyHint=true, and the description adds valuable context: Pro+ plan requirement, cache-based source, and the included details (flow/app counts, deleted status). It does not disclose error cases, but the added context goes beyond the annotation.

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

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

The description is a single, front-loaded sentence with the plan requirement first, followed by the action and scope. Every clause adds information without redundancy.

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

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

For a single-get tool with one parameter and no output schema, the description sufficiently explains what the tool returns (counts and deletion status). It does not specify output structure or error scenarios, but for a simple lookup, this 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?

Schema coverage is 100%, with the parameter described as 'Maker RowKey (AAD object ID of the user).' The description adds 'usually' to qualify the key format, but this is marginal. The schema already provides the core semantics.

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

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

The description clearly states 'Get details for a single maker' with a specific resource (Power Clarity cache) and identifies the input key as the AAD object ID. It distinguishes from sibling list_store_makers by emphasizing 'single' and key-based lookup.

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 context is clear: use this tool for a single maker by key, which implies it is not for listing makers. It does not explicitly name alternatives or exclusions, but the 'single' qualifier provides sufficient 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 readOnlyHint already indicating safety, the description adds meaningful behavioral context: it returns live API data, includes full objects, and the search parameter produces paste-ready templates for integration. This goes beyond the annotation without contradicting it.

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 focused sentences that front-load the core purpose, list return fields, and provide integration guidance. Every sentence contributes information without 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?

Despite having no output schema, the description compensates by listing returned fields and explaining search behavior and integration with update_live_flow. It omits details about statuses/overallStatus meanings, but the schema covers parameter semantics, and the tool's simplicity does not demand more.

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 provides 100% coverage of all three parameters, so the baseline is 3. The description adds only a brief restatement of the search functionality ('Pass search=<term> to narrow the list') and the template addition, but does not explain top or environmentName beyond what the schema already states.

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

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

The description clearly states the action ('List') and specific resource ('Power Platform connections'), and immediately distinguishes from the cached store alternative by noting 'not the cached store'. It also enumerates the return fields, making the 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 implies when to use this tool by contrasting it with the 'cached store' and mentions a specific use case with 'update_live_flow'. However, it does not explicitly name sibling tools like list_store_connections as alternatives or state when not to use this tool, so it falls short of full 5.

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

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

Annotations only state readOnlyHint=true, so the description adds significant behavioral context: the live API source, the specific fields returned (id, displayName, sku, location, state), and the account visibility constraint. This exceeds the annotation baseline and makes behavior clear.

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

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

Two concise sentences: the first states the main purpose and source, the second outlines return fields and scope. Every sentence carries essential information with no redundancy.

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

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

Given the low complexity (one optional parameter, no output schema, read-only annotation), the description adequately covers the tool's purpose, source, return fields, and account scope. Sibling differentiation is also addressed via the 'not the cached store' contrast.

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 for the only parameter 'top', including pagination behavior and default. The tool description adds no additional parameter semantics, so the baseline 3 applies.

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

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

The description clearly states the verb 'List' and the resource 'Power Platform environments', and explicitly contrasts with 'not the cached store', distinguishing it from sibling tools like list_store_environments. It also specifies the return fields, which further clarifies its purpose.

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

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

The phrase 'directly from the Power Automate API — not the cached store' implies when to use this tool over the store alternative, but it does not explicitly name the sibling tool or provide detailed when-not-to-use guidance. The mention of 'impersonated service account' gives useful context on visibility scope.

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 include readOnlyHint=true, but description goes beyond by disclosing time-bounded pagination, mode-specific scoping (personal+team vs all), and admin account necessity. This adds rich context without contradicting 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?

Dense but well-structured text, each sentence serves a purpose. Uses clear separations for modes and pagination. No fluff, appropriate length for the tool's complexity.

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 missing output schema, description lists return fields (id, displayName, state, triggerType, lastModifiedTime), explains pagination, mode differences, search, and continuation. This fully covers the tool's behavior for effective use.

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

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

Schema has 100% parameter coverage, yet description adds significant meaning: mode enum explained with examples, search case-insensitivity, continuationUrl resume semantics, and timeoutSeconds behavior. This is far beyond 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 starts with 'List Power Automate flows in an environment,' using a specific verb and resource. It distinguishes from get_live_flow (single flow) and list_store_flows (store flows) by detailing live flow listing in environment 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?

Provides clear context on modes (owner vs admin), admin requirement, search filtering, and pagination continuation. Does not explicitly compare with sibling tools, hence no exclusions, but the guidance is strong.

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

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

Annotations already declare readOnlyHint=true, so the read-only nature is covered. The description adds value beyond that by specifying the return format (each skill's description and member tool names) and noting that the tool is non-billable. It does not contradict the annotation, but omits details like pagination or any depth limitations, so a 4 is appropriate.

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 sentences, each earning its place: the first defines the resource, the second explains the return value, and the third gives usage guidance. No word is wasted, and the structure is front-loaded with the core purpose before practical instructions.

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

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

For a zero-parameter, no-output-schema listing tool, the description is fully complete. It covers what the tool does, what it returns, when to use it, and how to follow up. Sibling tools are sufficiently differentiated, and no critical information is missing given the simplicity of the 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 coverage is trivially 100%. Per the rubric, a baseline of 4 applies when no parameters exist, and the description correctly avoids inventing parameter details. It provides no unnecessary parameter explanations, keeping the focus on the tool's purpose and usage.

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

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

The description clearly states the tool 'List all skill bundles' with a specific verb and resource, and distinguishes it from sibling tools by focusing on skill bundles rather than flows or connections. It also names example bundles and specifies the return content (description and member tool names), leaving no ambiguity about its function.

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 provides a usage workflow: 'Call this first when you are unsure which tools apply to a request; then call tool_search with query: "skill:<name>" to load the full bundle.' This not only tells when to use the tool but also references the alternative (tool_search) and gives the exact follow-up call, making the usage context crystal 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?

With readOnlyHint=true already providing safety information, the description adds context about the Pro+ plan requirement and the fact that data comes from a cache (implying potential staleness). This is useful behavioral context beyond the annotation, though it does not detail return format or pagination.

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

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

The description is a single, front-loaded sentence that conveys the essential information (action, resource, source, plan requirement) without any waste. Every word contributes.

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 provides sufficient context: what it lists, the source (cache), and a prerequisite (Pro+ plan). Since no output schema exists, the lack of return details is acceptable for this simple tool.

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

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

The input schema has zero parameters, so the baseline is 4. The description does not need to add parameter information, and it correctly focuses on the tool's purpose and source.

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

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

The description clearly states the action (list), the resource (Power Platform connections), the scope (all), and the data source (Power Clarity cache). It distinguishes itself from the sibling tool list_live_connections by specifying the cache, making the purpose unambiguous.

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

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

The description implies usage for cached connection data and notes a Pro+ plan requirement, but does not explicitly state when to use this tool versus alternatives like list_live_connections. The guidance is implied rather than explicit.

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

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

The description adds the Pro+ plan requirement and the fact that data is sourced from a cache, which goes beyond the readOnlyHint annotation. This informs the agent about potential data staleness and access restrictions, providing useful behavioral context beyond the structured annotation.

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

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

The description is extremely concise: a bracket-flag for the plan requirement followed by a one-sentence action. It is front-loaded with the key constraint and contains no fluff or 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?

For a simple, parameterless list tool with no output schema, the description covers the essential purpose and a critical prerequisite. It could potentially mention return format or staleness implications, but the word 'cache' already hints at that. Overall, it is sufficiently complete given the tool's simplicity.

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

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

The tool has zero parameters, so the input schema is trivially covered. The baseline for zero-parameter tools is 4, and the description does not need to add any parameter semantics. It appropriately focuses on the operation and data source.

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

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

The description clearly states the action ('List all'), the resource ('Power Platform environments'), and the specific data source ('from the Power Clarity cache'). This distinguishes it from sibling tools like list_live_environments, which likely list live environments. The verb and resource are specific 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?

The description provides context by indicating the data comes from the Power Clarity cache, which implies this tool is for cached/offline environments rather than live ones. It also notes the Pro+ plan requirement. However, it does not explicitly mention alternatives or when not to use this tool, so it stops short of full guidance.

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

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

The annotation readOnlyHint=true already establishes the safety profile. The description adds meaningful behavioral context: data is from a stored snapshot rather than live, the Pro+ plan requirement, and what key fields are returned (trigger URL, state, run failure rate). This goes beyond the annotation without contradicting it.

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 sentences, each with a specific purpose: stating the core function and plan requirement, summarizing filters and return fields, and clarifying the data source. No filler or redundancy. Front-loaded with the primary action.

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 there is no output schema, the description appropriately highlights the return fields (trigger URL, state, run failure rate). It covers the essential behaviors: cached data, optional filters, and plan requirement. Minor omissions like pagination or error behavior are not critical for a simple list tool with optional filters.

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 a small layer of meaning by grouping the boolean parameters as "governance flags (monitor, notification rules)", which is not fully obvious from the individual schema descriptions. It does not provide syntax examples or further parameter-specific details.

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

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

The description states a specific verb and resource: "List Power Automate flows from the Power Clarity cache." It clearly distinguishes itself from sibling live-flow tools by emphasizing the cached snapshot source and explicitly noting data is "not live from 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 provides clear context for when to use this tool: it requires a Pro+ plan and accesses cached data. It implicitly contrasts with live API tools by stating data is "not live from the Power Automate API," which signals that live-data needs should use a different tool, though it does not name an alternative explicitly.

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 readOnlyHint annotation already indicates a safe read operation. The description adds value by noting the data source ('Power Clarity cache'), implying cached data rather than live data, and the Pro+ plan requirement. These are behavioral details not present in 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, front-loaded sentence that leads with the licensing requirement and then clearly states the function. It is concise, with no filler or redundant phrasing.

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

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

For a zero-parameter read-only tool with no output schema, the description is sufficiently complete. It names the entity, the source (cache), and the scope ('all'). It could potentially describe the return format, but that is unnecessary for a simple list operation and there are no nested objects or outputs to detail.

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, so there is no schema to explain. The description adds no parameter information, but the baseline for 0 parameters is 4, and the description correctly focuses on the tool's operation rather than non-existent inputs.

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

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

The description clearly states the tool's action ('List'), the resource ('makers'), and the scope ('all'), with a parenthetical clarifying that makers are 'citizen developers / AAD users'. This distinguishes it from the singular sibling tool 'get_store_maker' and other list tools.

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

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

The description provides clear context: it lists all makers and requires a Pro+ plan. It does not explicitly mention alternatives or when not to use it, but the zero-parameter design and 'all' scope make its usage straightforward. The license requirement adds a relevant precondition.

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 the description adds useful behavioral context: it reads from the 'Power Clarity cache' (implying potential staleness) and has a plan requirement. It does not describe cache refresh behavior or return details, but the added information goes 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 sentence with no wasted words. It front-loads the requirement, then clearly states the action and resource. Every element ('Requires Pro+ plan', 'List all Power Apps canvas apps', 'from the Power Clarity cache') contributes essential information.

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

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

For a simple list tool with zero parameters, a readOnly annotation, and no output schema, the description is sufficiently complete: it states the source (cache), the scope (all), and the access requirement. It does not describe return fields, but given the simplicity and lack of output schema, this is a minor gap rather than a critical omission.

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 coverage is 100% (empty schema). The description clarifies that it lists 'all' apps, which conveys the lack of filtering. This adds meaning beyond the empty schema, aligning with the baseline for parameterless tools and earning a slight increase.

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

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

The description clearly states the tool's function with a specific verb and resource: 'List all Power Apps canvas apps from the Power Clarity cache.' It distinguishes itself from sibling list tools by specifying the resource type (Power Apps canvas apps) and the source (cache), making it 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 implies usage—it is for listing all Power Apps canvas apps—but does not explicitly provide when-to-use guidance or mention alternatives. The requirement 'Requires Pro+ plan' is a prerequisite, not a usage exclusion. While the context is clear, it lacks explicit direction compared to tools that name alternative tools for different scenarios.

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

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

Adds useful behavioral traits: the tool supports reporting, appending evidence, and checking reports, and remains accessible after quota. The security constraint about excluding secrets is also disclosed. However, it doesn't mention response format, persistence of reports, or rate limits. Annotations (readOnlyHint=false, destructiveHint=false) are consistent, so no contradiction.

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

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

Two sentences, no unnecessary verbosity. The first sentence covers the core functions, and the second adds a safety constraint. Well front-loaded and efficient.

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

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

A complex tool with 17 parameters, no output schema, and no parameter descriptions demands a much more thorough description. The existing text gives an overview but doesn't explain parameter semantics, action-specific workflows, or expected results, leaving significant gaps for the agent.

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

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

The schema has 17 parameters with 0% description coverage, so the description must compensate. It only hints at the 'action' parameter (report, append, status, list) and content-related constraints. Parameters like chunk, notify, ticket, category, severity, include_diagnostics, and others are left completely unexplained, making it hard to invoke correctly.

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 explicitly states 'Report a Flow Studio MCP bug or missing capability, append text evidence, or check your reports' – clear verbs and resources that cover the tool's main actions. It is clearly distinct from all sibling tools, which are about flow and connector management.

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 practical context: 'Free and available even after quota is reached' tells when to use, and the warning 'Do not include passwords...' sets content expectations. There is no mention of alternatives since this is a unique reporting tool, but the usage context is clear.

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

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

The description adds useful behavioral context beyond the annotations, such as automatic trigger name discovery and payload reuse. It also indicates this is a write operation but not destructive, consistent with the annotations. However, it doesn't disclose whether resubmission creates a new run or modifies the existing one, leaving some ambiguity.

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 front-loaded, with two sentences that efficiently convey the action, scope, and a key automation detail. No redundant information 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 tool with three clearly documented parameters, no output schema, and straightforward semantics, the description is largely complete. It provides the essential action, target, and auto-discovery behavior. It could mention the return value, but this is not critical for a resubmit action.

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 each parameter already having a clear description. The tool description adds minimal semantic value for the parameters, only noting that no trigger name parameter is needed, which is unrelated to the existing three parameters. 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 the tool's specific purpose: resubmitting a failed or cancelled Power Automate flow run via the live PA API. It identifies the exact resource (flow run) and action (resubmit), and distinguishes itself from sibling tools like cancel_live_flow_run and trigger_live_flow.

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

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

The description specifies the intended use case: resubmitting failed or cancelled runs, and clarifies that it re-uses the original trigger payload. While it doesn't explicitly contrast with alternatives like trigger_live_flow, the context is clear enough for an agent to infer when this tool is appropriate.

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

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

The description adds behavior beyond annotations by noting it 'Reads the current flow state first and only issues the start/stop call if a state change is actually needed,' which explains its idempotent behavior. It also discloses the return values (flow name, environment, requested state, actual state) despite no output schema. This supplements the annotations effectively.

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 sentences, front-loaded with the core action, and each sentence adds useful context without waste.

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

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

For a 3-parameter tool with no output schema, the description covers the operation, scope, idempotent behavior, and return values, which is quite complete. It lacks explicit error handling or alternative paths, but the core use case is well covered.

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 has 100% coverage with descriptions for each parameter. The description does not add significant new parameter-specific detail beyond affirming the schema, so baseline 3 is appropriate.

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

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

The description clearly states the tool's function: 'Start or stop a Power Automate flow via the live Power Automate API using an impersonated service account.' It distinguishes itself from sibling tools like set_store_flow_state by specifying live API and no workspace requirement.

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 context that it works without a Power Clarity workspace and for any flow the impersonated account can access, which helps determine when to use it. However, it does not explicitly name alternative tools or state when not to use it, so it stops short of full guidelines.

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?

Description adds beyond annotations: mentions impersonation via a cached service account, return value, and that it persists state. It complements the destructiveHint and readOnlyHint=false annotations. Slight gap: no detail on failure modes or side effects beyond persistence.

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

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

Two compact sentences with high-value flags (Pro+, deprecated, impersonation) front-loaded. No redundant or filler content; every word contributes essential information.

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

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

For a deprecated tool, it includes crucial context: plan requirement, replacement, action, return type. Missing little except perhaps why it's deprecated or details on errors, but overall sufficient for an agent to decide 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?

Input schema has 100% coverage with descriptions for all three parameters. The description adds no extra parameter-level meaning, so a 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?

Description clearly states the tool's function: start or stop a Power Automate flow and persist the state to the store. It distinguishes itself from the sibling set_live_flow_state by explicitly naming it as the replacement, making the purpose unambiguous.

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

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

Explicitly directs users to 'Use set_live_flow_state instead' and marks the tool as deprecated, providing strong guidance on when not to use this tool and which alternative to choose. Also notes the Pro+ plan 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?

The readOnlyHint annotation is present, and the description adds meaningful context: it is non-billable, returns full JSON schemas, and uses ranked keyword matching. This goes beyond the annotation, though it doesn't cover all edge behaviors like no-results handling.

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

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

Front-loaded with a strong preference instruction, followed by purpose, usage conditions, and query forms. Each sentence serves a distinct purpose and the structure is logical, with no wasted words.

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

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

The description is complete for a meta-search tool: it explains what it does, when to use it, the query forms, the return value (full JSON schemas), and the non-billable aspect. Despite no output schema, the description adequately specifies the return format.

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 detailed descriptions for both query and max_results, including the query forms and max_results behavior. The description adds example queries and skill bundle names, but the schema already covers the essential parameter semantics, so extra meaning is marginal.

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

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

The description clearly states the tool searches Flow Studio MCP tools by keyword, skill bundle, or explicit selector and returns full JSON schemas. It distinguishes itself from siblings by explicitly instructing 'PREFER THIS over guessing tool names' and listing specific query forms.

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 call this whenever uncertain about functionality, or to load a whole skill bundle. It also directs to use list_skills first for skill queries, providing clear when-to-use guidance and referencing 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 indicate destructiveHint=true, and the description elaborates with the mechanism: fetches the signed URL via listCallbackUrl then POSTs the body, and includes auth automatically. This adds valuable context about how the mutation occurs. It does not contradict annotations and provides more depth than the bare destructive hint.

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

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

The description is four sentences with clear structure: purpose, mechanism, auth handling, return values, and a constraint. No redundant text; 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?

The tool has no output schema, but the description enumerates the return values (HTTP status, response body, requiresAadAuth flag, authType). It also explains the trigger type restriction and auth behavior. It doesn't cover error handling or potential side effects in depth, but it's sufficient for an agent to understand the tool's operation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description only minimally connects the body parameter to the POST action; it doesn't add new parameter-level information beyond what the schema already provides.

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

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

The description clearly states the tool triggers an HTTP-triggered Power Automate flow via its callback URL, using a specific verb and resource. It also distinguishes itself by specifying 'Only works for flows with a Request (HTTP) trigger type', separating it from siblings like get_live_flow_trigger_url which merely fetches the URL.

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

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

The description gives clear context on when to use it (for HTTP-triggered flows) and excludes other trigger types. It also notes that AAD auth is handled automatically, which is a usage condition. However, it does not explicitly name alternative tools for non-HTTP flows or for merely retrieving the trigger URL.

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

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

The description adds substantial behavioral context beyond the annotations: it mentions using an environment admin account, generating a GUID for new flows, appending '#flowstudio-mcp' to the description, mirroring displayName changes to the cache, and the exact semantics of surgical operations (set/add/remove/merge with errors on existing/new keys). These details go well beyond the readOnlyHint/idempotentHint/destructiveHint annotations, which it does not contradict.

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, front-loading the primary purpose and then systematically explaining creation, update, surgical edit, dryRun, cache sync, and whole-definition updates. Every sentence provides actionable information without fluff, making the density appropriate for the tool's complexity.

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 is comprehensive, covering all main behaviors, prerequisites (get_live_flow), edge cases (blank flowName, literal slashes), and the dryRun preview. However, it does not explicitly describe the return value format for normal update/create calls (only dryRun mentions returning the result and what changed), which is a minor gap since no output schema is provided to fill that void.

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 description coverage is 100%, the description enriches parameter semantics significantly. It clarifies that definition must be a parsed object (not stringified), that path must be an array of literal keys with literal slashes (not a slash-delimited string), and that operations cannot be combined with definition. It also explains the structure of connectionReferences and the conditional requirements for displayName and definition during creation.

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

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

The description clearly states the tool's purpose: 'Update or create a Power Automate flow via the live PA API.' It specifies the verb (update/create), the resource (Power Automate flow), and the scope (live PA API), and distinguishes between creation and update based on flowName. This sets it apart from sibling read tools like get_live_flow and store tools like update_store_flow.

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

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

The description provides explicit usage guidance for different scenarios: omit flowName to create, provide flowName to PATCH, use operations for surgical edits, and follow a get_live_flow → mutate → pass process for wholesale definition changes. It also warns against combining operations with definition and describes the dryRun preview option, giving clear when-to-use and when-not-to-use instructions.

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

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

The description discloses key behavioral traits beyond annotations: it requires a paid plan, writes to the cache rather than calling the Power Automate API, and updates only provided fields. These are non-obvious and crucial for an agent to set expectations. The idempotentHint and non-destructive annotations align, and no contradiction exists.

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 (three sentences), front-loaded with the plan requirement, and each sentence adds unique value: purpose, merge semantics, and cache behavior. No superfluous 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?

For a 18-parameter tool with no output schema, the description covers the critical context: purpose, prerequisites, merge behavior, and side-effects. It does not mention return value or error conditions, but these are less critical for an update operation and the schema covers required parameters.

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

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

With only 33% schema coverage, the description partially compensates by listing example field categories (business impact, owner team, tags, monitor flag, notification settings). However, it does not explain most individual parameters, and the meaning of fields like 'tier', 'security', and 'rule_notify_onmissingdays' remains unclear.

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

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

The description clearly states the tool's purpose: 'Update governance/metadata fields on a flow record in the Power Clarity store' and provides specific examples of fields (description, business impact, owner team, tags, etc.). It also distinguishes from siblings by noting 'Writes to the cache — does not call the Power Automate API', which separates it from 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 gives clear usage context: it requires a Pro+ plan, explains merge semantics ('Only fields provided are updated'), and indicates it targets stored flows rather than live Power Automate flows. However, it does not explicitly state 'use this instead of update_live_flow when...', so a direct alternative comparison is missing.

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