MCP Tools

All internal file and asset interactions must use MCP tools: do not use HTTP endpoints for Runnit files or assets.

Configure optional tracking

configure_tracking accepts optional time and expenses fields. Use true or false for an explicit choice, or null to follow Finance activation again. Organisation settings permission is required; client-scoped sessions cannot change workspace settings. The result contains resolved tracking values. The equivalent organisation PATCH and expense-options GET are available through call_public_api. See tracking API details.

log_time and draft_expense require their tracking feature to be enabled. Task completion still works with time tracking off, without recording hours. Switching tracking off retains history and existing access rules. Expense claims also require a configured billing entity and categories.

Read supplier spend

get_supplier includes spendYearByCurrency: separate totals with the original bill currency and exact minor-unit amount. Keep each currency separate. The supplier’s default currency does not convert the figures. An empty array means no included bills; an absent array means you lack complete cost access. The legacy spendYear value is omitted for mixed currencies. See supplier summary rules for dates, permissions and the matching public list through call_public_api.

Authentication modes

Two user-scoped credential types work with every tool: short-lived MCP session tokens (mcps_...) from Agent Connectivity, and long-lived per-user API keys (rnk_...) from Settings → API Keys. See API Keys & Authentication.

Runnit supports two ways to present the credential:

1. External MCP clients (Claude Code, Codex CLI, Gemini CLI, Cursor, VS Code Copilot Agent mode, generic streamable HTTP clients) send it once as an Authorization: Bearer ... header. In this mode, tool calls omit apiKey.
2. Payload-based workflows that cannot set per-server MCP headers. In this mode, every tool call must include the apiKey argument taken from the workflow input payload.

Caution

For payload-based workflows, MCP tool calls fail without the apiKey argument. Use the field name apiKey (not the deprecated organizationApiKey), and pass the actual token value: never the literal string {{apiKey}}.

The credential is an opaque string prefixed with mcps_ (session token) or rnk_ (API key). Treat it as a secret: do not parse or split it. It reflects the owning user’s permissions, resolved live on every call. Session tokens are short-lived, so payload-based workflows should always read the current apiKey from this run’s input rather than reusing a previous token.

Client-scoped sessions keep project lists, details and related reads within the selected active client. This includes tasks, milestones, members, contributors, comments, history, schedule and time entries, costs and linked project files. Internal sessions select projects without a client. Counts and totals use the same boundary before limits. Arguments cannot expand it, and call_public_api is unavailable to these sessions. See project read scope.

Example: extracting and using apiKey

Given this input:

{
  "apiKey": "mcps_9f2c8a1b...",
  "jobCollectionId": "91c52864-fd2b-4732-9f53-fd6d28606482"
}

A payload-based tool call must include the actual token value:

{
  "tool": "read_file",
  "arguments": {
    "apiKey": "mcps_9f2c8a1b...",
    "collectionId": "3e7c3220-7f08-4754-8f8c-d93ca946eb3d",
    "fileName": "brand_guidelines.md"
  }
}

Results reflect user permissions

A read may legitimately return fewer items, or an empty/forbidden result, if the connected user lacks permission. That is expected behaviour, not an error to retry.

Tool groups

• Project management (read): projects, tasks, comments, schedules, milestones, costs, clients, users, jobs, briefs, project history. See Reading Data.
• Write tools: create and update projects, tasks, milestones, briefs, staff, clients, rate cards, and collections. See the write tools section below.
• Files & assets: create, update, read, list, link, unlink, search, delete.
• DAM discovery: search_assets (hybrid semantic + structured search) and find_similar_clients (brand/tone-of-voice similarity).
• Generation: image and video generation/editing.
• Web: scrape_url, crawl_website. These fetch public websites only: an address with no domain name, an IP address, or a private, local or internal address is refused with “That address could not be fetched. Runnit only fetches public websites.” Crawler failures return reason: fetch_failed with a web service failure message; timeouts return reason: timeout with a timeout message. Neither means the address is private. Continue with other available sources and disclose missing evidence. Each organisation has a daily web fetch allowance; once it is used, the tools reply “This organization has reached today’s web fetch limit.” and Ru continues without fetching. A crawl counts as one fetch. An organisation owner or admin can block sites under Organisation Settings > Security > Web access; a blocked site is refused with “This site is blocked by your organization. An admin can change this under Settings > Web access.” Every other public site is fetched without asking; trusted and unlisted only label the organisation’s fetch record. See Advanced Settings.
• Approvals: list, read, decide, create, and cancel approval requests, manage a standing delegation, and request project activation approval. See the approvals section below.
• Complete REST API coverage: call_public_api for documented /api/v1 operations that do not have a dedicated MCP tool.

