box_tools_users.md

Box Tools Users

This document describes the tools available for managing and querying users in Box.

Available Tools

1. box_users_list_tool

List all users in the Box account.

• Arguments: None
• Returns: list[dict] with all users
  • Each user includes: id, name, login (email), status, created_at, modified_at, etc.
• Use Case: Get a comprehensive list of all users in the enterprise
• Performance Note: May return a large dataset for large enterprises

2. box_users_locate_by_name_tool

Find a user by their exact full name (case-insensitive).

• Arguments:
  • name (str): The full name of the user to locate
• Returns: dict with user information if found, otherwise error message
  • Returns: id, name, login, email, status, created_at, modified_at
• Use Case: Get user ID when you know the exact user name
• Note: This is an exact match search; partial names won't match

3. box_users_locate_by_email_tool

Find a user by their email address (exact match).

• Arguments:
  • email (str): The email address of the user
• Returns: dict with user information if found, otherwise error message
  • Returns: id, name, login, email, status, created_at, modified_at
• Use Case: Look up a user by their email address
• Note: Email addresses are the most reliable user identifier

4. box_users_search_by_name_or_email_tool

Search for users by name or email (partial/fuzzy match).

• Arguments:
  • query (str): Search query (part of name or email)
• Returns: list[dict] with matching users
  • Each match includes: id, name, login, email, status, created_at, modified_at
• Use Case: Find users when you don't have the exact name or email
• Examples:
  • Search by first name: query: "John"
  • Search by last name: query: "Smith"
  • Search by partial email: query: "john@example"

---

User Information Returned

Each user record includes:

• id: Unique Box user ID
• name: User's full name
• login: User's email/login address
• email: User's email address
• status: Account status (active, inactive, cannot_delete_login, cannot_delete_edit)
• created_at: Account creation timestamp
• modified_at: Last modification timestamp
• role: User's role (user, admin, coadmin)
• language: User's language preference
• timezone: User's timezone
• phone: User's phone number (if available)
• address: User's address (if available)

---

Usage Tips

1. Finding Users:

   • Use box_users_locate_by_email_tool for most reliable lookup (email is unique)
   • Use box_users_locate_by_name_tool if you know the exact full name
   • Use box_users_search_by_name_or_email_tool for fuzzy/partial matching

2. Performance Considerations:

   • box_users_list_tool returns all users - can be slow for large enterprises
   • Search tools are more efficient for finding specific users
   • Email lookup is fastest when email is available

3. Use Cases:

   • Share files/folders: Look up user ID to add collaborator
   • Assign tasks: Find user ID for task assignment
   • Collaboration: Verify user exists before adding to group
   • Reporting: List all users for audit purposes

---

Examples

Example 1: Find user by email

Tool: box_users_locate_by_email_tool
email: "john.smith@example.com"

Returns: User ID and full user information

Example 2: Search for users by partial name

Tool: box_users_search_by_name_or_email_tool
query: "john"

Returns: All users with "john" in their name or email

Example 3: Search by partial email

Tool: box_users_search_by_name_or_email_tool
query: "john@example"

Returns: All users with "john@example" in their email

Example 4: Get all users

Tool: box_users_list_tool

Returns: Complete list of all Box users in the enterprise

Refer to src/tools/box_tools_users.py for implementation details.