MCP tools
All tools resolve the calling agent’s trusted identity, run through core
permission checks + the audit log, and return JSON. Domain failures come back as
isError tool results (with an error code), not crashes.
The Scope column is the OAuth token scope an agent needs. Humans are
governed by role alone (see the security model);
agents need both a sufficient role and the listed scope. Tools marked —
need no scope — they are the provisional/account-level bootstrap tools available
before (or independent of) a workspace grant.
Identity & onboarding
Section titled “Identity & onboarding”Before you belong to a workspace your token resolves to a provisional identity
that exposes only whoami and create_tenant (and join_tenant). After
bootstrapping, the full toolset below unlocks.
| Tool | Scope | Description |
|---|---|---|
whoami |
— | Your trusted identity (principal id, org, role) and granted scopes |
create_tenant |
— | Bootstrap a new workspace (org + first project) anchored to your account |
join_tenant |
— | Join an existing workspace with an invite code a teammate shared |
create_workspace |
— | Create an additional workspace owned by your account |
list_workspaces |
— | List the workspaces your account belongs to |
Teams, projects & milestones
Section titled “Teams, projects & milestones”| Tool | Scope | Description |
|---|---|---|
list_teams |
ticket:read |
Teams in your workspace |
create_team |
team:write |
Create a team (optional grouping; no key required) |
list_projects |
ticket:read |
Projects, optionally filtered to a team |
create_project |
project:write |
Create a project with its own ticket-key prefix |
set_project_key |
project:write |
Rename a project’s prefix; re-keys all its tickets in lockstep |
move_project |
project:write |
Move a project to another team; ticket keys, numbers and history are preserved |
archive_project |
project:write |
Archive (or unarchive) a project; reversible, keeps all tickets |
delete_project |
project:write |
Permanently delete an empty project (no tickets) |
create_milestone |
ticket:write |
Create a milestone / cycle (sprint) |
list_milestones |
ticket:read |
Milestones in a project |
Tickets
Section titled “Tickets”| Tool | Scope | Description |
|---|---|---|
list_tickets |
ticket:read |
Tickets in a project; optional status / assigneeId / milestoneId filters |
my_tickets |
ticket:read |
Tickets assigned to you (primary or co-assignee) |
get_ticket |
ticket:read |
A ticket by id or key (e.g. ROOST-42) |
get_ticket_context |
ticket:read |
A ticket plus comments, attachments, subtasks, links & assignees in one call |
create_ticket |
ticket:write |
Open a ticket — set labels, parentId, dueDate, estimate, idempotencyKey |
create_tickets |
ticket:write |
Open many tickets at once (1–100) in one round-trip |
update_ticket |
ticket:write |
Edit title/description/priority/labels/assignee/parent/dates/estimate |
move_ticket |
ticket:write |
Move a ticket to another project (fresh key + number) |
change_status |
ticket:write |
Move status (validated against the workflow) |
claim_next |
ticket:write |
Atomically claim & assign the next actionable unassigned ticket |
search_tickets |
ticket:read |
Ranked full-text search over titles + descriptions (stemmed) — exact keyword; prefer find_similar_tickets for meaning-based recall when semantic search is on |
find_similar_tickets |
ticket:read |
Semantic (vector) search by meaning across all projects (pass projectId to scope to one); needs embeddings configured |
backfill_embeddings |
ticket:write |
Embed tickets that lack an embedding (e.g. created before embeddings were configured) |
find_by_label |
ticket:read |
Find related tickets across the workspace by tag |
list_subtasks |
ticket:read |
Direct children of a ticket |
Pass compact: true to list_tickets / my_tickets / find_by_label /
search_tickets / find_similar_tickets for a trimmed
{id, key, title, status, priority, assigneeId} shape — far fewer tokens when
scanning a board. When several principals may edit one ticket, pass
expectedUpdatedAt to update_ticket / change_status / assign_ticket for
optimistic concurrency (the write applies only if the ticket is unchanged).
Conversation traces & context
Section titled “Conversation traces & context”Persist the human↔agent working record so it survives the session and becomes
recallable across every project in the workspace. recall_* need embeddings
configured on the instance (ROOSTER_EMBEDDING_*); without them they return a
clear “not configured” error and everything else still works.
| Tool | Scope | Description |
|---|---|---|
append_messages |
conversation:write |
Record a batch (1–50) of the conversation trace on a ticket, tagged by stage (input | plan | execution | review) and role |
list_messages |
conversation:read |
A ticket’s conversation trace, optionally filtered to one stage |
recall_conversations |
conversation:read |
Semantic recall over conversation traces across all projects; filter by stage / role |
save_context_file |
project:write |
Save (or update) a named context document on a project; text is stored and embedded |
list_context_files |
ticket:read |
A project’s context documents (optionally only those pinned to a ticket) |
recall_context |
conversation:read |
Unified semantic recall across tickets, conversation traces and context files |
rag_search |
ticket:read |
Grounded RAG retrieval: hybrid keyword+semantic search over the corpus, returning ranked cited hits + a ready-to-ground contextBlock (message/context_file hits need conversation:read) |
Assignees, comments & attachments
Section titled “Assignees, comments & attachments”| Tool | Scope | Description |
|---|---|---|
assign_ticket |
ticket:write |
Set the single primary assignee, or null to unassign |
add_assignee |
ticket:write |
Add a co-owner (shared work) |
remove_assignee |
ticket:write |
Remove a co-owner |
list_assignees |
ticket:read |
A ticket’s effective assignees (primary + co-owners) |
comment |
ticket:write |
Add a comment |
add_attachment |
ticket:write |
Attach a URL (Rooster does not host files) with an optional label |
list_attachments |
ticket:read |
A ticket’s attachments |
remove_attachment |
ticket:write |
Remove an attachment |
Links & relations
Section titled “Links & relations”| Tool | Scope | Description |
|---|---|---|
link_tickets |
ticket:write |
Relate tickets: blocks, duplicates, or symmetric relates |
unlink_tickets |
ticket:write |
Remove a relation |
list_links |
ticket:read |
A ticket’s relations from its own viewpoint (inverses derived) |
Watchers & notifications
Section titled “Watchers & notifications”| Tool | Scope | Description |
|---|---|---|
watch_ticket |
ticket:read |
Follow a ticket — be notified on status/assignee/comment changes |
unwatch_ticket |
ticket:read |
Stop following a ticket |
list_watchers |
ticket:read |
Who is following a ticket |
my_watches |
ticket:read |
Tickets you follow |
crow |
ticket:write |
Wake/notify a ticket’s assignee |
Being assigned to or commenting on a ticket auto-follows it. Notifications are
delivered through the crow webhook (ROOSTER_CROW_WEBHOOK_URL).
Members, agents & audit
Section titled “Members, agents & audit”| Tool | Scope | Description |
|---|---|---|
invite_member |
team:write |
Invite a human teammate by email |
create_invite |
team:write |
Mint a shareable join code |
list_agents |
agent:read |
Agents registered in the workspace |
register_agent |
agent:write |
Register a new agent principal |
set_agent_status |
agent:write |
Suspend / reactivate an agent |
read_audit |
audit:read |
Read the append-only audit log |
CRM (customers & contacts)
Section titled “CRM (customers & contacts)”| Tool | Scope | Description |
|---|---|---|
create_customer |
crm:write |
Create a customer/client (lifecycleStage lead→prospect→active→churned) |
list_customers |
crm:read |
List the workspace customers, most recent first |
get_customer |
crm:read |
Fetch a single customer by id |
update_customer |
crm:write |
Update a customer’s name / owner / tags |
change_lifecycle_stage |
crm:write |
Move a customer through the relationship lifecycle (validated transitions) |
add_contact |
crm:write |
Add a person (contact) to a customer |
list_contacts |
crm:read |
List a customer’s contacts |
update_contact |
crm:write |
Update a contact’s name / email / phone / role |
remove_contact |
crm:write |
Remove a contact |
create_deal |
crm:write |
Open a deal under a customer (pipeline prospecting→…→won/lost) |
list_deals |
crm:read |
List a customer’s deals |
get_deal |
crm:read |
Fetch a single deal by id |
update_deal |
crm:write |
Update a deal’s title / value / currency / closeDate / probability / owner / tags |
change_deal_stage |
crm:write |
Move a deal through the sales pipeline (validated transitions) |
log_interaction |
crm:write |
Log a call/email/note/meeting against a customer/deal/contact (embedded for recall) |
list_interactions |
crm:read |
List a target’s logged interactions |
link_deal_work |
crm:write |
Link an existing delivery project to a deal (won-deal → work bridge) |
list_deal_work |
crm:read |
List the delivery projects linked to a deal |
list_customer_work |
crm:read |
List every delivery project serving a customer, across all their deals |
Scopes
Section titled “Scopes”Scopes map 1:1 to the core permission set. Each carries a minimum role floor that the agent’s membership must also satisfy:
| Scope | Min role |
|---|---|
ticket:read |
viewer |
ticket:write |
member |
project:write |
member |
conversation:read |
member |
conversation:write |
member |
crm:read |
member |
crm:write |
member |
team:write |
admin |
agent:read |
viewer |
agent:write |
admin |
audit:read |
admin |
A token may also hold * (all scopes). Token scopes are intersected with the
agent’s configured allowance, so a token can never exceed what its agent is
permitted.
Resources
Section titled “Resources”Read-only, addressable board state:
ticket://{key}— a single ticket, e.g.ticket://ROOST-42project://{id}— a project’s metadata
Status workflow
Section titled “Status workflow”The default ticket workflow (status sets and transitions are global today; per-project configurable workflows are a planned post-v1 item):
backlog ⇄ todo → in_progress → in_review → done ↑______________|backlog · todo · in_progress · in_review ──→ canceled (cancel from any open state)done ──→ in_progress (reopen)canceled ──→ backlog | todo (reopen)New tickets start in backlog. change_status rejects illegal transitions and
same-status no-ops.