User-authored components use a separate sandbox tool policy. They start with a read-only subset; explicitly granted runtime tools and runtime AI have additional checks. Studio’s saved disabled-tool list takes precedence over component grants and applies to public pages, previews and builder data checks. A refused call returns ok:false with error.kind: "forbidden"; authors should show that failure instead of treating it as an empty result. Direct calls using your generated REST or MCP credential retain your normal permissions. See Studio tool restrictions.

• Indexing health: get_indexing_health reports whether files are indexed and searchable by content (counts by status and index quality, scanned documents awaiting OCR, last sweep run). These aggregate counts include protected files without their names or contents. reindex_assets queues a collection or specific files for re-indexing and can opt them into OCR. Bulk repairs are refused before changes if you lack access to a receipt in the request.

Complete REST API coverage

Use call_public_api when you need a documented public API operation that has no dedicated MCP tool. This includes operations such as board and workflow stage management, report exports, closure dates, master project changes, saved views, permission administration, asset folders, tags and versions, and user imports.

Prefer a named MCP tool when one exists. Named tools have smaller schemas and responses designed for AI clients. call_public_api is the complete-coverage fallback and follows the relevant REST API reference.

Argument	Use
method	GET, POST, PUT, PATCH, or DELETE. It defaults to GET.
path	The path after /api/v1, beginning with one slash. For example, /organizations/<organisation-id>/boards.
query	Optional query values. Arrays create repeated query parameters.
body	Optional JSON request body. Do not use it with multipart.
multipart	Optional form fields and base64-encoded files for upload endpoints. Do not use it with body.
accept	Optional response media type.
confirm	Required as true for every non-GET request.

For example, list an organisation’s boards:

{
  "method": "GET",
  "path": "/organizations/<organisation-id>/boards"
}

To change data, review the matching API reference first and confirm the call:

{
  "method": "PATCH",
  "path": "/projects/<project-id>",
  "body": {
    "name": "Updated project name"
  },
  "confirm": true
}

The result includes the HTTP status and response body. JSON is returned in data, text and CSV in text, and other binary content in bodyBase64 with encoding: "base64". Request and response bodies are limited to 25 MiB, and the request times out after 60 seconds. Redirects are returned without being followed.

The public API still applies the connected user’s current permissions, organisation binding, client assignments, resource grants, validation, rate limit, and audit attribution. An MCP session token cannot authenticate the REST API directly. The tool performs the authorised bridge call on its behalf.

Note

call_public_api accepts tokens generated from Agent Connectivity and per-user rnk_ API keys. It is unavailable to restricted internal sessions, such as sessions limited to a client, job, automation, or specific tool list. Those sessions keep their named-tool limits.

Image and video generation

Call generation tools when the user has requested that creative work. Creating or scheduling a project does not itself request concept imagery. Future creative deliverables in a project brief can be represented as tasks.

Omit the model argument from generate_image, edit_image, generate_video, and generate_video_from_image unless you have a specific supported model ID. Runnit selects the configured model for that capability and normalises supported friendly names.

Generation follows the active organisation’s AI billing mode. A credit organisation needs enough balance for the estimated request. An own-key organisation needs its fal.ai credential under Settings → AI API Keys and never falls back to a platform key. See AI Credits for the organisation workflow.

Files and folders

read_document reads the current file content. After updating or restoring a file, call it again with the same asset ID to read that content. Saved text is reused only when the file content, filename and format still match. See Reading data.

Collections can organise files into folders. File tools address folders with a folderPath argument: a slug path such as /campaign-assets/q3. Display names also work ("Campaign Assets/Q3" is normalised to the same path), and paths are matched case-insensitively.

