copilot-studio-friction-index

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

Annotations already provide readOnlyHint and openWorldHint. The description adds valuable behavioral context: records filtered by status (open/regressed), ordered by newest change, and including health counts. 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?

A single sentence that is front-loaded with the core question and provides necessary details. It is concise but somewhat dense, earning a 4.

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 sufficiently explains the return content (records with status, ordering, health counts) for a read-only, zero-parameter 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?

No parameters exist, and schema coverage is 100%. According to guidelines, 0 parameters warrants a baseline of 4, and the description adds no parameter info as none is needed.

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

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

The description clearly states it retrieves 'what is currently broken or regressed' with specific details on status and health counts, distinguishing it from siblings like get_friction_record and search_frictions.

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 an overview of current issues but does not explicitly state when to use this tool versus alternatives like search_frictions for broader searches or get_friction_record for a single item.

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 openWorldHint=true, and the description reinforces safe read-only behavior while detailing every component of the response. The inclusion of the German version URL adds valuable context beyond annotations.

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

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

The description is two sentences, front-loading the comprehensive record structure and ending with actionable guidance. Every word adds value, with no redundancy or extraneous text.

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

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

Given the simple input schema and lack of output schema, the description fully compensates by enumerating all return fields and noting the German version link. It is complete for an agent to understand the tool's output and usage.

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 sole parameter 'slug' has 100% schema coverage with a clear description. The description adds context by noting the slug comes from search/list results and gives an example, enhancing understanding beyond the schema alone.

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

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

The description explicitly states the tool retrieves the complete friction record for a given slug, listing all fields (status, dates, confidence, severity, etc.) and markdown sections. This clearly differentiates it from sibling tools like search_frictions or list_frictions.

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 instructs to cite the returned URL and mentions a German version, providing basic usage guidance. It implies this tool is for full detail retrieval after obtaining a slug from list/search tools, though explicit when-not-to-use alternatives is 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?

Annotations already declare readOnlyHint and openWorldHint. Description adds useful detail about output content (markdown, includes friction records) 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?

Single, well-structured sentence with no filler. Front-loads purpose and details efficiently.

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?

Adequately describes output content for a simple tool with no output schema. Could be more specific about return structure, but sufficient given annotations and schema richness.

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

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

Schema covers the parameter (100%), but description adds context that slug comes from list_patterns, which aids correct invocation beyond schema alone.

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

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

Description clearly states the tool gets a complete prevention pattern for a slug, listing specific components (pattern, usage, instructions, friction records). Distinguishes from siblings like list_patterns which only lists slugs.

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?

Schema description hints that slug comes from list_patterns, implying prior use of that tool. Does not explicitly state when not to use, but context is 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?

Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds the sorting behavior (newest first) and notes that it lists only published records, which is useful context beyond the annotations.

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

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

The description is a single sentence that is well-structured and front-loaded with the primary verb 'browse'. Every word adds value, and it is concise without being overly terse.

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

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

Given the low complexity (2 parameters, no nested objects) and no output schema, the description adequately covers the tool's behavior. It mentions sorting and filtering, but does not explicitly describe the return format, which is acceptable for a list retrieval.

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 enum descriptions for both parameters. The description mentions filtering by status and/or category, aligning with the schema, but does not add new meaning 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 it lists all published friction records, sorted by newest first, and allows filtering by status and category. It distinguishes from siblings like 'get_friction_record' (single record) and 'search_frictions' (likely search).

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

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

The description implies browsing the register for an overview, but does not explicitly state when to use this tool versus siblings or when not to use it. No exclusions or alternatives are mentioned.

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

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

The annotations already indicate readOnlyHint=true and openWorldHint=true. The description adds that each pattern includes a problem class and related records, but does not disclose other behavioral aspects like pagination, ordering, or how the list is generated. This provides some transparency beyond annotations but leaves gaps.

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 efficiently conveys the purpose and content. The parenthetical example adds concrete context without unnecessary verbosity. Every word earns its place.

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

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

With no parameters, no output schema, and annotations providing readOnly and openWorld hints, the description covers the essential aspects: what the tool returns (list of patterns) and their structure. However, it does not specify if there are options for filtering or sorting, which could be relevant for a list tool. Overall adequate but not exhaustive.

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

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

There are no parameters, so the schema coverage is 100%. The description adds value by explaining the output structure (each pattern with problem class and related records), which compensates for the lack of parameters. Given the baseline of 4 for zero parameters, this is appropriate.

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

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

The description clearly states it lists reusable build patterns that prevent Copilot Studio friction, with an example (async continuation). This distinguishes it from siblings like list_frictions (lists frictions, not patterns) and get_pattern (retrieves a single pattern).

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 does not provide explicit guidance on when to use this tool versus alternatives. It does not mention when not to use it or suggest other tools for specific needs (e.g., use get_pattern for details on a single pattern).

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 that it returns matching record(s) with a citable URL, which is helpful. Annotations already indicate readOnlyHint and openWorldHint, so the description complements but does not significantly expand beyond that.

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 defines the tool's function and domain, the second adds usage and output details. No unnecessary text.

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

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

For a simple one-parameter lookup tool, the description covers input, matching behavior, and output (records with URL). Annotations add safety context. Minor gap: no mention of case sensitivity or multiple matches, but it's sufficient.

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 the single parameter, and the description adds practical context: 'exact/substring match' and an example, enhancing understanding beyond the schema description.

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

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

The description clearly states it performs exact/substring match against Copilot Studio error codes and messages, with an example ('FlowActionTimedOut'). It distinguishes from sibling tools by specifying the use case of having a verbatim error string.

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

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

Explicitly states it is the fastest path when a verbatim error string is available. Could be improved by clarifying when not to use (e.g., when no exact match is available), but the guidance is clear and useful.

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 (readOnlyHint, openWorldHint) are complemented by detailed behavioral explanation: ranking order (exact hits first), search scope, empty result interpretation, and output fields. No contradiction with annotations.

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

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

Description is four sentences, each serving a clear purpose: main function, ranking/details, usage context, output summary. No redundant or unnecessary information. Front-loaded with key action verb 'Ranked search'.

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

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

Given no output schema, description sufficiently details return fields (slug, status, severity, last-verified date, URL). It covers search behavior, limitations, and usage context. Complements sibling tools well.

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 already provides 100% coverage with descriptions for all 4 parameters. Description adds value by explaining ranking behavior (e.g., query parameter effect on ranking) and giving an example query ('flow times out after 100 seconds'). This enriches 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?

Description clearly states it performs ranked search over the Copilot Studio Friction Index, specifying which fields are searched (error-code, message, title, alias, summary, symptom-checklist) and not searched (solution bodies). It explicitly differentiates from siblings like list_frictions and get_friction_record by focusing on search with ranking and usage 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?

Explicitly states when to use: 'Use this when the user describes a Copilot Studio problem, symptom or keyword.' It also provides negative guidance (solution bodies not searched, empty result meaning). However, it does not explicitly mention alternatives like get_friction_record for full details, though this is implied.

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