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

Beyond the destructiveHint annotation, the description warns that the Microsoft endpoint is unofficial and unsupported, adding important risk context. It also discloses the PUT method and the disabled-by-default status, which are behavioral traits not captured by 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 first sentence is concise and information-dense, but the subsequent parameter enumeration duplicates the input schema. It is not overly verbose, but not every sentence adds unique value for an agent that already sees the schema.

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

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

For a mutation tool with full schema coverage, the description provides essential operational context: the unofficial endpoint, the disabled flag, and the required parameters. It does not explain return values, but no output schema exists and the focus is on invocation, which is adequately 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 covers all four parameters with descriptions and enums, so the baseline is 3. The description mostly repeats the schema's parameter list without adding new semantic detail, such as format constraints or examples 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 begins with 'Grant a principal a role on a flow', a specific verb and resource that clearly distinguishes this from sibling tools like list_flow_owners and remove_flow_owner. The HTTP method and parameter list further reinforce the intended action.

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

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

It clearly states that the tool grants a role to a principal on a flow and lists required parameters. It also provides the prerequisite about ENABLE_WRITE_OPS. However, it does not explicitly mention alternatives or when not to use it, so it stops short of full exclusion guidance.

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

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

Annotations already include destructiveHint=true, and the description adds valuable context: it uses an unofficial Microsoft endpoint labeled unsupported, with behavior that may change. This exceeds the annotation by warning about stability and support, helping the agent manage expectations.

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

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

The description is compact and front-loaded with the action. It includes the endpoint, required flag, parameter list, and a warning—all essential. The parameter list is slightly redundant with the schema, but the overall structure is efficient and not bloated.

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, the description covers the essentials: what it does, the endpoint, how to enable it, parameter guidance, and a stability warning. It does not describe return values, but no output schema exists, and the operation is straightforward. The main gap is lack of explicit permission requirements, but that is common across siblings.

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 documented (e.g., 'Run id (from list_flow_runs)'). The description merely restates parameter names and required/optional status without adding new semantics, so it does not elevate beyond the schema 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 clearly states the tool's purpose: 'Cancel an in-progress run'. It uses a specific verb ('cancel') and resource ('run'), and includes the endpoint for precision. This distinguishes it from sibling tools like resubmit_flow_run or delete_flow.

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

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

The description provides clear context for when to use the tool (on in-progress runs) and notes that it is disabled by default with a required flag. It does not explicitly mention alternatives or exclusions, but the context is sufficiently clear for an agent to decide when cancellation 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 discloses important behavioral traits beyond the destructiveHint annotation: the tool is disabled unless ENABLE_WRITE_OPS=true, it uses an unofficial Microsoft endpoint that may change, and it returns the created flow. It does not contradict the destructiveHint 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 organized: purpose first, then parameter summary, then usage tips, then a caveat about the unofficial endpoint. Though the parameter line duplicates schema details, it's useful for quick reference and the entire description stays under 150 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?

With no output schema, the description explains the return value ('Returns the created flow'). It also covers the disabled-by-default behavior, the unofficial nature of the API, and provides practical authoring guidance. For a complex create operation with 5 parameters, this is highly 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 input schema already documents all 5 parameters with descriptions (100% coverage), so the description only needs to add extra meaning. It adds guidance that the definition JSON includes $schema/triggers/actions, and explicitly warns that authoring a valid definition is non-trivial, recommending get_flow as a template. This adds value beyond the schema.

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

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

The description clearly states 'Create a new cloud flow from a workflow definition', using the specific verb 'create' and the resource 'cloud flow'. It also identifies the HTTP operation (POST .../flows), distinguishing creation from sibling tools like update_flow or delete_flow.

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

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

It provides clear usage context: creating flows requires a workflow definition, and suggests using get_flow on an existing flow as a template for authoring a valid definition. It also notes connection-dependent actions need matching connectionReferences, but doesn't explicitly state when not to use this tool or name alternatives for updating/deleting.

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 destructiveHint annotation, the description discloses irreversibility, the need for a confirm flag, the default-disabled state, and reliance on an unofficial Microsoft endpoint whose behavior may change. This significantly enriches the agent's understanding of the tool's behavior and risks.

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

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

Three concise sentences deliver purpose, safety requirements, and reliability caveats with no filler. The structure is front-loaded and every sentence earns its place.

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

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

Given the destructive nature, the description covers critical context: irreversibility, confirm requirement, disabled-by-default, and unofficial endpoint. It omits explicit return-value or error details, but for a simple delete tool this is not a major gap, especially with the destructiveHint annotation present.

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

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