• list_files returns folders (the file’s folder paths) and primaryFolder for every file (folders is empty for files at the collection root), and accepts an optional folderPath argument to list only that folder.
• read_file accepts an optional folderPath to pick the right file when the same name exists in more than one folder. Without it, the most recently updated match anywhere in the collection is returned; the response includes folders and primaryFolder so you can see which one you got.
• create_or_update_file accepts an optional folderPath to file the document into a folder, creating missing folders automatically. With a folderPath, only a same-named file in that folder is updated; same-named files elsewhere in the collection are left alone.
• save_asset_to_collection accepts an optional folderPath to file the copy into a folder of the target collection. Repeating a save of the same source to the same folder and file name returns the existing saved asset, including a copy saved automatically by Ru. Unrelated files with the same name stay separate. Source-read and destination-write permissions are checked on every call. Use update_file to revise the saved content.

Use link_asset and save_asset_to_collection for requested attachment or reuse, and to preserve source documents supplied for the current workflow. Finding a relevant historical concept during research does not authorise attaching it to a new project.

Copies retain the source’s AI creator attribution. To make an existing file available on a project, use link_asset. It reuses a file already visible there, including images generated in that project’s conversation. Use save_asset_to_collection when you need the file in a particular collection. See asset linking.

File creation and update record the connected user as the author. A rejected file write returns isError: true. Application failures include code and statusCode in the text result. For KNOWLEDGE_CONTENT_CAPACITY_EXCEEDED (413), contact support about retained file history. For KNOWLEDGE_CONTENT_TOO_LARGE (413), reduce the file content. These errors leave the file content unchanged. The same errors are available through the Assets API.

When create_file returns brandCopy, that file is already in the reported collection. If copyToBrandCollectionId equals collectionId, both results refer to the same asset.

Private files appear in listings and search only when you can read them. read_file and read_document use the same access with an ordinary user-generated credential when you uploaded it, own a conversation it is attached to, or are an owner or admin of the authorising organisation. You still need permission to view assets. Finance documents require their Finance permissions. Access to the file does not give access to the conversation.

Internal sessions limited to a job, client or tool set continue to reject private-file reads, except for the assigned receipt in an active receipt-reading task. Expense receipts follow live claim permissions and cannot be copied into other collections or opened through public viewer links. See Private files.

Write tools

The server exposes write tools that create and change Runnit data. Every write tool enforces the connected user’s live permissions, so a call fails when the user lacks the required access in the app.

Project record forms

Use these tools with your generated connection to manage structured project details. Named tools and call_public_api use the organisation bound to that connection; your memberships in other organisations do not extend it. Record forms must be enabled for your organisation. You need form management to edit or publish a definition, and project edit access to change an attached record.

Tool	Use
list_record_forms, get_record_form	Find published forms and read their fields and draft revision.
edit_record_form_draft	Apply typed draft changes using expectedDraftRevision.
publish_record_form	Preview a publication, then confirm the same draft revision.
attach_project_record_form, get_project_record	Attach a published form or read the current project details.
set_project_record_values	Save a partial patch with expectedRecordRevision.
upgrade_project_record	Adopt the latest version, providing values for new required fields.
detach_project_record_form, restore_project_record	Preview and confirm detachment, or restore saved values.

Client-scoped sessions can use get_project_record only for their selected active client. Internal scope reads projects without a client. Form definitions and all record changes are unavailable in client-scoped sessions, including confirmation previews. A component grant does not remove this restriction.

A date change during an upgrade can return FIRM_MILESTONES_AFFECTED with the milestones that would move. Confirm those changes before retrying with confirmFirmMilestones: true. Keep other business refusal codes separate from revision conflicts. See the record API for field values, financial privacy, revisions and lifecycle behaviour. Form authoring is available through these named tools; it has no /api/v1/forms route.

Projects and milestones

Project record summaries return completeness: null and completenessFinanciallyRedacted: true when a budget mapping requires financial access. Show the status as unavailable. Record saves through call_public_api preserve business refusal codes; BUDGET_MANAGED_BY_OBJECT requires the Finance budget workflow, rather than a revision retry. See the record response contract.

Project creation, updates and deletion, milestone creation, updates and deletion, and request_project_activation_approval require an unscoped user-generated connection. Client-scoped sessions, including Internal scope, cannot use these actions or their confirmation previews. A component tool grant does not remove this restriction. Keep the session’s client scope when handling a refusal.

