set_permissions

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

With zero annotations provided, the description carries the full burden of behavioral disclosure, and it only discloses scope. It does not state whether the assignment replaces or augments existing roles, whether admin/owner authorization is required, whether the operation is reversible, or what happens when the principal already holds a role. For a security-sensitive mutation tool this is a meaningful 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 one-sentence purpose summary is front-loaded and immediately unambiguous. The API scoping note earns its place by resolving the ambiguity of the generic tool name, and the Args section is justified given 0% schema coverage. No wasted words.

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 fully covers purpose and parameters, which is sufficient for a basic call. But as a mutation tool with no annotations and no output schema, it omits expected context: the effect on pre-existing assignments, required authorization level for the caller, and any irreversibility or constraints. The nullable workspace field and its meaning also go unexplained.

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 0%, so the description fully compensates: the Args section documents all four parameters with data types and valid values — workspace (name or ID), principal_id (UUID), principal_type ('User', 'Group', 'ServicePrincipal'), and role ('Admin', 'Member', 'Contributor', 'Viewer'). This adds the enum-like vocabulary and type constraints the schema itself omits.

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 opens with a specific verb+resource: 'Add a workspace role assignment' followed by the exact role vocabulary (Admin, Member, Contributor, Viewer). The follow-up note explicitly scopes the tool to workspace-level roles and excludes item-level permissions, which differentiates it from a generic 'set_permissions' name and from the sibling get_permissions read counterpart.

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 note 'Fabric REST API supports workspace-level roles, not item-level permissions' gives an implied exclusion — the agent can infer this tool is wrong for item-level permission changes. However, no alternative tool is named and no explicit when-to-use condition is stated, so the routing guidance is left to inference.

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