Tools reference

The Toado MCP server exposes 22 tools. They fall into two categories: read (no side effects) and write (mutate state). Each tool declares a required scope; calls with an under-scoped token return insufficient_scope without round-tripping to the API.

This page is generated from src/data/mcp-tools.json, which is hand-synced with the MCP server source on every release. The current snapshot matches Toado v0.1.4.

Read tools

Use these to discover ids, fetch ticket context, and search.

`list_companies` read

Lists every company the token can see.

Required scope: read

Returns

Array of {id, name, role}.

Errors

unauthorized

`list_projects` read

Lists projects, optionally filtered to one company.

Required scope: read

Parameters

Name	Type	Description
`company_id`	`string?`	Filter to a single company. Omit to list across every company the token can see.

Returns

Array of {id, company_id, name, url_patterns}.

Errors

unauthorized
company_not_found

`list_columns` read

Lists the workflow columns of a project (To Do, In Progress, Done, etc.). Required before moving a ticket.

Required scope: read

Parameters

Name	Type	Description
`project_id`	`string`	Project whose columns to list.

Returns

Array of {id, name, order}.

Errors

project_not_found
forbidden

`list_tickets` read

Lists tickets in a project with optional filters. Defaults to active (non-archived) tickets.

Required scope: read

Parameters

Name	Type	Description
`project_id`	`string`	Project to query.
`column_id`	`string?`	Filter to one column.
`status`	`'active' \| 'archived' \| 'all'`	Default 'active'.
`query`	`string?`	Text search within the project.
`limit`	`number?`	Page size, max 100.
`cursor`	`string?`	Pagination cursor from a previous response.

Returns

Paginated list: { items: TicketSummary[], cursor?: string }.

Errors

project_not_found
forbidden
invalid_cursor

`get_ticket` read

Returns a full ticket with capture data, comments, and DevTools arrays. Use this before working a bug so you have console / network / error context.

Required scope: read

Parameters

Name	Type	Description
`ticket_id`	`string`
`include`	`Array<'capture' \| 'comments' \| 'attachments' \| 'annotations' \| 'devtools'>?`	Currently advisory; the server returns the full payload regardless.

Returns

Ticket with title, description, source_url, capture (console/network/errors/performance), comments, attachments, annotations.

Errors

ticket_not_found
forbidden

`get_capture_asset` read

Returns a URL to download a capture asset (screenshot, annotated screenshot, or attachment). Fetch the URL directly with no extra headers.

Required scope: read

Parameters

Name	Type	Description
`ticket_id`	`string`
`asset`	`'screenshot' \| 'screenshot_with_annotations' \| 'attachment'`
`attachment_id`	`string?`	Required when asset='attachment'.

Returns

{ url: string }

Errors

ticket_not_found
asset_not_found
forbidden

`list_comments` read

Lists comments on a ticket in chronological order. Use before posting a new comment so you know what has already been said.

Required scope: read

Parameters

Name	Type	Description
`ticket_id`	`string`

Returns

Array of comments with author, body, timestamps.

Errors

ticket_not_found
forbidden

`get_annotations` read

Returns the structured vector shapes the user drew on the screenshot, with coordinates in image-natural pixel space. For the rasterized image, use get_capture_asset(asset='screenshot_with_annotations').

Required scope: read

Parameters

Name	Type	Description
`ticket_id`	`string`

Returns

Array of annotation shapes (circles, arrows, strokes, redactions, text boxes).

Errors

ticket_not_found
forbidden

`list_members` read

Lists members of a company with their user ids, names, emails, and roles. Required before assign / unassign tools, which take ids not names.

Required scope: read

Parameters

Name	Type	Description
`company_id`	`string`

Returns

Array of members.

Errors

company_not_found
forbidden

`list_capture_assets` read

Lists every capture asset on a ticket (screenshot, annotated overlay, attachments) without downloading bytes. Use get_capture_asset to fetch a specific asset's bytes.

Required scope: read

Parameters

Name	Type	Description
`ticket_id`	`string`

Returns

{ ticket_id: string, assets: Array<{kind, id?, url?}> }

Errors

ticket_not_found
forbidden

`search_tickets` read

Full-text search across tickets the token can see. Query must be at least 2 characters.

Required scope: read

Parameters

Name	Type	Description
`query`	`string`	Min 2 chars.
`company_id`	`string?`
`project_id`	`string?`
`assignee_id`	`string?`
`limit`	`number?`	Max 100.
`cursor`	`string?`

Returns

Paginated search results.

Errors

unauthorized
invalid_query

Write tools

Use these to post comments, edit tickets, move them between columns or projects, and manage assignment.

`add_comment` write

Posts a comment to a ticket. UI shows the MCP token label alongside the user who owns the token.

Required scope: comments

Parameters

Name	Type	Description
`ticket_id`	`string`
`body`	`string`	Markdown supported.

Returns

Created comment with author attribution.

Errors

ticket_not_found
forbidden
rate_limited

`create_ticket` write

Creates a new ticket in a project. Useful for filing bugs an AI agent discovers while working through other tickets. Text-only, no screenshot. To attach a screenshot, capture from the Chrome extension.

Required scope: tickets:write

Parameters

Name	Type	Description
`project_id`	`string`
`title`	`string`
`description`	`string?`	Markdown supported.
`column_id`	`string?`	Defaults to the lowest-order column (To Do).

Returns