Tool	Purpose	Required access
create_project	Create a project. The description field is the project’s brief record: the markdown shown on the project’s Brief tab. When the project needs a brief, write the full brief there rather than saving it as a file. Optional workflowStage (stage id or name, draft-category only) chooses the entry stage, for example a pipeline’s Enquiry. A successful result contains a read-after-write verified project and canonical projectUrl. Use projectUrl verbatim in user-facing links. If verification fails, do not invent a URL and retry only when retryable is true.	Project creation
update_project	Update a project’s fields. The description field is the project’s brief record (the Brief tab), so this is also the tool that writes or updates a project’s brief. Cannot set the status to archived (archiving happens in the app), and archived projects reject writes. When the organisation requires activation approval, moving a draft project to active returns a structured APPROVAL_REQUIRED or APPROVAL_PENDING result instead of an opaque failure; use request_project_activation_approval to proceed.	Project update
delete_project	Delete a project and everything in it. Destructive.	Project deletion
create_milestone / update_milestone / delete_milestone	Manage project milestones. update_milestone also takes an achieved flag: true marks the milestone achieved and stops its due and overdue notifications, false reopens it. You do not need to do this before closing a project, because moving a project to done or completed closes out its open milestones for you. delete_milestone is destructive.	Project update

Tasks

create_task, set_task_dependencies, update_task, update_task_status, create_task_comment and delete_task require an unscoped user-generated connection. Client-scoped sessions, including Internal, cannot use these actions or deletion previews. A component tool grant does not remove this restriction. Keep the session’s scope when handling a refusal. Normal task permissions still apply to unscoped connections.

Tool	Purpose	Required access
create_task	Create a task in a project. Only name is required; assignment, estimate, and planned start are optional. A schedule is built only when plannedStartDate is supplied. Dependencies are validated before the task is saved. A dependency or schedule failure does not retain the new task, so the call can be retried without creating a duplicate.	Task creation; task assignment when choosing an assignee; task-wide update plus schedule management when adding dependencies
update_task	Update task fields. A start creates or rebuilds the schedule and moves a pending backlog task to scheduled. An estimate change on a task with a day-by-day breakdown keeps the planned window and rescales the daily hours when the new total fits it; otherwise the schedule rebuilds from the start. An estimate-only or assignment-only change keeps an undated task unscheduled; reassignment moves any existing schedule ownership. The result includes task and its pre-change previousTask snapshot for follow-up edits or reversals.	Assigned-task or task-wide update for general fields; task assignment for reassignment; task-wide update plus schedule management for dates and estimates
update_task_status	Change status and optional whole-number progress using the same start, completion, reset, cancellation, and reopen rules as the app. Completion can include actual hours and notes. The result includes task and its pre-change previousTask snapshot.	Assigned-task update, project ownership, or task-wide update access
delete_task	Delete a task. Destructive.	Task deletion or project owner/admin override
create_task_comment	Add a comment to a task. Comments post into the task’s chat thread, so they notify the assignee, project owner, and other participants, and can be replied to in the app.	Task comments
involve_user	Pull a person into a task or project: posts a message into its chat thread with an @mention of them, so they are notified with a link and can reply there. Provide exactly one of taskId or projectId. Fails if the person cannot already see the work.	Task comments (tasks) or project view (projects); the mentioned person needs access to the project
post_project_note	Post a note into a project’s chat thread authored as Ru rather than as the acting user. Meant for a durable record of assumptions, decisions, and trade-offs made while working on the user’s behalf. Fails on archived projects.	Project view; the acting user must be able to post in the project’s chat
set_task_table_values	Set custom table-column values on a task. Values are validated against the project’s effective columns; use list_table_columns first for keys, types, and dropdown option keys.	Project owner, project admin, or organisation manager
create_table_column	Create a custom table column on a project, or at client/organisation scope so it appears on every matching project. Supports all eight column types and the optional settings.ai block that makes it an AI-filled column.	Project owner, project admin, or organisation manager; shared scopes also need the shared table columns permission
fill_table_column	Run the AI fill for a column with an enabled ai block. Targets specific taskIds, only empty cells (onlyEmpty), only cells whose task inputs and instruction changed (onlyStale), or every task (max 100). Values are validated like manual input and stamped with per-cell provenance.	Project owner, project admin, or organisation manager
set_task_allocations	Replace a task’s day-by-day hour breakdown (manual schedule mode). Sets the planned window to the allocation dates and rebuilds schedule segments. Prefer create_task or update_task with estimatedHours for automatic scheduling.	Task-wide update plus schedule management, or project owner/admin override
set_task_dependencies	Replace a task’s finish-to-start dependency list (same project, max 25, cycles rejected). The task and its transitive dependents are forward-shifted through the scheduler; returns the cascade summary. create_task also accepts dependsOn directly.	Task-wide update plus schedule management, or project owner/admin override

