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

With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool activates roles but doesn't disclose important behavioral traits: whether activation is immediate, whether it checks eligibility first, what happens on failure, or whether it requires approval. The phrase 'match against your eligible roles' hints at validation behavior but doesn't explain the consequences of mismatches or partial failures.

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

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

The description is a single sentence that front-loads the core action and resource. It's concise and to the point, with no wasted words. The second sentence adds useful context about matching eligible roles. It could be slightly more structured by separating the usage guidance, but overall it's 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?

For a mutation tool with no annotations and no output schema, the description is incomplete. It doesn't explain what happens after activation (e.g., confirmation, errors, approval workflows), how scopes are specified, or how this differs from activate_quick_roles. The sibling list includes activate_quick_roles, which likely overlaps in functionality, and the description doesn't help an agent choose between them. The tool has 3 parameters and 2 required, so more behavioral context is needed.

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 adds minimal value beyond the schema: it mentions 'role names and scopes' but the schema only has a 'roles' array and no explicit 'scopes' parameter. This creates slight ambiguity about whether scopes are embedded in role names or a separate concept. The description doesn't clarify the 'duration' or 'justification' parameters 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 tool activates specified PIM roles in Azure, with a specific verb ('activates') and resource ('PIM roles'). It distinguishes itself from sibling tools like list_eligible_roles by focusing on activation, though it doesn't explicitly name alternatives. The mention of 'match against your eligible roles' adds useful context about how the tool works.

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: provide role names and scopes to match eligible roles. It doesn't explicitly state when to use this tool versus alternatives like activate_quick_roles, which appears to be a sibling that also activates roles. The lack of explicit when/when-not guidance leaves some ambiguity, but the description does convey the core usage 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?

With no annotations, the description carries the behavioral disclosure burden. It adds useful context by noting that the tool 'Reads the latest config each time' and requires no server reload. However, it does not disclose side effects beyond activation, such as permission requirements, audit implications, or what happens when no quick roles are configured.

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

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

The description is three short, purposeful sentences with no filler. The core action and purpose are front-loaded, followed by prerequisite setup and a useful configuration note.

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 low-complexity tool with two optional parameters and no output schema, the description provides the essential setup context and behavioral note. It is sufficient for an agent to invoke the tool correctly, though it could mention the no-roles-configured edge case.

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

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

Schema description coverage is 100%, and the description does not add parameter-specific meaning beyond the schema. The baseline of 3 applies because the schema already documents duration and justification clearly.

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 ('Activates'), a specific resource ('your saved quick roles (favorites)'), and the purpose ('for fast elevation'). It is distinguishable from activate_pim_roles by focusing on saved favorites, though it does not explicitly contrast itself with that sibling.

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 setup context: configure quick roles first using list_quick_roles and save_quick_roles. It also explains the dynamic-config behavior, but it does not state explicit conditions for choosing this over activate_pim_roles or other siblings.

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

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

With no annotations provided, the description must carry the disclosure burden. It transparently states the operation is read-only ('Lists') and specifies the returned information (start and end times). It does not mention any side effects, but for a listing operation this is sufficient. It also implicitly communicates the elevation/security context, but does not detail permissions or limitations, which is a minor gap.

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 concise, front-loaded sentences. The first sentence names the exact purpose, and the second expands on output details. No unnecessary words or redundancy, making it efficient and easy for an agent to parse.

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

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