The schema descriptions cover 100% of parameters with meaningful information. The description restates parameter names and requiredness but adds no new parameter-level meaning beyond what the schema already provides, 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 opens with 'Permanently delete a flow' and explicitly shows the HTTP DELETE endpoint, giving a specific verb and resource. It clearly distinguishes this from non-destructive operations like disable_flow by emphasizing 'permanently'.

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 for when to use: for permanent deletion, with a confirm guard to prevent accidents, and notes the tool is disabled by default, requiring ENABLE_WRITE_OPS=true. However, it does not explicitly name an alternative like disable_flow for temporary deactivation, 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?

While destructiveHint already communicates the mutation risk, the description adds valuable context about the unofficial, unsupported API endpoint and potential behavior changes. It also suggests a verification method, going 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 compact and front-loaded with the core action. The bracketed configuration note ([DISABLED: set ENABLE_WRITE_OPS=true]) adds necessary context but slightly clutters the flow; otherwise each sentence earns its place.

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

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

For a two-parameter tool with no output schema, the description covers the action, key parameters, verification step, and a notable risk caveat. It lacks response format details, but that is not required given the absence of an output schema.

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

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

Schema coverage is 100% for both parameters, so the description does not need to add parameter details. It briefly restates the parameters and their optionality but adds no additional semantic value beyond the schema.

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

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

The description opens with 'Turn a flow off' which is a specific verb+resource action, clearly distinguishing it from enable or delete operations. It also references the POST .../stop endpoint, adding precision.

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

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

Provides a verification step ('Verify with get_flow') and notes environment optionality, but gives no explicit guidance on when to use this tool versus alternatives like enable_flow or delete_flow. The usage context is implied but not fully 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?

Adds significant behavioral disclosure beyond annotations by stating the tool uses Microsoft's unofficial and unsupported api.flow.microsoft.com endpoint, warning that behavior may change. It also notes the ENABLE_WRITE_OPS=true flag requirement. This is consistent with destructiveHint=true and provides useful risk context.

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

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

The description is compact and information-dense, covering purpose, parameters, verification, and a caveat in a few short sentences. Slight structural inefficiency exists with the bracketed [DISABLED] note interrupting the flow, but overall every sentence earns its place.

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

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

For a two-parameter mutation tool with no output schema, the description adequately covers what the tool does, how to verify success, and a critical risk. It could mention permissions or side effects, but the verification step and endpoint warning fill most gaps.

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

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

The input schema already documents both parameters fully (flow GUID, environment id, with 100% coverage). The description only repeats that flow is required and environment is optional, adding no new semantic detail, so the baseline score of 3 is appropriate.

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

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

The description explicitly states 'Turn a flow on' and identifies the exact endpoint (POST .../start), making the tool's function unambiguous. It clearly distinguishes from the sibling disable_flow by indicating the opposite action.

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

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

Provides contextual guidance by instructing to verify with get_flow (state -> Started), which implies the appropriate after-action. It does not explicitly discuss when to avoid using it or compare with alternatives, but the enables/disables sibling pair makes the use case sufficiently 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?

Beyond the readOnlyHint annotation, the description discloses a critical behavioral trait: it uses Microsoft's unofficial endpoint that is labeled unsupported and may change. It also enumerates the full set of returned fields, giving the agent a clear expectation of the operation's safety and output. No contradictions with annotations.

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

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

The description is compact: three sentences covering purpose, parameters, and a usage caveat, followed by an example. Every sentence contributes meaningful information, and the most important content is front-loaded.

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

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

With no output schema, the description compensates by listing exactly what is returned (state, timestamps, owner, definition JSON, connectionReferences, parsed trigger/action names). It also covers the key caveat about the unsupported endpoint and includes a usage example. For a read-only tool with good annotations, this is fully complete.

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

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

Schema coverage is 100%, so the schema already documents both parameters. The description restates that flow is a required GUID and environment is optional, but this adds little beyond the schema's own descriptions. It does not provide additional format constraints or cross-parameter relationships, so the baseline 3 is appropriate.

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

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

The description uses a specific verb ('Get') and identifies the resource ('full definition of one flow'), then enumerates exactly what is included: state, timestamps, owner, workflow definition JSON, connectionReferences, and parsed trigger/action names. This clearly distinguishes it from siblings like list_flows (which lists flows) and get_flow_run (which targets run details).

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

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