plannedEndDate is calculated from planned start and estimated hours. Do not send it to update_task.

When a scheduled create_task call omits estimatedHours, Runnit uses one day from the organisation’s Daily capacity setting, with 8 hours as the fallback. Name-only tasks return an empty scheduleSegments array.

Schedule

Tool	Purpose	Required access
block_out_dates	Mark a date range (inclusive, up to 366 days) as unavailable for a user, with an optional type (leave, appointment, other) and reason. Optional hoursUnavailable (greater than 0, less than 24) makes the block partial: that many hours per day are unavailable and the scheduler books at most the remaining capacity; omit it for whole days. Partial blocks on the same day stack, and hours at or above the organisation’s daily capacity block the whole day. To express “hours available”, subtract from the daily capacity first. When conflicting work is booked on the dates, resolution decides the outcome: flag (the default) leaves the bookings in place and raises conflict warnings; replan refits work to the remaining hours and moves the excess to the next available working days, cascading dependants. The response includes the conflict or replan report; surface it to the user, and never choose replan without their explicit confirmation.	Own dates: any member. Another user’s dates: schedule management
update_blocked_dates	Change an existing blocked-dates entry by blockId: move or resize the range, change the type or reason, or adjust hoursUnavailable (a number sets partial hours, null converts the entry to whole days, omitting leaves it unchanged). Only days the change makes stricter (newly covered, newly whole-day, or increased partial hours) re-run the conflict flow with the same resolution choice; loosening or shrinking never moves scheduled work. Never choose replan without the user’s explicit confirmation.	Own entries: any member. Another user’s entries: schedule management
remove_blocked_dates	Delete a blocked-dates entry by blockId, freeing that capacity. Removing a block never pulls already-scheduled work earlier; replan tasks explicitly if the freed days should be used.	Own entries: any member. Another user’s entries: schedule management

| set_work_pattern | Record how many hours a person works on each weekday, from a date onwards. Send hoursByWeekday as seven numbers starting on Monday, where 0 means they do not work that day. This is the person’s ordinary week, not an absence: use block_out_dates for leave. The change takes effect from effectiveFrom and closes the previous pattern the day before, so earlier weeks keep the hours they had. | Own pattern: any member. Another user’s pattern: schedule management |

The matching read tools are get_blocked_dates and get_work_pattern. See Reading Data.

Working patterns and blocked dates answer different questions. A pattern is the baseline capacity of somebody’s ordinary week and repeats until you change it. A blocked date is a dated exception to that baseline. Leave is subtracted from the pattern, so four hours of leave on a four-hour Friday removes the whole day.

Briefs

Tool	Purpose	Required access
create_brief_session	Create a Brief Builder session, optionally prepopulated with brief markdown and source files. Returns the session id and a Brief Builder link. A session is the standalone intake for new work: its handoff plans and creates its own new project. Do not create one for a project that already exists; write that project’s brief into its description with update_project instead.	Brief creation
update_brief_draft	Replace the draft markdown of a Brief Builder session. The new draft appears in the owner’s open Brief Builder tab.	Brief editing; session owner or organisation admin
create_from_capture	Turn captured page content (an email chain, a document, an article) into Runnit work. A server-side model identifies the client from your active client list and judges whether the requirements are adequate for planning. Mode auto creates a Brief Builder session and returns a recommendation without starting planning. Mode plan requires an explicit clientOrganizationId and starts planning immediately. Mode brief creates and evaluates a brief session. The model can only nominate clients from your active list; anything else is saved without a client for you to choose.	Brief creation
start_brief_planning	Hand a Brief Builder session to analysis and resource planning. Creates the planning job that ends in a draft project with a full plan (tasks, milestones, team, tentative schedule). Optionally set or change the session’s client first, and pass additionalNotes to append an Additional notes section the planner reads. Calling it again for the same session returns the existing job instead of planning twice. Archived sessions and sessions marked to skip AI planning are refused. Destructive; requires confirmation.	Brief creation; session owner or organisation admin