For a simple, parameterless listing tool with no output schema, the description is largely complete. It specifies what is listed and the included fields (start and end times). It does not mention potential nuances like ordering, scope (e.g., only the user's own activations), or any prerequisites, but these are not critical for a straightforward list operation. The sibling context suggests some differentiation could be helpful, but it is not strictly required.

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 covers everything (100%). The description adds value by explaining what the tool returns (active PIM roles with timing). Since there are no parameters to document, the baseline of 4 applies, and the description does not need to add further parameter 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 clearly states a specific verb ('Lists') and resource ('currently active (elevated) PIM role assignments'), and adds detail on the output (roles activated with start/end times). It distinguishes itself from siblings by its focus on active PIM roles, contrasting with list_eligible_roles (eligible not active) and list_quick_roles (quick roles, not PIM).

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 it (when you need currently activated PIM roles) but does not explicitly name alternatives or exclusion criteria. It lacks a direct statement like 'Use this instead of list_eligible_roles when you want only elevated roles you've activated.' For a tool surrounded by similar list/activation siblings, this guidance is 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?

With no annotations provided, the description carries the behavioral burden. It clearly signals a read-only listing ('Lists', 'Returns') and specifies the returned attributes (role names, scopes, assignment type). It does not discuss auth or rate limits, but for a parameterless list operation that is a minor gap.

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

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

Two sentences with the core action front-loaded and the return shape provided in the second sentence. No filler, repetition, or irrelevant 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 parameterless, read-only list with no output schema, the description covers the action, scope, and return fields completely. An agent has enough information to invoke the tool and interpret its result.

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 an empty schema, so there is nothing semantic to add; the baseline 4 applies. The description correctly avoids inventing or describing parameters.

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

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

States a precise verb ('Lists') and a specific resource ('eligible PIM roles that can be activated in Azure'), and names the returned attributes. This clearly distinguishes it from siblings like list_active_roles, which would cover active rather than eligible roles.

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?

Usage context is implied by 'eligible ... that can be activated': an agent would call this before activating a role. However, the description never names alternatives such as list_active_roles or activate_pim_roles, nor states conditions for 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?

With no annotations provided, the description carries the behavioral disclosure burden. The verbs 'Lists' and 'shows' clearly imply a read-only operation, and the mention of providing indices indicates the tool surfaces data meant for the save_quick_roles workflow. However, it does not explicitly state there are no side effects, nor does it describe the output format or pagination if any.

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, each earning its place. The first sentence states the tool's output, and the second explains the workflow. No filler or repetition of schema 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 description is adequate for a parameterless, read-only list tool. It explains what will be shown and what the caller should do with the results. The only gap is not clarifying the difference from the similarly named list_eligible_roles sibling, which could lead an agent to pick the wrong 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, so the schema leaves nothing ambiguous. The description adds relevant context about what the returned indices are used for (selecting quick roles), but with no parameters to document, the baseline of 4 is appropriate.

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

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

The description clearly states the tool 'Lists all eligible PIM roles with indices and shows your currently saved quick roles' – a specific verb and resource. It differentiates itself by mentioning both eligible roles and saved quick roles, but the existence of sibling list_eligible_roles creates some ambiguity about the exact boundary between the two tools.

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

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

The description gives explicit workflow guidance: 'Use this to see available roles, then call save_quick_roles with your selected indices to update your favorites.' This tells the agent when to invoke the tool and what to do next. However, it does not explicitly state when not to use it or how it compares to other siblings like list_eligible_roles or activate_quick_roles.

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?

No annotations are provided, so the description must carry the full burden of behavioral disclosure. It explains the purpose but does not mention side effects, whether existing quick roles are overwritten, permission requirements, or what happens after saving. This is a notable gap for a mutation tool.

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 with no wasted words. The key action and the required input source are front-loaded, making it easy for an agent to parse quickly.

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 and schema together define the parameters well, but with no annotations and no output schema, the tool lacks behavioral context such as overwrite behavior, return value, or next steps. It is adequate for a basic save operation but leaves some operational 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?

Schema coverage is 100% and each parameter already has a meaningful description. The tool description adds helpful context by pointing to list_quick_roles as the source of indices, but it doesn't add new details for the optional description or defaultJustification parameters.

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 saves selected roles as quick roles for fast activation, using a specific verb and resource. It distinguishes itself from siblings like activate_quick_roles by indicating this is a save operation, not activation.

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

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

The description gives explicit usage context: use indices from list_quick_roles to specify which roles to save. It doesn't explicitly exclude alternatives or state when not to use the tool, but the instruction is clear and actionable.

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