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

Beyond the annotations, the description discloses that this action 'overrides any existing role,' which is an important side effect, and states that admin access is required. It also explains bulk behavior for batched execution. This adds valuable behavioral context beyond the annotation flags.

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 compact and front-loaded, with each sentence providing functional value: what the tool does, how to target each recipient type, the permission prerequisite, and bulk support. There is no fluff or repetition of schema content.

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 10 parameters and no output schema, the description covers the core action, target selection rules, a key side effect (role override), a permission prerequisite, and bulk execution. It does not describe the response format or potential failures, but overall it is substantially complete for making a correct invocation.

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?

With 0% schema description coverage, the description carries the burden of parameter explanation. It meaningfully clarifies that `user_email` should be the only target for users, `group_id` for groups, and `workspace_api_key_id` for service accounts, and it describes the bulk parameters. However, it does not fully explain `resource_type` or the `account` parameter, leaving some gaps despite the rich enum.

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 'Share Workspace Resource' and immediately explains its function: granting a role on a workspace resource to a user, group, or workspace API key. It specifies the role values and the scope, making it clearly distinct from other resource-management tools like adding or removing members.

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 concrete guidance on how to use the tool: target users by email, groups by id, and service accounts by API key id, with the prerequisite that users must be in the workspace and the caller needs admin access. It does not explicitly contrast with sibling tools, but the targeting rules and permission requirement provide clear situational guidance.

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