User Tools
add_user
Create a new team member. Owner only.
Console-only — not reachable from Slack; use the web console.
Writes to: 03. Users
Parameters:
| Param | Required | Description |
|---|---|---|
requesting_user_slack_id | ✅ | |
user_name | ✅ | Display name or Slack mention (see below) |
role | ✅ | "owner" | "manager" | "user" |
slack_user_id | Optional. Omit for contractors and vendors who are not yet in the Slack workspace. Can be added later via update_user_role. | |
discipline_id | FK → 08. Disciplines.id | |
employment_type | "fte" (default) | "contractor" | "vendor" | |
hours_per_week | Float. Working hours per week. FTE: omit — defaults to 40. Contractor: required — VERA will ask if not provided. Vendor: omit — defaults to 40 (not used for capacity). |
Employment-type/role restriction (issue #2034): a contractor or vendor may only be given the "user" role — rejected otherwise. A vendor additionally never uses VERA at all, so slack_user_id and email must both be empty for a vendor — either one non-empty is rejected. The web console's Add-user modal reorders Employment type as the first field and hides/disables Hours per week, Slack ID, and Email for a vendor accordingly, but this rule is enforced here, at the endpoint, regardless of which surface the call came from.
Slack mention auto-resolution: If user_name is passed as a Slack mention token (<@U…>, bare U…/W…, @handle, markdown profile link, or email mention), VERA extracts the Slack user ID and fetches the real name from the Slack profile API (real_name → display_name fallback chain). The stored row will have the human-readable profile name, not the mention literal. If a slack_user_id is provided alongside user_name, the Slack profile name from the API overwrites the typed shortname. If the Slack API is unavailable and user_name is still a mention literal after resolution, the call is rejected with a descriptive error rather than storing garbage data.
list_users
All active users with disciplines.
Reads from: 03. Users, 08. Disciplines
Inactive users appear with (inactive) next to their name.
update_user_role
Change a user's permission role and other profile fields. Owner only. At least one of new_role, new_slack_user_id, new_employment_type, new_email, or new_discipline_id must be supplied.
Console-only — not reachable from Slack; use the web console.
Updates: 03. Users (role, slack id, employment type, email, and/or discipline)
Parameters: requesting_user_slack_id, user_name or slack_user_id, and one or more of: new_role, new_slack_user_id, new_employment_type, new_email, new_discipline_id.
new_discipline_id assigns the user's discipline; pass an empty string to clear it. A non-empty value must be the id of an active discipline. (Surfaced in the console Users page Edit modal as the "Discipline" selector.)
Employment-type/role restriction (issue #2034): the same rule add_user enforces applies here — a contractor or vendor may only hold the "user" role, and a vendor may not have a Slack ID or an email. The check runs against the effective post-update state (the new value where supplied via new_role/new_employment_type/new_slack_user_id/new_email, else the user's current stored value), and only when the request supplies new_role or new_employment_type — a call that touches neither is never blocked by this rule, so an existing row already in an invalid combination (predating this rule) can still have its other fields corrected.
rename_user
Change a user's display name. Owner only.
Console-only — not reachable from Slack; use the web console.
Updates: 03. Users col C
Parameters: requesting_user_slack_id, current_name or slack_user_id, new_name
Broken-row repair: If slack_user_id is supplied and the ID is not found in VERA by its stored slack_user_id, VERA checks for a row whose stored name is the raw mention literal (<@U…> or bare ID). If found, it renames the row and links the Slack ID in the same operation. This recovers users that were added before mention normalization was in place.
assign_pm
Assign a project manager to a project. Owner only.
This is a two-in-one operation:
- Promotes the user to
managerrole (if currentlyuser) - Sets
pm_user_idon the project
Console-only — not reachable from Slack; use the web console.
Updates: 02. Projects col G, 03. Users col D
Parameters: requesting_user_slack_id, project_name, pm_name or pm_slack_id
If the user hasn't messaged the bot yet, they won't be in the system. They need to send at least one message to be auto-registered before they can be assigned as PM.
deactivate_user
Mark a user as inactive. They cannot log time or take any actions. Historical entries are preserved. Owner only.
Console-only — not reachable from Slack; use the web console.
Updates: 03. Users col E (status → "inactive")
Parameters: requesting_user_slack_id, user_name or slack_user_id
Natural language triggers: "delete user", "remove user", "deactivate user" — all map to this tool.
reactivate_user
Restore an inactive user. Owner only.
Console-only — not reachable from Slack; use the web console.
Updates: 03. Users col E (status → "active")
Parameters: requesting_user_slack_id, user_name or slack_user_id
Natural language triggers: "reactivate", "restore", "re-enable"
ensure_user
Internal tool — auto-creates a user record if one doesn't exist for the given Slack ID. Called automatically when a new person messages the bot. Creates with role = "user" and employment_type = "fte".
Display name auto-sync: On every message, VERA compares the caller's current Slack display name to the stored name. If they differ (e.g. after a Slack workspace rename), the stored name is silently updated. Manual renames via rename_user are only needed if you want a name different from what appears in Slack.
list_disciplines
All functional discipline categories.
Reads from: 08. Disciplines
Parameters: requesting_user_slack_id
add_discipline
Create a new functional discipline category. Owner only.
Console-only — not reachable from Slack; use the web console.
Writes to: 08. Disciplines
Parameters: requesting_user_slack_id, name
The words "Designer," "Developer," "Project Manager" may refer to a person name or a discipline. VERA confirms before acting when the context is ambiguous.
rename_discipline
Rename an existing discipline category. Owner only.
Console-only — not reachable from Slack; use the web console.
Writes to: 08. Disciplines
Parameters: requesting_user_slack_id, old_name, new_name
Blocks case-insensitive name collisions. No user records need updating — disciplines are referenced by ID.
Returns: discipline_id, old_name, new_name
archive_discipline
Archive a discipline category so it no longer appears in menus. Owner only. Historical references are preserved. Use unarchive_discipline to restore.
Console-only — not reachable from Slack; use the web console.
Writes to: 08. Disciplines
Parameters: requesting_user_slack_id, discipline_name
Hard fails (409) if any active user has this discipline assigned. Reassign all users' discipline field first.
Returns: discipline_id, discipline_name
unarchive_discipline
Restore an archived discipline so it appears in menus again. Owner only.
Console-only — not reachable from Slack; use the web console.
Writes to: 08. Disciplines
Parameters: requesting_user_slack_id, discipline_name
Returns: discipline_id, discipline_name
set_discipline_color
Set the identity color a discipline is displayed with, wherever a discipline appears in a table. Owner only.
Console-only — not reachable from Slack; use the web console.
Updates: 08. Disciplines
Parameters:
| Param | Required | Description |
|---|---|---|
requesting_user_slack_id | ✅ | |
discipline_id | ✅ | Must be an active discipline |
color | Must be one of a fixed set of recognized color names. Empty clears the discipline back to uncolored. |
Purely a display identity — it changes no calculation and carries no meaning beyond telling disciplines apart at a glance.
set_discipline_default_task
Set a discipline's suggested task — the task VERA pre-selects when logging time or adding an envelope for someone in that discipline. Owner only.
Console-only — not reachable from Slack; use the web console.
Updates: 08. Disciplines
Parameters:
| Param | Required | Description |
|---|---|---|
requesting_user_slack_id | ✅ | |
discipline_name | ✅ | |
default_task_id | Must be an active (non-archived) task. Empty clears the default. |
This is a forward-looking convenience only — it pre-fills a form, and the person can always override it. It's a different thing from a task's own discipline attribution (see set_task_discipline on the Task Tools page), which is what drives by-discipline reporting.
list_message_log
View the delivery log of scheduled morning and evening messages VERA has sent. Owner/Admin only.
Console-only — not reachable from Slack; use the web console.
Reads from: scheduled-message delivery log
Parameters:
| Param | Description |
|---|---|
requesting_user_slack_id | |
user_id | Optional — filter to one person |
kind | Optional — "morning" | "evening" | "renewals" |
start_date | Optional range filter |
end_date | Optional range filter |
Returns: up to 500 rows, each with the recipient, the message kind, the full message body, whether the send succeeded, and when it was sent (or attempted). Rows older than 90 days are pruned automatically.
This is a record of what VERA told people, not a way to send anything — it's read-only.
get_project_assignments
Who is allocated to a project. Manager/Owner.
Shared with Envelope Tools — documented there.