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

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

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

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

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

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

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

Given the tool has no output schema, the description still explains what the return value contains (failedActions and remediation hint). It fully covers the operational context (cached vs live), the deprecation status, and the recommended replacement. Nothing an agent needs for correct invocation is missing.

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

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

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

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

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

The description clearly identifies the verb ('get'), resource ('cached failed run history for a flow from the Power Clarity store') and scope, distinguishing it from get_store_flow_runs and get_live_flow_runs. It also specifies that this is a convenience wrapper around get_store_flow_runs with status=Failed, making its purpose unambiguous.

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

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

The description explicitly says the tool is deprecated and directs users to use get_live_flow_runs and filter by status=Failed instead. It also clarifies that the data is from a stored snapshot, not live from the Power Automate API, giving clear when-to-use and when-not-to-use guidance.

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