Boards and workflow stages

Tool	Purpose	Required access
list_boards	List visible kanban boards with their columns and stage mappings.	Organisation membership
list_workflow_stages	List the organisation’s workflow stages and categories.	Organisation membership
create_board	Create a board from named columns; missing stages are created with a category in the same step. Optional members (ids or emails) and memberGroups (group ids, slugs, or exact names) limit the board to those people and groups. Optional taskTableColumns sets the default task-table columns for projects on the board. Optional recordFormId sets the board’s details form, and records ({"newCardWorkspaceMode": "lean"}) makes projects created through the board open as lean records. Optional cardLabel (a short singular noun, at most 40 characters) renames what the board calls its cards, and offerBriefBuilder: false makes card creation skip the Brief Builder chooser.	Kanban management
update_board	Rename a board, change its client scope, replace its columns, replace its audience (members and memberGroups form one audience; [] for both reopens it to everyone), set taskTableColumns (the default task-table columns for projects on the board; null reverts to the organisation default, and the default board always follows the organisation setting), set recordFormId, set records ({"newCardWorkspaceMode": "lean"} for lean records; null reverts to full projects), set cardLabel (what the board calls its cards; null reverts to “project”), or set offerBriefBuilder (false skips the Brief Builder chooser when creating cards; true or null restores it).	Kanban management
list_user_groups	List the organisation’s user groups with member counts, for resolving memberGroups references.	Organisation membership
manage_workflow_stages	Add, rename, or delete workflow stages. Deletions are destructive and require confirmation with a reassignment stage.	Kanban management
delete_board	Delete a board (a view; projects and stages are untouched). Destructive; requires confirmation.	Kanban management

Board and stage writes are not available to client-scoped sessions, and list_boards shows a client-scoped session only the default board plus that client’s boards.

Staff

Tool	Purpose	Required access
invite_staff	Invite a person to the organisation at or below your own role (only an owner can invite an owner). Returns emailSent; the invitation link is emailed and never returned. Non-production datasets create the invitation without sending email.	Member management
update_staff_role	Change a member’s organisation role. Only an owner assigns or changes owner, admins assign up to admin, you can’t change your own role, and the last active owner can’t be demoted. Refusals return the reason.	Role management
archive_staff	Remove a member from the organisation (archive the membership). Called without confirm, it returns the work the person holds (heldWork) and whether a handover is required. When work is held, pass handover: { reassignToUserId } (or reassignToEmail) to move everything to one person, or handover: { unassign: true } to leave tasks unassigned; owner-type records then pass to you. An admin can’t archive an owner, you can’t archive yourself, and the last active owner can’t be archived. It does not delete the user account or revoke a pending invitation. Destructive.	Role management
reassign_member_work	Move one person’s open tasks to another person, or unassign them, in bulk. Optional projectIds limit the move and includeProjectOwnership also transfers the projects they own. Never archives anyone; use it to split a handover across several people before archive_staff. Preview without confirm. Refused when the new person isn’t allowed on one of the projects. Destructive.	Task assignment, admin or owner
update_staff_profile	Update your profile, or a member’s profile when you are an active admin/owner in the connection’s organisation. Basic and portfolio changes save together; if either fails, neither changes.	Self or member management
add_staff_history_entry / update_staff_history_entry / delete_staff_history_entry	Manage a member’s work-history entries.	Member management

An invitation remains valid when invite_staff returns emailSent: false. The tool never returns the link; an owner can copy it from the Organization Users page or resend the invitation.

Clients

Tool	Purpose	Required access
create_client / update_client	Create or update a client relationship.	Client management
remove_client	Remove a client relationship. Destructive.	Client management

Rate cards