Full ticket (DevTools fields trimmed for write responses).

Errors

project_not_found
forbidden
validation_error

`update_ticket` write

Edits a ticket's title, description, resolved state, and / or branch name. Only fields you provide are changed.

Required scope: tickets:write

Parameters

Name	Type	Description
`ticket_id`	`string`
`title`	`string?`
`description`	`string?`
`resolved`	`boolean?`	Resolved is independent of archived.
`branch_name`	`string?`	Pass empty string to clear. For most cases prefer start_work_on_ticket.

Returns

Updated ticket.

Errors

ticket_not_found
forbidden
validation_error

`start_work_on_ticket` write

Records the git branch a ticket (or a small bundle of related tickets) is being worked on. Generates a slug from the title for a single ticket; requires an explicit branch_name when bundling 2 or more.

Required scope: tickets:write

Parameters

Name	Type	Description
`ticket_ids`	`string[]`	1 to 10 ticket ids.
`branch_name`	`string?`	Required when ticket_ids has more than one id.

Returns

{ branch_name, tickets: Array<{ticket_id, ok, ticket?, error?}> }

Errors

validation_error
ticket_not_found
forbidden

`archive_ticket` write

Archives a ticket. Removes it from the board into the archive view. Reversible via restore_ticket. Different from delete: data, comments, and capture context are retained.

Required scope: tickets:write

Parameters

Name	Type	Description
`ticket_id`	`string`

Returns

Updated ticket.

Errors

ticket_not_found
forbidden

`restore_ticket` write

Restores an archived ticket back to the board, into the column it was archived from.

Required scope: tickets:write

Parameters

Name	Type	Description
`ticket_id`	`string`

Returns

Updated ticket.

Errors

ticket_not_found
forbidden

`move_ticket` write

Moves a ticket to a different column (same project) or project (same company). Cross-company moves are forbidden.

Required scope: tickets:write

Parameters

Name	Type	Description
`ticket_id`	`string`
`target_column_id`	`string?`
`target_project_id`	`string?`

Returns

Updated ticket.

Errors

ticket_not_found
column_not_found
cross_company_move_forbidden
validation_error
forbidden

`bulk_move_tickets` write

Moves up to 50 tickets to the same destination in one call. Best-effort, partial failures reported per ticket.

Required scope: tickets:write

Parameters

Name	Type	Description
`ticket_ids`	`string[]`	1 to 50 ticket ids.
`target_column_id`	`string?`
`target_project_id`	`string?`

Returns

{ results: Array<{ticket_id, ok, ticket?, error?}> }

Errors

validation_error
forbidden

`assign_ticket` write

Assigns users to a ticket. mode='add' appends; mode='replace' overwrites.

Required scope: tickets:assign

Parameters

Name	Type	Description
`ticket_id`	`string`
`user_ids`	`string[]`
`mode`	`'add' \| 'replace'`

Returns

Updated ticket with assignees.

Errors

ticket_not_found
user_not_in_company
forbidden

`unassign_ticket` write

Removes users from a ticket.

Required scope: tickets:assign

Parameters

Name	Type	Description
`ticket_id`	`string`
`user_ids`	`string[]`

Returns

Updated ticket.

Errors

ticket_not_found
forbidden

`bulk_assign_tickets` write

Assigns the same set of users to up to 50 tickets in one call. Best-effort, partial failures reported per ticket.

Required scope: tickets:assign

Parameters

Name	Type	Description
`ticket_ids`	`string[]`	1 to 50 ticket ids.
`user_ids`	`string[]`
`mode`	`'add' \| 'replace'`

Returns

{ results: Array<{ticket_id, ok, ticket?, error?}> }

Errors

validation_error
forbidden

Common patterns

Discover the project tree

list_companies → pick a company id
list_projects(company_id) → pick a project id
list_columns(project_id) → pick a column id
list_tickets(project_id, column_id) → ticket ids

You usually only need to do this once per session. Most skills cache the company / project / column ids from the first round and reuse them.

Work a ticket end-to-end

get_ticket(ticket_id, include=['capture','comments','annotations'])
get_capture_asset(ticket_id, asset='screenshot_with_annotations')
get_annotations(ticket_id)
start_work_on_ticket([ticket_id])
[edit code locally]
add_comment(ticket_id, body='Fixed in branch t-…')
move_ticket(ticket_id, target_column_id=in_review_id)

Bulk operations

bulk_move_tickets and bulk_assign_tickets cap at 50 ticket ids per call. They call sequentially to stay inside the per-token write rate limit (60 / min). Failures on one ticket do not roll back others; results come back as a per-ticket array.

Search

search_tickets requires a query of at least 2 characters. Scope with company_id, project_id, or assignee_id to narrow results.

Scope quick reference

Scope	Tools
`read`	`list_companies`, `list_projects`, `list_columns`, `list_tickets`, `get_ticket`, `get_capture_asset`, `list_comments`, `get_annotations`, `list_members`, `list_capture_assets`, `search_tickets`
`comments`	`add_comment` (plus all `read`)
`tickets:write`	`create_ticket`, `update_ticket`, `archive_ticket`, `restore_ticket`, `move_ticket`, `bulk_move_tickets`, `start_work_on_ticket` (plus `read` and `comments`)
`tickets:assign`	`assign_ticket`, `unassign_ticket`, `bulk_assign_tickets` (plus `read`)

See Tokens & scopes for details on choosing the right scope set.