The description explains the required parameter (flow GUID from list_flows) and optional environment, and provides an example invocation. It implies usage after listing flows, but does not explicitly contrast with alternative tools or state when not to use it. The context is clear enough for an agent to select it appropriately.

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 warns that it uses Microsoft's unofficial api.flow.microsoft.com endpoint, labels it unsupported, and cautions that behavior may change. It also explains that original run properties are under `raw` and that per-action breakdown appears only when the API provides it, adding valuable context not captured 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?

Four concise sentences, front-loaded with the primary purpose, then a useful output note, parameter summary, and example. No filler or redundancy.

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

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

Despite the lack of an output schema, the description covers key return fields, parameter requirements, an example invocation, and a critical unsupported-endpoint caveat. It adequately prepares the agent for debugging a run, though a little more on response structure would make it fully complete.

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

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

Schema coverage is 100% with each parameter already described (e.g., 'Omit to use the user's default environment'). The description reiterates the parameters but adds little new meaning, with the exception of a usage example. Per the rubric, high schema coverage yields a baseline of 3.

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

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

The description clearly states the tool's function: 'Get one run in detail for debugging' and lists specific outputs (status, timing, triggering action, first-failure error). It differentiates from siblings like list_flow_runs (which lists runs) and get_flow (which retrieves flow details).

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 'for debugging' offers clear context for when to use the tool, and parameter provenance ('from list_flow_runs', 'from list_flows') indicates dependencies. However, it does not explicitly mention alternative tools or when not to use it, so it stops short of full exclusion guidance.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is known. The description adds context by enumerating the type of data returned (name, version, build commit, runtime, capability counts), which is useful beyond the annotation. It does not mention rate limits or auth, but for a simple read-only info tool this is sufficient.

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

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

The description is a single, well-structured sentence that leads with the action and then lists specifics. Every word earns its place, with 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?

This is a simple, no-parameter tool with no output schema. The description gives a complete picture of what the tool does and what it returns, making it unnecessary to elaborate further. The return fields are listed, so the agent can anticipate the response.

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 parameter semantics are trivial. Baseline for 0 params is 4. The description adds context about what the tool returns, which is the only relevant semantic information.

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: 'Returns identity and build information for this server.' It uses a specific verb ('returns') and identifies the resource (server info). It also lists specific components (name, version, build commit, runtime, capability counts), making it distinct from sibling tools that manage flows.

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 context: when you need server identity/build info. The sibling tools are all flow operations, so the purpose is clear without explicit alternatives. Although it doesn't state exclusions or when-not-to-use, the context is unambiguous for an info endpoint.

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

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

Annotations provide readOnlyHint, but the description adds valuable behavioral context: the exact return array shape, the meaning of 'status', and the warning that the endpoint is unofficial/unsupported and behavior may change. This goes beyond the structured data.

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

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

The description is structured with clear sections: purpose, return format, status explanation, parameter note, endpoint warning, and example. It is slightly verbose (e.g., the parameter line is redundant), but the warning and example earn their 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?

Given the tool's simplicity (one optional parameter, no output schema), the description covers everything needed: purpose, return value, status semantics, parameter guidance, reliability caveat, and a usage example. No critical information is missing.

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

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

Schema coverage is 100% and already fully describes the 'environment' parameter. The description merely restates 'environment (optional)' and an example call, adding no new semantic information 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 states a specific action on a specific resource: 'List the connections (API connectors) in an environment and their health.' It clearly distinguishes from sibling list tools (list_environments, list_flows) by specifying connections and health.

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

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

Provides clear context for when to use: the explanation 'A status other than "Connected" indicates a broken/expired connection — a common cause of silently failing flows' implies diagnostic use. It does not explicitly name alternatives or when-not-to-use, but the context is strong enough for a simple tool.

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

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

Beyond the readOnlyHint annotation, the description discloses that it uses Microsoft's unofficial api.flow.microsoft.com endpoint, which may change behavior. It also specifies the output fields and the meaning of isDefault, adding valuable operational context.

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

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

The description is concise, with the main purpose in the first sentence, followed by return details and a warning about API stability. The example usage is compact and helpful without redundancy.

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

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

Given the tool's simplicity (no parameters, no output schema), the description covers all relevant aspects: what it returns, what the default environment means, and the unofficial API caveat. It is sufficient 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?

The tool has zero parameters, which earns a baseline of 4. The description explicitly states 'Parameters: none' but this is already apparent from the schema, so no additional semantic value is added.

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 the verb 'List' with a specific resource ('Power Automate environments') and clarifies scope ('visible to the signed-in user'). It also specifies the return shape, distinguishing it from other list tools for flows and connections.

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

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

The description explains that the tool returns the user's default environment and notes that other tools use this when `environment` is omitted, giving a clear use case. It does not name alternative tools explicitly, but the resource focus makes the context clear enough.

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 the tool uses Microsoft's unofficial api.flow.microsoft.com endpoint, which is unsupported and may change behavior. This is critical risk information that adds significant value and goes well beyond what annotations 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 well-structured: it opens with the primary purpose, then summarizes return format, parameters, a critical caveat, and an example. Every sentence serves a clear informational role 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?

For a relatively simple listing tool, the description covers the required aspects comprehensively: purpose, return structure, parameters, usage example, and a notable behavioral risk. The absence of an output schema is compensated by the explicit return array description, and no 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% for both parameters, so the baseline is 3. The description adds a practical example ('list_flow_owners { "flow": "<guid>" }') and reiterates the flow parameter's origin from list_flows, which clarifies usage beyond the schema's static text.

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

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

The description states a specific verb and resource: 'List the owners/permissions on a flow.' This clearly distinguishes the tool from sibling operations like add_flow_owner and remove_flow_owner by focusing on the read-only listing action.

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

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

The description communicates the clear context for use (listing owners/permissions on a flow) and provides a concrete example. It does not explicitly name alternatives or exclusions, but its read-only nature and the presence of sibling tools imply appropriate usage, meeting the 'clear context, no exclusions' threshold.

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

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

Annotations already indicate readOnlyHint=true, and the description adds a valuable disclosure that the tool uses Microsoft's unofficial api.flow.microsoft.com endpoint, which is unsupported and may change behavior. This is beyond what annotations 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 structured with purpose, return type, parameters, caveat, and example. It is longer than minimal but every section adds value, with the caveat and example being useful.

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

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

No output schema exists, but the description explains the return array format and fields. It also includes parameter details, an example, and a stability warning, making it complete for a read-only listing tool.

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

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

Schema description coverage is 100%, so baseline is 3. The description reiterates parameter details (defaults, enums) already in the schema but does not add new meaning beyond providing a usage example.

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

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

The description states 'List recent runs of a flow, newest first,' which is a specific verb+resource. It clearly distinguishes from siblings like get_flow_run by mentioning that the returned `name` is the run id used by get_flow_run.

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

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

The description implies usage by showing an example and referencing get_flow_run, but it does not explicitly state when to use this tool versus alternatives or when not to use it. The context is clear but exclusions/alternatives are not directly addressed.

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

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

Annotations declare readOnlyHint=true, and the description aligns with that by framing the action as inventory/list. It adds important context beyond annotations by revealing the unofficial, unsupported endpoint and warning that behavior may change. It also details the return structure and state values, though it does not cover pagination or error conditions.

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

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

The description is well-organized in short, labeled segments (purpose, usage, returns, parameters, caveat, example). Every sentence adds distinct value—from the 'START HERE' directive to the unofficial endpoint warning—without redundancy. It is appropriately sized 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?

With no output schema, the description takes on the responsibility of explaining return values, and it does so clearly (array of fields, GUID meaning, state values). It also covers usage context, parameter behavior, example call, and a stability caveat. This is complete for a simple read-only list tool with two optional 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?

Schema coverage is 100%, so the baseline is 3. The description adds minimal value over the schema for parameters themselves: it repeats 'environment (optional)' and 'owner (optional — filter by creator userId/email)' almost exactly as the schema descriptions. It does clarify that 'name' in the output is the flow GUID, but that is output rather than parameter 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 uses specific verbs 'List / enumerate' and clearly identifies the resource ('all cloud flows in an environment') and the key outcome (returning flow GUIDs). It distinguishes itself from siblings by stating it is the only tool that produces flow GUIDs, making its purpose unambiguous.

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

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

The description explicitly instructs 'START HERE to discover flows' and explains that every per-flow tool needs a GUID that only this tool produces. It also names the sibling tools that depend on this output, providing strong when-to-use guidance and creating a clear workflow.

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 destructiveHint annotation, the description discloses that the tool uses an unofficial, unsupported Microsoft endpoint, behavior may change, and it requires setting ENABLE_WRITE_OPS=true. These are critical behavioral traits not captured by the structured annotations.

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

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

The description is highly efficient: it leads with the action, includes the HTTP method and endpoint, notes the disabled state, lists parameters, and warns about the unsupported API—all in two compact sentences without unnecessary 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 simple permission-revocation tool, the description covers the essential context: what it does, the endpoint, required parameters, the disabled flag, and the risk of the unsupported API. It doesn't describe the return value, but no output schema exists, and the behavior is straightforward enough that this omission is acceptable.

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

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

Schema description coverage is 100% (all three parameters are described in the schema). The description reiterates the parameter names and required/optional status but adds no additional semantic detail 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 uses a specific verb ('Revoke') and resource ('a principal's access to a flow'), clearly distinguishing it from siblings like delete_flow (which deletes the flow itself) and add_flow_owner (which grants access).

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 through the verb 'Revoke' and mentions it is disabled by default, but doesn't explicitly contrast it with alternatives or state when not to use it. It gives context about the unsupported endpoint, which serves as a caution, but no formal 'use this instead of X' guidance.

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

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

The description adds important behavioral context beyond annotations by warning that all input may be public and that redaction is best-effort. It also lists categories of prohibited data, which is valuable for safe use. It doesn't cover every side effect, but the privacy implications are well disclosed.

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

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

The description is efficient: a purpose sentence, a brief bulleted list of prohibitions, and a one-line redaction caveat. Every part contributes directly to safe usage and readability.

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 lack of an output schema, it might ideally mention what the user can expect after submission, but the combination of schema details and safety warnings is sufficient for selecting and invoking the tool correctly. The description fully covers the public-content risk and parameter constraints.

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% parameter coverage, including descriptions, enums, and constraints. The description reinforces the public-safety requirement but doesn't add substantive semantics 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 opens with 'Submit a feedback report or issue to this server's maintainers,' using a specific verb and resource. This clearly distinguishes it from the sibling flow and connection management tools.

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

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

It clearly establishes when to use the tool (feedback reports/issues to maintainers) and provides context about public content. It doesn't explicitly name alternatives, but none of the sibling tools are similar, so exclusions are not necessary.

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

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

The description discloses that it uses an unofficial, unsupported Microsoft endpoint that may change behavior, and that the tool is disabled by default. These are important behavioral traits beyond the destructiveHint annotation, adding genuine value.

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

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

The description is concise and information-dense, with a clear front-loaded action, HTTP endpoint, disabled flag, and parameter summary. Every sentence serves a purpose and there is no 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 write operation with no output schema, the description covers the essential invocation details: parameter sources, disabled status, and API instability. However, it does not describe side effects (e.g., what happens to the original run) or return behavior, leaving some ambiguity.

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 detailed descriptions for all four parameters, including provenance (e.g., 'from list_flow_runs'). The description merely repeats this information without adding new semantic meaning, so the baseline of 3 for full schema coverage 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 starts with 'Resubmit (replay) a run from its trigger', which clearly states the specific action and target. This distinguishes it from sibling tools like cancel_flow_run or get_flow_run by focusing on replaying an existing run.

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

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

The description provides clear context for when to use this tool (to resubmit/replay a run from its trigger) and includes a prerequisite (ENABLE_WRITE_OPS=true). However, it does not explicitly mention alternatives or when not to use it, 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?

Discloses key behavioral traits beyond the destructiveHint annotation: the PATCH partial-update semantics ('only the fields you pass'), the requirement to pass the full workflow definition for logic edits, and the critical caveat that the API is unofficial, unsupported by Microsoft, and behavior may change. This is rich, valuable context.

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

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

Four compact sentences, each serving a purpose: operation + endpoint, parameter overview, safety workflow, and unsupported API warning. The parameter list is somewhat redundant with the schema but provides a quick summary. No fluff, though it could be slightly tighter.

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 mutation tool with no output schema, the description covers the essential aspects: the core operation, partial update behavior, safe modification workflow, and the unsupported/unofficial nature of the API. It is fully contextual 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 baseline is 3. The description adds meaning by explaining that the definition expects the full workflow JSON and advising to pass the whole definition back after modifying the get_flow output. It also clarifies the optional environment default and partial-update semantics, which are not explicitly 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?

Description clearly states 'Update an existing flow's properties' with the specific PATCH endpoint and method (PATCH .../flows/{flow}), making it distinct from siblings like create_flow, delete_flow, enable_flow, etc. The verb-resource relationship is explicit.

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 guidance for safe use: 'To edit logic safely: get_flow first, modify the returned definition, then pass the whole definition back here.' Also notes the disabled flag (ENABLE_WRITE_OPS=true). However, it does not explicitly differentiate when to use update_flow vs enable_flow/disable_flow for state changes, though sibling names imply the distinction.

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