add_workspace_member

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

Annotations indicate a mutation tool (readOnlyHint=false). Description adds precondition that user must exist in org, but does not disclose potential error cases like duplicate membership or permission requirements. Good but could be more thorough.

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?

Two concise sentences: purpose and usage guidance. No redundant information, well-structured.

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?

Given moderate complexity and presence of output schema, description covers key preconditions and usage steps. Could mention error handling for duplicate members, but overall sufficient.

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 covers all parameters with descriptions. Description adds value by clarifying user_id must be UUID (not email) and referencing list_all_users, which goes beyond schema details.

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 'Add an existing org user to a workspace with a role,' specifying verb, resource, and constraints. It distinguishes from sibling tools like invite_user and list_all_users by referencing them.

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 provides prerequisites: requires UUID user_id, use list_all_users to find it, and invite_user if not in org. This gives clear when-to-use and when-not-to-use guidance.

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