Tool	Purpose	Required access
list_rate_card_roles / list_client_rate_cards	Read rate-card data.	Financial reporting
create_rate_card_role / update_rate_card_role / archive_rate_card_role	Manage rate-card roles.	Organisation settings management
create_client_rate_card / update_client_rate_card	Manage client rate cards.	Organisation settings management

Approvals

Tool	Purpose	Required access
list_approvals	List approvals: waiting (on the caller), requested (by the caller), or all (managers only).	Approvals viewing
get_approval	Full detail of one approval: snapshot, approvers and decisions, linked records, audit timeline, and whether the caller can decide.	Approvals viewing
decide_approval	Record the caller’s decision (approved, rejected, or changes_requested with a required comment) on an approval where they are a pending approver on the active stage. First decision wins; repeating it is idempotent.	Approvals viewing
create_approval	Create a standalone approval with named people and groups and an all / any / quorum policy, or sequential stages.	Approvals management
cancel_approval	Withdraw a pending approval. Requester or manager.	Approvals viewing
set_approval_delegation	Set the caller’s standing delegation: new approvals assigned to them go to the delegate, optionally until an end date.	Approvals viewing
clear_approval_delegation	Revoke the caller’s standing delegation.	Approvals viewing
request_project_activation_approval	Create the activation approval for a draft project blocked by APPROVAL_REQUIRED.	Project update

An approval is visible to its requester, its approvers, and approvals managers; other members receive a not-found result. See the Approvals API for the matching REST routes.

Time and finance

Tool	Purpose	Required access
log_time	Record a draft time entry for the caller against a task or a budget line, with the day, minutes, note and billable flag. Never logs time for someone else.	Time logging
submit_timesheet	Submit the caller’s week for approval. Refuses without confirm: true and reports the week’s total first, because a week may approve automatically.	Time logging
get_uninvoiced_work	The uninvoiced work queue: approved time and ready schedule items by client, budget and line, with totals. Never shadow-allowed.	Prices viewing
get_period_checklist	A billing entity’s period and checklist. Current and saved amounts require unrestricted organisation-wide prices; counts and status remain available. Never shadow-allowed.	Close periods, Finance settings, recognition management, prices viewing or invoice issuing

Invoicing adds read and draft tools only: list_invoices, get_invoice, get_receivables, get_client_billing_profile and draft_invoice (composes a draft from approved work, and never issues). Issuing, sending and voiding an invoice are deliberately not exposed as named tools; an integration that needs them calls the REST routes with an API key, which is the account’s own credential and carries the same approval and permission checks.

draft_invoice preserves approved time amounts. When rounded hours would change the net amount, it returns a line with item quantity 1 and includes the minutes in its description. Source time and rates remain available for review. See Invoices and credit notes.

get_payment_status reports credit notes as eligible: false with reason nothing_due. Their positive amountDue is document arithmetic, not collectible debt. Settlement and collection writes through call_public_api refuse credit notes with the same status and validation as the Finance API. Separate client-credit balances can still be applied to ordinary invoices or refunded.

list_time_entries rows carry origin, budgetLineId, billableMinutes, held and writtenOff. update_task_status accepts lockOverrideReason when the completion date is behind the timesheet lock and returns a timeEntry outcome beside the task. Time approvals are decided with decide_approval; the finance routes are in the Finance & Budgets API.

Collections

reindex_assets queues files for re-indexing so they become searchable and drains the queue immediately: pass collectionId or assetIds, scope (problems, the default, or all), and ocr: true to opt the queued files into OCR. OCR is a charged vision call per scanned document, so set it only when the user asked for it. Read queued from the result and follow progress with get_indexing_health.

Tool	Purpose	Required access
create_collection / update_collection	Create or update an asset collection.	Asset upload
delete_collection	Delete an asset collection. Destructive.	Asset upload

Note

AI Directives collections are protected. Creating, updating, or deleting files in an AI Directives collection, or changing the collection itself, additionally requires the connected user to hold the “Manage AI agents” permission. See AI Directives.

Destructive tools require confirmation

delete_project, delete_task, delete_milestone, archive_staff, reassign_member_work, remove_client, delete_collection, and update_staff_role require a confirm: true argument. Called without it, the tool does not act: it returns a preview describing what would happen so the agent can check with the user first, then call again with confirm: true.

