entitlement_remove

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

Annotations already indicate destructive and non-read-only behavior. The description adds valuable context beyond annotations: 'confirm=False previews; confirm=True revokes' reveals a preview mode, and 'Audited' discloses that the action is logged. These details are not in the annotations and meaningfully inform the agent about safety and side effects.

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-structured with a one-line purpose, usage notes, and a clearly labeled Args section. It is slightly redundant—the confirm behavior is mentioned both in the intro line and in the Args list—but this repetition is minor and helps reinforce a critical safety detail. Overall, every sentence contributes value.

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

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

For a destructive mutation tool, the description provides essential context: where to get IDs, how to preview, the audit trail, and target config. It lacks explicit mention of return values or success/failure behavior, but in the absence of an output schema this is a minor gap. The tool's purpose, parameters, and behavior are sufficiently 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 has 0% description coverage, but the description fully compensates by explaining every parameter: pool_id is from pool_list, ad_user_or_group_ids are AD SIDs from entitlement_list, confirm controls preview vs. revoke, and target defaults to config.yaml. This is critical because the schema only lists parameter names and types without additional meaning.

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: 'Revoke desktop-pool access from AD user/group SID(s).' The verb 'revoke' is specific, the resource is 'desktop-pool access', and the target is 'AD user/group SID(s)'. It also distinguishes from sibling tools by referencing 'entitlement_list' and 'entitlement_add' (implied), making the action 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?

It provides practical guidance: 'Get SIDs from entitlement_list' tells the agent where to source required inputs. It also explains the confirm flag: 'confirm=False previews; confirm=True revokes', which is essential for safe usage. However, it does not explicitly contrast with alternatives like 'entitlement_add' or state when not to use it, though the context with siblings makes it clear.

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