manage_sharepoint_governance_policies

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false. The description adds some context by mentioning the types of policies managed (sharing controls, access restrictions, site lifecycle management), which helps clarify what 'destructive' might mean in this context. However, it doesn't provide additional behavioral details like authentication requirements, rate limits, or specific destructive consequences beyond what annotations indicate.

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, efficient sentence that front-loads the core purpose. It wastes no words and directly communicates what the tool does. However, for such a complex tool with many parameters and destructive potential, the extreme brevity might be insufficient despite being structurally sound.

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 complex, destructive tool with 7 parameters, nested objects, no output schema, and multiple policy types, the description is inadequate. It doesn't explain the relationship between action and other parameters, doesn't clarify what 'manage' entails across different policy types, and provides no information about return values or error conditions. The annotations help but don't compensate for the description's lack of operational context.

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 7 parameters thoroughly. The description mentions policy types (sharing controls, access restrictions) that align with the policyType enum values, but adds no meaningful parameter semantics beyond what the schema provides. The baseline score of 3 reflects adequate coverage through 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 clearly states the tool's purpose as managing SharePoint governance policies with specific examples (sharing controls, access restrictions, site lifecycle management). It distinguishes itself from siblings like manage_sharepoint_sites or manage_sharepoint_lists by focusing on governance policies rather than site/list operations. However, it doesn't explicitly differentiate from other policy management tools like manage_conditional_access_policies or manage_retention_policies.

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 no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites, required permissions, or when to choose this over other policy management tools. The agent must infer usage from the tool name and description alone, which is insufficient for a complex governance tool.

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