For archive_staff, a successful confirmation reports the previous and resulting membership status, whether a pending invitation remains, userAccountDeleted: false, the handover that was applied with its handoverResult counts, and a plain-language effect. Use those fields literally. Archiving a membership is not deletion of the user account, and a member who still holds work can’t be archived without a handover.

Caution

delete_project removes the project and all of its tasks, schedules, and assets. There is no undo. Always review the preview before confirming.

Finance guidance and actions

Use get_finance_guide for the product guides included with this release and get_finance_operations to discover supported reads, actions and their input contracts. read_finance_operation reads a reviewed operation; perform_finance_action performs an authorised change with confirm:true. The same route permissions, approval policies, period locks and financial visibility apply. See Finance workflow tools and Finance with Ru for the boundaries.

Retainer close and invoice operations keep hourly allowances separate from monetary carry credits. The invoice source kind retainer_carry identifies the signed credit or correction. Existing permissions and price visibility apply through REST and MCP. See Retainers.

Pricing adoption is available through the shared Finance routes. Read GET /finance/budgets/:id/quote-pricing-review, then send its reviewHash and a reason to POST /finance/budgets/:id/adopt-quote-pricing. Active budgets open a correction for normal approval. For templates, read GET /finance/budget-templates/:id/pricing-review?sourceBudgetId=..., then send sourceBudgetId, reviewHash and reason to POST /finance/budget-templates/:id/adopt-pricing. Direct REST paths use the /api/v1 prefix. Generated-token MCP callers use the same paths through call_public_api. Management scope, price visibility and evidence validation apply to both. See Budgets for the review workflow.

For a period’s PDF close report, call the public Finance export endpoint with format=pdf. The same export permission and organisation-wide price and cost access apply through MCP. The default format returns the CSV pack. See Finance API for the response contract.

Binary exports are returned as base64 with their content type and attachment filename. The PDF close report also preserves the X-Close-Generation header.

Period checklist supporting records

get_period_checklist includes links to live review queues. To page the supporting records, use call_public_api with GET and /finance/periods/:id/review/:key. It needs the corresponding organisation-wide source permission as well as period read. See the Finance API for fields, paging and failure responses.

update_quote_draft can change a line’s activity, billing type, unit and hours per day. Activity changes adopt its defaults; hour/day changes convert the saved rate using retained day hours. Supply an explicit price to override it. The same rules apply through call_public_api. See the line selection contract.

Finance setup tools

get_finance_setup reads the current workspace’s Finance setup and outstanding checklist, with Finance settings access. configure_finance_usage applies the choice between full Finance and resource planning. It requires both Finance and organisation settings access; enabling follows the Finance plan entitlement. See the Finance usage contract for fields and results. These tools do not send invoices, execute payments, purchase upgrades or grant permissions.

SVG file content

create_file and create_or_update_file accept raw SVG XML or base64 file bytes. read_file and read_file_by_job return isBinary to distinguish the two forms, with fileSize measured in decoded bytes. Preserve that representation when reusing the returned content. For a data URL, decode the base64 payload after its comma. Updates can switch forms and saved versions retain the original bytes.

For downloads through call_public_api, UTF-8 SVG returns text. SVG bytes that cannot round-trip through UTF-8 return bodyBase64, encoding: "base64" and byteLength. Decode the base64 to recover the file. See Assets API.

Supplier-uploaded invoice originals and proposals follow current cost access to all linked purchase records, or organisation cost access when unattached. Linked acceptance needs readable source costs. Named file readers, discovery and the public API bridge preserve these restrictions. See Supplier invoice originals and Supplier upload cost scope.

Supplier-payment recording and reversal keep action permission separate from amount visibility. Response totals need all contributing bill cost scopes; recording also checks selected bills that receive no allocation. Remainders need organisation cost access. Authorised writes can succeed with payment identity and hidden amounts. See supplier payment visibility.

Inclusive credit lines returned by get_invoice or call_public_api keep the original line’s remaining net and tax allocation. The selected amount still includes tax. Partial credits can split net and tax differently from a fresh calculation; read the returned figures. Allocation amounts follow price access. See credit-note entry.