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

The description discloses a critical behavioral trait: 'This only stages a request: the owner opens the link in their browser, reviews it, and approves it there with their agent PIN.' This is beyond what annotations provide (none are given), and it also includes a security-relevant instruction: 'Never ask for or accept the PIN in chat.' This is exactly the kind of behavioral context an agent needs to avoid a serious error.

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 sentences, each earning its place: the first states the action and initial state, the second explains the follow-up workflow, and the third discloses the approval flow and PIN safety rule. It is front-loaded with the core purpose and scoping constraint, and there is zero waste.

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 2-parameter tool with no output schema, the description is complete. It covers the initial state of the role, the follow-up tools to use, the workspace ownership prerequisite, the approval flow, and the PIN safety rule. An agent has everything it needs to call this tool correctly and avoid a security mistake.

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 both parameters. The description adds context about the workspace parameter ('Only needed when you own more than one — list_workspaces shows them'), which is useful. However, it doesn't add much about the name parameter beyond what the schema provides. Baseline 3 is appropriate since the schema does the heavy lifting.

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 and resource: 'Create a named access role in a workspace you own.' It clearly distinguishes this from siblings like set_access_role_capability, set_access_role_mailbox_access, and assign_access_role by explaining the role starts with all capabilities and mailbox access enabled, then must be narrowed with those sibling tools. This is a clear, specific purpose that an agent can act on.

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 explicitly explains the workflow: create the role, then narrow it with set_access_role_capability and set_access_role_mailbox_access, then assign people with assign_access_role. It also states the prerequisite that you must own the workspace, and that the workspace parameter is only needed when you own more than one. This is explicit when-to-use guidance with named alternatives and sequencing.

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