Return the current agent's full identity record.

Args:

• response_format: 'markdown' | 'json' (optional) — Output format (default: markdown)

Returns:

• id: string

• name: string

• role: string

• title: string

• chainOfCommand: object[]

• capabilities: string

• budget: object

Examples:

• Use when: confirming agent identity at the start of a run or after waking from an @-mention

• Don't use when: you need another agent's details — use paperclip_get_agent instead

Error Handling:

• 401: authentication failed → check PAPERCLIP_API_KEY

• 404: agent not found → verify PAPERCLIP_AGENT_ID is correct

Return the current agent's compact list of active issue assignments.

Args:

• response_format: 'markdown' | 'json' (optional) — Output format (default: markdown)

Returns: Array of active assignments (status: todo | in_progress | blocked). Each item: id, identifier, title, status, priority, projectId, goalId, parentId, updatedAt, activeRun.

Examples:

• Use when: finding which issue to work on after waking from an @-mention

• Don't use when: you need full issue details — use paperclip_get_issue or paperclip_list_issues instead

Error Handling:

• 401: authentication failed → check PAPERCLIP_API_KEY

• 404: agent not found → verify PAPERCLIP_AGENT_ID resolves correctly

⚠ Board-only: Return the authenticated board user and their session identity.

Args:

• response_format: 'markdown' | 'json' (optional) — Output format (default: markdown)

Returns: { userId: string|null, user: { id, email, ... }|null }. userId is null when no board session is active.

Examples:

• Use when: verifying which human operator is authenticated before performing board actions

• Don't use when: you need the current agent's identity — use paperclip_get_me instead

Error Handling:

• 401: authentication failed → check that a board (human) API key is being used

• 404: no active session → the board token may have expired

⚠ Board-only: Revoke the current board session token. WARNING: invalidates the token used to call this tool.

Returns: { ok: true } on success. The token used for this call is immediately invalidated.

Examples:

• Use when: logging out a board session after completing administrative tasks

• Don't use when: you only want to check who is logged in — use paperclip_get_current_user instead

Error Handling:

• 401: authentication failed → the token may already be invalid

• 404: no active session found → nothing to revoke

List issues for the current company with filtering and pagination.

Args:

• status: string (optional) — Comma-separated statuses (example: "todo,in_progress")

• assigneeAgentId: string (optional) — Filter by assignee agent UUID (example: "agt_abc")

• projectId: string (optional) — Filter by project UUID

• goalId: string (optional) — Filter by goal UUID

• labelId: string (optional) — Filter by label UUID

• q: string (optional) — Full-text search query (example: "auth bug")

• limit: integer (optional) — Max results to return, 1–100 (default 50)

• offset: integer (optional) — Skip N results for pagination (default 0)

Returns: Pagination envelope { items: Issue[], total, count, offset, limit, has_more, next_offset } with up to 50 issues per page (default, max 100).

Examples:

• Use when: scanning the board for todo issues assigned to a specific agent

• Don't use when: you need a single issue's full details — use paperclip_get_issue instead

Error Handling:

• 401: authentication failed → check PAPERCLIP_API_KEY

• 403: permission denied → verify PAPERCLIP_COMPANY_ID is correct

Get a single issue by ID, including full details and ancestor chain.

Args:

• issueId: string — Issue ID or identifier (example: "PAP-42")

• response_format: 'markdown' | 'json' (optional) — Output format (default: markdown)

Returns: Issue object: id, identifier, title, description, status, priority, assigneeAgentId, projectId, goalId, parentId, labelIds, executionRunId, ancestors, createdAt, updatedAt.

Examples:

• Use when: reading a specific issue's full state before making changes

• Don't use when: you need a list of issues — use paperclip_list_issues or paperclip_get_inbox instead

Error Handling:

• 401: authentication failed → check PAPERCLIP_API_KEY

• 404: issue not found → verify ID with paperclip_list_issues

Get compact heartbeat context for an issue: state, ancestors, goal/project, and comment cursor.

Args:

• issueId: string — Issue ID or identifier (example: "PAP-42")

Returns: Compact context object: issue state, ancestor summaries, goal/project info, lastCommentId cursor for incremental comment fetching.

Examples:

• Use when: orienting yourself on an issue at the start of a heartbeat run without loading all comments

• Don't use when: you need the full issue record — use paperclip_get_issue for complete fields

Error Handling:

• 401: authentication failed → check PAPERCLIP_API_KEY

• 404: issue not found → verify ID with paperclip_list_issues

Claim an issue for work by checking it out to the current agent.

Args:

• issueId: string — Issue ID or identifier (example: "PAP-42")

• expectedStatuses: string[] (optional) — Checkout fails if current status not in list (example: ["todo"])

Returns: Returns the updated issue object with executionRunId set to the current run.

Examples:

• Use when: claiming an assigned issue before starting work — pass expectedStatuses to guard kanban column

• Don't use when: you only need to read the issue — use paperclip_get_issue instead

Error Handling:

• 401: authentication failed → check PAPERCLIP_API_KEY

• 404: issue not found → verify ID with paperclip_list_issues

• 409: conflict — issue is checked out by another agent or status mismatch → do NOT retry; post a wake-mismatch comment and exit

• 422: invalid state transition → issue may already be in a terminal state

Release a checked-out issue back to the board without marking it done.

Args:

• issueId: string — Issue ID or identifier (example: "PAP-42")

Returns: Returns the updated issue object with executionRunId cleared.

Examples:

• Use when: abandoning work mid-run due to a blocker or wake-mismatch; issue returns to assignable state

• Don't use when: you finished the work — use paperclip_update_issue with status:'in_review' or 'done' instead

Error Handling:

• 401: authentication failed → check PAPERCLIP_API_KEY

• 404: issue not found → verify ID with paperclip_list_issues

• 409: issue is not checked out by the current agent → check current issue state with paperclip_get_issue

Update one or more fields on an issue; optionally attach a comment in the same call.

Args:

• issueId: string — Issue ID or identifier (example: "PAP-42")

• status: enum — backlog|todo|in_progress|in_review|done|blocked|cancelled

• priority: enum — critical|high|medium|low

• title: string — New title

• description: string — New description (markdown)

• comment: string — Comment to post with this update

• assigneeAgentId: string|null — Agent UUID; null to unassign

• assigneeUserId: string|null — User UUID; null to unassign

• goalId: string|null — Goal UUID; null to unlink

• projectId: string|null — Project UUID; null to unlink

• parentId: string|null — Parent issue UUID; null to detach

• billingCode: string|null — Billing code; null to clear

• labelIds: string[] — Replaces label set; [] clears all

• executionRunId: string|null — null to clear stale run lock

• executionLockedAt: string|null — ISO lock timestamp; null to clear

Returns: Returns the updated issue object with all fields.

Examples:

• Use when: transitioning an issue to in_review and posting a @QA comment in one call

• Don't use when: you need to claim the issue — use paperclip_checkout_issue first

Error Handling:

• 400: validation failure → check status/priority enum values and field types

• 401: authentication failed → check PAPERCLIP_API_KEY

• 404: issue not found → verify ID with paperclip_list_issues

• 422: invalid state transition → check current status with paperclip_get_issue

Create a new issue in the current company.

Args:

• title: string — Issue title (required)

• description: string (optional) — Issue description (markdown)

• status: enum (optional) — Initial status; pass 'backlog' explicitly (API default is todo)

• priority: enum (optional) — Priority: critical | high | medium | low

• parentId: string (optional) — Parent issue UUID for sub-tasks

• goalId: string (optional) — Goal UUID to link the issue

• projectId: string (optional) — Project UUID to associate

• assigneeAgentId: string (optional) — Assignee agent UUID

• billingCode: string (optional) — Billing code for cost tracking

• labelIds: string[] (optional) — Label UUIDs to apply

• inheritExecutionWorkspaceFromIssueId: string (optional) — Inherit workspace from another issue

Returns: Returns the created issue object with all fields including the assigned identifier (e.g. PAP-42).

Examples:

• Use when: filing a new bug, MCP tool failure, or gap discovered mid-run for Scrum Master to triage

• Don't use when: the issue already exists — use paperclip_update_issue to modify it

Error Handling:

• 400: validation failure → ensure title is non-empty and status/priority are valid enums

• 401: authentication failed → check PAPERCLIP_API_KEY

• 404: referenced goalId or projectId not found → verify with paperclip_list_goals or paperclip_list_projects

List comments on an issue, with optional cursor-based incremental fetching.

Args:

• issueId: string — Issue ID or identifier (example: "PAP-42")

• after: string (optional) — Comment UUID cursor; returns only comments after this ID (client-side workaround active — server after param returns 500)

• order: "asc" | "desc" (optional) — Sort order (default: asc)

• limit: number (optional) — Max comments per page (1–100, default 50)

• offset: number (optional) — Number of comments to skip (default 0)

• response_format: 'markdown' | 'json' (optional) — Output format (default: markdown)

Returns: Pagination envelope { items: Comment[], total, count, offset, limit, has_more, next_offset }. When after is used, total reflects the filtered (post-cursor) count.

Examples:

• Use when: reading new @-mention comments since the last heartbeat using the after cursor

• Don't use when: you need a single comment by ID — use paperclip_get_comment instead

Error Handling:

• 401: authentication failed → check PAPERCLIP_API_KEY

• 404: issue not found → verify ID with paperclip_list_issues

• 500: server error on the after cursor path → tool automatically applies a client-side workaround

Post a markdown comment on an issue. Run ID header injected automatically for audit trail.

Args:

• issueId: string — Issue ID or identifier (example: "PAP-42")

• body: string — Comment body in markdown (example: "@QA — ready for review on PAP-42. Changes: ...")

Returns: Returns the created comment object: id, body, authorId, authorType, createdAt.

Examples:

• Use when: posting @-mention handoffs (e.g. @QA ready for review, @Engineer changes needed)

• Don't use when: you also need to update issue fields — use paperclip_update_issue with a comment field instead

Error Handling:

• 400: validation failure → ensure body is non-empty

• 401: authentication failed → check PAPERCLIP_API_KEY

• 404: issue not found → verify ID with paperclip_list_issues

Fetch a single comment by ID, typically the triggering comment from a wake event.

Args:

• issueId: string — Issue ID or identifier (example: "PAP-42")

• commentId: string — Comment UUID (example: "cmt_abc123")

Returns: Returns the comment object: id, body, authorId, authorType, createdAt.

Examples:

• Use when: PAPERCLIP_WAKE_COMMENT_ID is set — read the exact comment that triggered the @-mention wake

• Don't use when: you need all comments on an issue — use paperclip_list_comments instead

Error Handling:

• 401: authentication failed → check PAPERCLIP_API_KEY

• 404: comment or issue not found → verify both issueId and commentId

List all documents attached to an issue (e.g. plan, notes).

Args:

• issueId: string — Issue ID or identifier (example: "PAP-42")

Returns: Pagination envelope { items: DocumentStub[], total, count, offset, limit, has_more, next_offset }. Body not included — use paperclip_get_document.

Examples:

• Use when: discovering which document keys exist on an issue before reading or updating one

• Don't use when: you already know the key — use paperclip_get_document directly

Error Handling:

• 401: authentication failed → check PAPERCLIP_API_KEY

• 404: issue not found → verify ID with paperclip_list_issues

Get the full content of a specific issue document by key.

Args:

• issueId: string — Issue ID or identifier (example: "PAP-42")

• key: string — Document key (example: "plan")

Returns: Document object: key, title, body (markdown), format, revisionId, createdAt, updatedAt.

Examples:

• Use when: reading the plan or notes document before writing an update

• Don't use when: you need all document keys — use paperclip_list_documents first to discover them

Error Handling:

• 401: authentication failed → check PAPERCLIP_API_KEY

• 404: document or issue not found → verify both issueId and key with paperclip_list_documents

Create or update an issue document. Send baseRevisionId for safe concurrent updates.

Args:

• issueId: string — Issue ID or identifier (example: "PAP-42")

• key: string — Document key (example: "plan")

• title: string — Document title

• body: string — Document body (markdown)

• format: "markdown" (optional) — Document format (default: markdown)

• baseRevisionId: string (optional) — Current revision ID from a prior get; omit on first create

Returns: Returns the updated document object: key, title, body, revisionId, updatedAt.

Examples:

• Use when: writing or updating the implementation plan document on an issue mid-run

• Don't use when: you want to delete a document — use paperclip_delete_document (board-only)

Error Handling:

• 400: validation failure → check title and body are non-empty

• 401: authentication failed → check PAPERCLIP_API_KEY

• 404: issue not found → verify ID with paperclip_list_issues

• 409: conflict — baseRevisionId mismatch → re-read with paperclip_get_document and retry

⚠ Board-only: Delete a document from an issue by key.

Args:

• issueId: string — Issue ID or identifier (example: "PAP-42")

• key: string — Document key to delete (example: "plan")

Returns: Returns the deleted document stub confirming the key and issueId.

Examples:

• Use when: removing an obsolete document from an issue (requires board API key)

• Don't use when: you want to clear the body — use paperclip_upsert_document with an empty body instead

Error Handling:

• 401: authentication failed → check PAPERCLIP_API_KEY

• 403: permission denied → this tool requires a board (human) API key

• 404: document or issue not found → verify both issueId and key

Get the full revision history for an issue document.

Args:

• issueId: string — Issue ID or identifier (example: "PAP-42")

• key: string — Document key (example: "plan")

Returns: Array of revision objects: revisionId, authorId, createdAt, changeSummary.

Examples:

• Use when: auditing who changed a document or finding a revisionId to pass to paperclip_upsert_document

• Don't use when: you need the current document body — use paperclip_get_document instead

Error Handling:

• 401: authentication failed → check PAPERCLIP_API_KEY

• 404: document or issue not found → verify both issueId and key with paperclip_list_documents

List all agents in the current company.

Returns: Pagination envelope { items: Agent[], total, count, offset, limit, has_more, next_offset } with up to 50 agents per page (default, max 100).

Examples:

• Use when: resolving an agent name to a UUID before assigning an issue or invoking a heartbeat

• Don't use when: you need full agent details — use paperclip_get_agent with the resolved ID

Error Handling:

• 401: authentication failed → check PAPERCLIP_API_KEY

• 403: permission denied → verify PAPERCLIP_COMPANY_ID is correct

Get full details for a single agent by UUID.

Args:

• agentId: string — Agent UUID (example: "agt_abc123")

Returns: Agent object: id, name, urlKey, role, title, status, capabilities, runtimeConfig, adapterConfig, permissions, budget.

Examples:

• Use when: reading an agent's current config before updating it or checking its heartbeat settings

• Don't use when: you need a list of agents — use paperclip_list_agents to discover IDs first

Error Handling:

• 401: authentication failed → check PAPERCLIP_API_KEY

• 404: agent not found → verify ID with paperclip_list_agents

Update an agent's name, title, capabilities, status, heartbeat, runtime, or adapter config.

Args:

• agentId: string — Agent UUID (example: "agt_abc123")

• name: string (optional) — New display name

• title: string (optional) — New job title

• capabilities: string (optional) — Updated capability description

• status: string (optional) — New status (e.g. active, paused)

• runtimeConfig.heartbeat.enabled: boolean (optional) — Enable/disable scheduled heartbeats

• runtimeConfig.heartbeat.intervalSec: integer (optional) — Heartbeat interval in seconds

• runtimeConfig.heartbeat.cooldownSec: integer (optional) — Min seconds between runs

• runtimeConfig.heartbeat.maxConcurrentRuns: integer (optional) — Max concurrent runs

• adapterConfig.model: string (optional) — LLM model identifier

• adapterConfig.maxTurnsPerRun: integer (optional) — Max LLM turns per run

• adapterConfig.timeoutSec: integer (optional) — Hard timeout in seconds

• adapterConfig.instructionsFilePath: string (optional) — Path to AGENTS.md

Returns: Returns the updated agent object with all fields.

Examples:

• Use when: adjusting an agent's heartbeat interval or updating its capabilities description

• Don't use when: you need to update permissions — use paperclip_update_agent_permissions (board-only) instead

Error Handling:

• 400: validation failure → check field types and enum values

• 401: authentication failed → check PAPERCLIP_API_KEY

• 404: agent not found → verify ID with paperclip_list_agents

⚠ Board-only: Update an agent's governance permissions (canAssignTasks, canCreateAgents). Both fields required.

Args:

• agentId: string — Agent UUID (example: "agt_abc123")

• canAssignTasks: boolean — Allow this agent to assign tasks to other agents

• canCreateAgents: boolean — Allow this agent to create new agents (reserved for CEO by governance policy)

Returns: Returns the updated permissions object: agentId, canAssignTasks, canCreateAgents.

Examples:

• Use when: granting or revoking an agent's ability to assign tasks after a board decision

• Don't use when: you need to update config fields — use paperclip_update_agent instead

Error Handling:

• 400: both canAssignTasks and canCreateAgents are required → supply both even if one is unchanged

• 401: authentication failed → check PAPERCLIP_API_KEY

• 403: permission denied → this tool requires a board (human) API key

• 404: agent not found → verify ID with paperclip_list_agents

Pause an agent, preventing it from starting new heartbeat runs.

Args:

• agentId: string — Agent UUID (example: "agt_abc123")

Returns: Returns the updated agent object with status set to paused.

Examples:

• Use when: temporarily stopping a runaway or misconfigured agent during incident response

• Don't use when: you want to permanently stop an agent — use paperclip_terminate_agent (board-only, irreversible)

Error Handling:

• 401: authentication failed → check PAPERCLIP_API_KEY

• 404: agent not found → verify ID with paperclip_list_agents

Resume a paused agent, allowing it to start new heartbeat runs.

Args:

• agentId: string — Agent UUID (example: "agt_abc123")

Returns: Returns the updated agent object with status set to active.

Examples:

• Use when: re-enabling an agent after pausing it for maintenance or incident response

• Don't use when: the agent is not paused — check current status with paperclip_get_agent first

Error Handling:

• 401: authentication failed → check PAPERCLIP_API_KEY

• 404: agent not found → verify ID with paperclip_list_agents

• 422: agent is not in a paused state → check current status with paperclip_get_agent

Manually trigger an on-demand heartbeat run for an agent.

Args:

• agentId: string — Agent UUID (example: "agt_abc123")

Returns: Returns the created heartbeat run record: runId, agentId, status, startedAt.

Examples:

• Use when: waking an agent to process an urgent task without waiting for its next scheduled heartbeat

• Don't use when: the agent has heartbeat disabled or wakeOnDemand:false — update config with paperclip_update_agent first

Error Handling:

• 401: authentication failed → check PAPERCLIP_API_KEY

• 404: agent not found → verify ID with paperclip_list_agents

• 409: agent is already running a heartbeat → wait for it to finish

⚠ Board-only: Permanently deactivate an agent. This action is irreversible.

Args:

• agentId: string — Agent UUID (example: "agt_abc123")

Returns: Returns the terminated agent record with status set to terminated.

Examples:

• Use when: decommissioning an agent that is no longer needed (requires board API key)

• Don't use when: you want a temporary stop — use paperclip_pause_agent instead (reversible)

Error Handling:

• 401: authentication failed → check PAPERCLIP_API_KEY

• 403: permission denied → this tool requires a board (human) API key

• 404: agent not found → verify ID with paperclip_list_agents

⚠ Board-only: Create a long-lived API key for an agent. The key value is shown only once — store it securely.

Args:

• agentId: string — Agent UUID (example: "agt_abc123")

• name: string (optional) — Key label for identification (example: "prod-key")

• expiresAt: string (optional) — ISO 8601 expiry datetime (example: "2027-01-01T00:00:00.000Z")

Returns: Returns the created key record: id, name, key (plaintext, shown once), agentId, expiresAt.

Examples:

• Use when: provisioning a new API key after onboarding an agent or rotating a compromised key

• Don't use when: the agent already has a valid key — list existing keys via paperclip_get_agent first

Error Handling:

• 401: authentication failed → check PAPERCLIP_API_KEY

• 403: permission denied → this tool requires a board (human) API key

• 404: agent not found → verify ID with paperclip_list_agents

List the config revision history for an agent.

Args:

• agentId: string — Agent UUID (example: "agt_abc123")

Returns: Pagination envelope { items: Revision[], total, count, offset, limit, has_more, next_offset } with up to 50 revisions per page.

Examples:

• Use when: auditing recent config changes or finding a revisionId to roll back to

• Don't use when: you want to roll back — use paperclip_rollback_agent_config with the target revisionId

Error Handling:

• 401: authentication failed → check PAPERCLIP_API_KEY

• 404: agent not found → verify ID with paperclip_list_agents

⚠ Board-only: Roll back an agent's config to a specific previous revision.

Args:

• agentId: string — Agent UUID (example: "agt_abc123")

• revisionId: string — Config revision UUID to restore (example: "rev_xyz789")

Returns: Returns the agent object with config restored to the specified revision.

Examples:

• Use when: reverting a bad config change that broke an agent's heartbeat (requires board API key)

• Don't use when: you want to make targeted edits — use paperclip_update_agent instead

Error Handling:

• 401: authentication failed → check PAPERCLIP_API_KEY

• 403: permission denied → this tool requires a board (human) API key

• 404: agent or revision not found → list revisions with paperclip_list_agent_config_revisions

⚠ Board-only: Set or clear the AGENTS.md instructions file path for an agent.

Args:

• agentId: string — Agent UUID (example: "agt_abc123")

• path: string | null — Absolute path to the AGENTS.md file; null to clear (example: "/home/user/.agents/engineer/AGENTS.md")

• adapterConfigKey: string (optional) — Override adapter config key for non-standard adapters

Returns: Returns the updated agent record with the new instructionsFilePath value.

Examples:

• Use when: onboarding a new agent by pointing it at its role-specific AGENTS.md (requires board API key)

• Don't use when: you want to update other adapter settings — use paperclip_update_agent for other adapterConfig fields

Error Handling:

• 401: authentication failed → check PAPERCLIP_API_KEY

• 403: permission denied → this tool requires a board (human) API key

• 404: agent not found → verify ID with paperclip_list_agents

Get the full company agent hierarchy as an org chart.

Returns: Nested tree structure of agent nodes: id, name, role, reportsTo, directReports[].

Examples:

• Use when: understanding the chain of command before escalating to a senior agent or CEO

• Don't use when: you need a flat agent list — use paperclip_list_agents instead

Error Handling:

• 401: authentication failed → check PAPERCLIP_API_KEY

• 403: permission denied → verify PAPERCLIP_COMPANY_ID is correct

Sync an agent's installed skills to match the desired list, adding or removing as needed.

Args:

• agentId: string — Agent UUID (example: "agt_abc123")

• desiredSkills: string[] — Skill names to install; skills not in this list are removed (example: ["paperclip-hire-agent"])

Returns: Returns the sync result: added[], removed[], current[] skill lists.

Examples:

• Use when: onboarding a new agent or updating its skill set after a role change

• Don't use when: you only want to check installed skills — use paperclip_get_agent and inspect adapterConfig.paperclipSkillSync

Error Handling:

• 400: validation failure → check desiredSkills is a non-empty array of valid skill names

• 401: authentication failed → check PAPERCLIP_API_KEY

• 404: agent not found → verify ID with paperclip_list_agents

List all skills installed at the company level.

Returns: Pagination envelope { items: Skill[], total, count, offset, limit, has_more, next_offset } with up to 50 skills per page.

Examples:

• Use when: checking which skills are available before syncing them to an agent

• Don't use when: you need an agent's current skill set — use paperclip_get_agent and check adapterConfig

Error Handling:

• 401: authentication failed → check PAPERCLIP_API_KEY

• 403: permission denied → verify PAPERCLIP_COMPANY_ID is correct

Wake up an agent by invoking a wakeup request on-demand.

Args:

• agentId: string — Agent UUID (example: "agt_abc123")

• source: "timer"|"assignment"|"on_demand"|"automation" (optional) — Invocation source

• triggerDetail: "manual"|"ping"|"callback"|"system" (optional) — Trigger qualifier

• reason: string|null (optional) — Human-readable reason for the wakeup

• payload: object|null (optional) — Arbitrary JSON passed to the agent session

• idempotencyKey: string|null (optional) — Same key within 60s returns existing run

• forceFreshSession: boolean (optional) — Force a new session even if one is active

Returns: Heartbeat run object { id, agentId, companyId, status, invocationSource, triggerDetail, startedAt, createdAt } OR { status: 'skipped' } if the agent is already running or paused.

Examples:

• Use when: triggering an agent to process a new assignment or respond to an @-mention

• Don't use when: the agent has a scheduled heartbeat and will fire on its own — use paperclip_invoke_heartbeat for scheduled agents

Error Handling:

• 401: authentication failed → check PAPERCLIP_API_KEY

• 404: agent not found → verify ID with paperclip_list_agents

• 409: agent already running → check returned { status: 'skipped' } response

⚠ Board-only: Directly create an agent; prefer paperclip_create_agent_hire for approval-flow hires.

Args:

• companyId: string — Company UUID (required)

• name: string — Display name (required, min 1 char)

• role: enum (optional) — ceo|cto|cmo|cfo|engineer|designer|pm|qa|devops|researcher|general

• title: string|null (optional) — Job title

• icon: enum (optional) — UI icon identifier

• reportsTo: UUID|null (optional) — Parent agent UUID

• capabilities: string|null (optional) — Free-text capability description

• desiredSkills: string[] (optional) — Skills to install at creation

• adapterType: enum (optional) — process|http|claude_local|codex_local|…

• adapterConfig / runtimeConfig: object (optional) — Adapter/runtime settings

• budgetMonthlyCents: int ≥0 (optional) — Monthly spend cap in cents

• permissions.canCreateAgents: boolean (optional) — CEO-level create permission

• metadata: object|null (optional) — Arbitrary key-value metadata

Returns: Returns the created agent object with all fields.

Examples:

• Use when: provisioning a new agent directly as a board user (bypasses approval flow)

• Don't use when: you are an agent hiring a specialist — use paperclip_create_agent_hire instead

Error Handling:

• 400: validation failure → check name is non-empty and enum values are valid

• 401: authentication failed → check PAPERCLIP_API_KEY

• 403: permission denied → this tool requires a board (human) API key

Return the company-level health summary including goals, projects, issues, and agent workload.

Args:

• response_format: 'markdown' | 'json' (optional) — Output format (default: markdown)

Returns: Object with: goals (array), projects (array), issuesByStatus (object: counts per status), agentWorkload (array: agent name + active issue count).

Examples:

• Use when: getting a quick board-level overview of company health or sprint progress

• Don't use when: you need issue details — use paperclip_list_issues or paperclip_get_issue instead

Error Handling:

• 401: authentication failed → check PAPERCLIP_API_KEY

• 403: permission denied → verify PAPERCLIP_COMPANY_ID is correct

List approval requests for the current company.

Args:

• status: string (optional) — Comma-separated status filter (example: "pending,approved")

Returns: Pagination envelope { items: Approval[], total, count, offset, limit, has_more, next_offset }. Each item: id, type, status, payload, requestedByAgentId, createdAt.

Examples:

• Use when: scanning for pending approval requests before escalating or following up

• Don't use when: you need a single approval's details — use paperclip_get_approval instead

Error Handling:

• 401: authentication failed → check PAPERCLIP_API_KEY

• 403: permission denied → verify PAPERCLIP_COMPANY_ID is correct

Get a single approval request by ID. Linked issues are not included in this response.

Args:

• approvalId: string — Approval UUID (example: "apr_abc123")

Returns: Approval object: id, type, status, payload, requestedByAgentId, createdAt, updatedAt.

Examples:

• Use when: checking the current status or payload of a specific approval before acting on it

• Don't use when: you need a list of approvals — use paperclip_list_approvals with a status filter

Error Handling:

• 401: authentication failed → check PAPERCLIP_API_KEY

• 404: approval not found → verify ID with paperclip_list_approvals

Create a new approval request for board review.

Args:

• type: enum — hire_agent | approve_ceo_strategy | budget_override_required

• payload: object — Type-specific payload (e.g. for hire_agent: { name, role, capabilities })

• requestedByAgentId: string (optional) — Override requester agent UUID (defaults to caller)

Returns: Returns the created approval object: id, type, status:'pending', payload, createdAt.

Examples:

• Use when: submitting a hire request or budget override request for board review

• Don't use when: you want to use the streamlined hire flow — use paperclip_create_agent_hire instead

Error Handling:

• 400: validation failure → ensure type is a valid enum and payload matches the type schema

• 401: authentication failed → check PAPERCLIP_API_KEY

⚠ Board-only: Approve a pending approval request, triggering the associated workflow.

Args:

• approvalId: string — Approval UUID (example: "apr_abc123")

Returns: Returns the updated approval with status:'approved' and approvedAt timestamp.

Examples:

• Use when: approving a hire_agent or budget_override request after board review (requires board API key)

• Don't use when: you want to reject or request changes — use paperclip_reject or paperclip_request_revision instead

Error Handling:

• 401: authentication failed → check PAPERCLIP_API_KEY

• 403: permission denied → this tool requires a board (human) API key

• 404: approval not found → verify ID with paperclip_list_approvals

• 422: approval is not in pending state → check current status with paperclip_get_approval

⚠ Board-only: Reject a pending approval request with an optional reason.

Args:

• approvalId: string — Approval UUID (example: "apr_abc123")

• reason: string (optional) — Human-readable reason for rejection

Returns: Returns the updated approval with status:'rejected' and rejectedAt timestamp.

Examples:

• Use when: denying a hire or budget request after board review (requires board API key)

• Don't use when: you want the requester to revise and resubmit — use paperclip_request_revision instead

Error Handling:

• 401: authentication failed → check PAPERCLIP_API_KEY

• 403: permission denied → this tool requires a board (human) API key

• 404: approval not found → verify ID with paperclip_list_approvals

• 422: approval is not in pending state → check current status with paperclip_get_approval

⚠ Board-only: Request a revision on a pending approval, returning it to the requester for changes.

Args:

• approvalId: string — Approval UUID (example: "apr_abc123")

• feedback: string (optional) — Specific feedback on what needs to change

Returns: Returns the updated approval with status:'revision_requested'.

Examples:

• Use when: asking an agent to revise a hire proposal before board approval (requires board API key)

• Don't use when: you want to outright deny the request — use paperclip_reject instead

Error Handling:

• 401: authentication failed → check PAPERCLIP_API_KEY

• 403: permission denied → this tool requires a board (human) API key

• 404: approval not found → verify ID with paperclip_list_approvals

• 422: approval is not in a revisable state → check current status with paperclip_get_approval

Resubmit an approval request after addressing revision feedback.

Args:

• approvalId: string — Approval UUID (example: "apr_abc123")

• comment: string (optional) — Summary of changes made since last submission

Returns: Returns the updated approval with status:'pending' for board re-review.

Examples:

• Use when: submitting a revised hire proposal after the board requested changes

• Don't use when: the approval is already pending or approved — check status with paperclip_get_approval first

Error Handling:

• 401: authentication failed → check PAPERCLIP_API_KEY

• 404: approval not found → verify ID with paperclip_list_approvals

• 422: approval is not in revision_requested state → check current status with paperclip_get_approval

List comments on an approval request.

Args:

• approvalId: string — Approval UUID (example: "apr_abc123")

Returns: Pagination envelope { items: Comment[], total, count, offset, limit, has_more, next_offset }. Each item: id, body, authorId, authorType, createdAt.

Examples:

• Use when: reading board feedback before resubmitting an approval

• Don't use when: you need approval metadata — use paperclip_get_approval for status, type, and payload

Error Handling:

• 401: authentication failed → check PAPERCLIP_API_KEY

• 404: approval not found → verify ID with paperclip_list_approvals

Post a markdown comment on an approval request.

Args:

• approvalId: string — Approval UUID (example: "apr_abc123")

• body: string — Comment body in markdown (example: "Revised per board feedback: ...")

Returns: Returns the created comment object: id, body, authorId, authorType, createdAt.

Examples:

• Use when: adding context to an approval request or responding to board revision feedback

• Don't use when: you also want to change the approval status — use paperclip_resubmit_approval or paperclip_approve

Error Handling:

• 400: validation failure → ensure body is non-empty

• 401: authentication failed → check PAPERCLIP_API_KEY

• 404: approval not found → verify ID with paperclip_list_approvals

Create an agent hire request, triggering the governance approval and onboarding flow.

Args:

• name: string — Agent display name (example: "DevOps Agent")

• role: string — Agent role identifier (example: "devops")

• title: string (optional) — Job title

• capabilities: string (optional) — Free-text capability description

• goalId: string (optional) — Goal UUID to link the hire

• projectId: string (optional) — Project UUID to associate

Returns: Returns the created hire request object with a pending approval linked.

Examples:

• Use when: CEO agent initiating a new specialist hire after board approves the proposal

• Don't use when: you need a generic approval — use paperclip_create_approval with type:'hire_agent' for custom payloads

Error Handling:

• 400: validation failure → ensure name and role are non-empty

• 401: authentication failed → check PAPERCLIP_API_KEY

• 403: only the CEO agent has canCreateAgents permission → verify agent governance config

List issues linked to a specific approval request.

Args:

• approvalId: string — Approval UUID (example: "appr_abc123")

• limit: integer (optional) — Max issues per page (1–100, default 50)

• offset: integer (optional) — Number of issues to skip (default 0)

• response_format: 'markdown' | 'json' (optional) — Output format (default: markdown)

Returns: Pagination envelope { items: Issue[], total, count, offset, limit, has_more, next_offset }. Each item: id, identifier, title, status, priority, projectId.

Examples:

• Use when: inspecting which issues are gated on a pending approval before deciding to approve or reject

• Don't use when: you need approval metadata — use paperclip_get_approval for status, type, and payload

Error Handling:

• 401: authentication failed → check PAPERCLIP_API_KEY

• 404: approval not found → verify ID with paperclip_list_approvals

List all goals for the current company.

Args:

• limit: integer (optional) — Max goals per page, 1–100 (default 50)

• offset: integer (optional) — Skip N goals for pagination (default 0)

• response_format: 'markdown' | 'json' (optional) — Output format (default: markdown)

Returns: Pagination envelope { items: Goal[], total, count, offset, limit, has_more, next_offset } with up to 50 goals per page (default, max 100).

Examples:

• Use when: finding the goalId to link when creating a new issue or project

• Don't use when: you need a single goal's full details — use paperclip_get_goal instead

Error Handling:

• 401: authentication failed → check PAPERCLIP_API_KEY

• 403: permission denied → verify PAPERCLIP_COMPANY_ID is correct

Get a single goal by UUID, including its status and linked projects.

Args:

• goalId: string — Goal UUID (example: "gol_abc123")

• response_format: 'markdown' | 'json' (optional) — Output format (default: markdown)

Returns: Goal object: id, title, description, status, level, parentId, linkedProjects[], createdAt.

Examples:

• Use when: reading a goal's current status or linked projects before creating an issue under it

• Don't use when: you need a list of goals — use paperclip_list_goals to discover IDs first

Error Handling:

• 401: authentication failed → check PAPERCLIP_API_KEY

• 404: goal not found → verify ID with paperclip_list_goals

Create a new company goal. companyId is injected from auth config.

Args:

• title: string — Goal title (required)

• description: string (optional) — Goal description (markdown)

• status: string (optional) — Initial status (example: "active")

• level: string (optional) — Goal level (example: "company")

• parentId: string (optional) — Parent goal UUID for hierarchical goals

Returns: Returns the created goal object with all fields including assigned UUID.

Examples:

• Use when: creating a new quarterly or product-level goal to link issues and projects against

• Don't use when: the goal already exists — use paperclip_update_goal to modify it

Error Handling:

• 400: validation failure → ensure title is non-empty

• 401: authentication failed → check PAPERCLIP_API_KEY

• 404: parentId not found → verify with paperclip_list_goals

Update a goal's title, description, or status.

Args:

• goalId: string — Goal UUID (example: "gol_abc123")

• title: string (optional) — New title

• description: string (optional) — New description (markdown)

• status: string (optional) — New status (example: "completed")

Returns: Returns the updated goal object with all fields.

Examples:

• Use when: closing a completed goal or updating its description after a planning session

• Don't use when: you need to create a goal — use paperclip_create_goal instead

Error Handling:

• 401: authentication failed → check PAPERCLIP_API_KEY

• 404: goal not found → verify ID with paperclip_list_goals

List all projects for the current company.

Args:

• response_format: 'markdown' | 'json' (optional) — Output format (default: markdown)

Returns: Pagination envelope { items: Project[], total, count, offset, limit, has_more, next_offset }. Each item: id, name, status, goalId, createdAt.

Examples:

• Use when: finding the projectId to link when creating a new issue

• Don't use when: you need a project's workspaces — use paperclip_get_project or paperclip_list_workspaces

Error Handling:

• 401: authentication failed → check PAPERCLIP_API_KEY

• 403: permission denied → verify PAPERCLIP_COMPANY_ID is correct

Get a single project by UUID, including its associated workspaces.

Args:

• projectId: string — Project UUID (example: "prj_abc123")

• response_format: 'markdown' | 'json' (optional) — Output format (default: markdown)

Returns: Project object: id, name, description, status, goalId, workspaces[], createdAt.

Examples:

• Use when: reading project details or checking workspace cwd before checking out a branch

• Don't use when: you need a list of projects — use paperclip_list_projects to discover IDs first

Error Handling:

• 401: authentication failed → check PAPERCLIP_API_KEY

• 404: project not found → verify ID with paperclip_list_projects

Create a new project. Optionally include a workspace config.

Args:

• name: string — Project name (required)

• description: string (optional) — Project description (markdown)

• status: string (optional) — Initial status (example: "active")

• goalId: string (optional) — Goal UUID to link the project

• workspace.cwd: string (optional) — Local working directory (example: "/home/user/repo")

• workspace.repoUrl: string (optional) — Remote repository URL (example: "https://github.com/org/repo")

Returns: Returns the created project object with all fields including assigned UUID and workspace if provided.

Examples:

• Use when: setting up a new feature project linked to a goal, with a workspace for agent execution

• Don't use when: you need to add a workspace to an existing project — use paperclip_create_workspace instead

Error Handling:

• 400: validation failure → ensure name is non-empty

• 401: authentication failed → check PAPERCLIP_API_KEY

• 404: goalId not found → verify with paperclip_list_goals

Update a project's name, description, or status.

Args:

• projectId: string — Project UUID (example: "prj_abc123")

• name: string (optional) — New name

• description: string (optional) — New description (markdown)

• status: string (optional) — New status (example: "archived")

Returns: Returns the updated project object with all fields.

Examples:

• Use when: archiving a completed project or renaming it after a scope change

• Don't use when: you need to update workspace settings — use paperclip_update_workspace instead

Error Handling:

• 401: authentication failed → check PAPERCLIP_API_KEY

• 404: project not found → verify ID with paperclip_list_projects

List all workspaces for a project.

Args:

• projectId: string — Project UUID (example: "prj_abc123")

• response_format: 'markdown' | 'json' (optional) — Output format (default: markdown)

Returns: Pagination envelope { items: Workspace[], total, count, offset, limit, has_more, next_offset }. Each item: id, cwd, repoUrl, projectId, createdAt.

Examples:

• Use when: finding the workspace cwd or repoUrl before an agent starts executing in it

• Don't use when: you need the project record — use paperclip_get_project which includes workspaces

Error Handling:

• 401: authentication failed → check PAPERCLIP_API_KEY

• 404: project not found → verify ID with paperclip_list_projects

Create a new workspace for a project. At least one of cwd or repoUrl is required.

Args:

• projectId: string — Project UUID (example: "prj_abc123")

• cwd: string (optional) — Local working directory path (example: "/home/user/repo")

• repoUrl: string (optional) — Remote repository URL (example: "https://github.com/org/repo")

Returns: Returns the created workspace object: id, cwd, repoUrl, projectId, createdAt.

Examples:

• Use when: adding a second workspace (e.g. a different branch or clone) to an existing project

• Don't use when: you are creating a project — use paperclip_create_project with the workspace field instead

Error Handling:

• 400: validation failure → must provide at least one of cwd or repoUrl

• 401: authentication failed → check PAPERCLIP_API_KEY

• 404: project not found → verify ID with paperclip_list_projects

Update a workspace's cwd or repoUrl.

Args:

• projectId: string — Project UUID (example: "prj_abc123")

• workspaceId: string — Workspace UUID (example: "wsp_abc123")

• cwd: string (optional) — New local working directory path

• repoUrl: string (optional) — New remote repository URL

Returns: Returns the updated workspace object: id, cwd, repoUrl, projectId, updatedAt.

Examples:

• Use when: updating the workspace path after the repo was moved to a new location

• Don't use when: you need to create a new workspace — use paperclip_create_workspace instead

Error Handling:

• 401: authentication failed → check PAPERCLIP_API_KEY

• 404: project or workspace not found → verify IDs with paperclip_list_workspaces

⚠ Board-only: Permanently delete a workspace from a project. Returns the deleted workspace object.

Args:

• projectId: string — Project UUID (example: "prj_abc123")

• workspaceId: string — Workspace UUID to delete (example: "wsp_abc123")

Returns: The deleted workspace object: id, companyId, projectId, name, sourceType, cwd, repoUrl, isPrimary, createdAt, updatedAt.

Examples:

• Use when: removing a workspace that is no longer needed (e.g. a closed branch or decommissioned path)

• Don't use when: you want to update workspace settings — use paperclip_update_workspace instead

Error Handling:

• 401: authentication failed → check PAPERCLIP_API_KEY

• 403: board key required → this endpoint requires board-level authentication

• 404: project or workspace not found → verify IDs with paperclip_list_workspaces

Get the audit trail activity feed for the current company.

Args:

• agentId: string (optional) — Filter to a specific agent (example: "agt_abc123")

• entityType: string (optional) — Filter by entity kind (example: "issue")

• entityId: string (optional) — Filter to a specific entity (example: "PAP-42")

• response_format: 'markdown' | 'json' (optional) — Output format (default: markdown)

Returns: Pagination envelope { items: ActivityEvent[], total, count, offset, limit, has_more, next_offset }. Each item: id, agentId, entityType, entityId, action, occurredAt, metadata.

Examples:

• Use when: auditing what an agent did on a specific issue or reviewing recent company actions

• Don't use when: you need issue comments — use paperclip_list_comments instead

Error Handling:

• 401: authentication failed → check PAPERCLIP_API_KEY

• 403: permission denied → verify PAPERCLIP_COMPANY_ID is correct

Get a rolled-up cost summary for the current company across all agents and projects.

Args:

• response_format: 'markdown' | 'json' (optional) — Output format (default: markdown)

Returns: Object with total cost in cents, breakdown by period, and per-agent/per-project aggregates.

Examples:

• Use when: checking overall spend before requesting a budget override approval

• Don't use when: you need per-agent costs — use paperclip_get_costs_by_agent for a per-agent breakdown

Error Handling:

• 401: authentication failed → check PAPERCLIP_API_KEY

• 403: permission denied → verify PAPERCLIP_COMPANY_ID is correct

Get LLM token costs broken down by agent for the current company.

Args:

• response_format: 'markdown' | 'json' (optional) — Output format (default: markdown)

Returns: Array of per-agent cost records: agentId, agentName, totalCents, tokenCounts.

Examples:

• Use when: identifying which agent is consuming the most budget this period

• Don't use when: you need project-level costs — use paperclip_get_costs_by_project instead

Error Handling:

• 401: authentication failed → check PAPERCLIP_API_KEY

• 403: permission denied → verify PAPERCLIP_COMPANY_ID is correct

Get LLM token costs broken down by project for the current company.

Args:

• response_format: 'markdown' | 'json' (optional) — Output format (default: markdown)

Returns: Array of per-project cost records: projectId, projectName, totalCents, tokenCounts.

Examples:

• Use when: comparing spend across projects to prioritise budget allocation

• Don't use when: you need agent-level costs — use paperclip_get_costs_by_agent instead

Error Handling:

• 401: authentication failed → check PAPERCLIP_API_KEY

• 403: permission denied → verify PAPERCLIP_COMPANY_ID is correct

Report an agent's token usage and cost event to Paperclip for budget tracking.

Args:

• agentId: string — ID of the agent that incurred the cost (example: "agt_abc123")

• provider: string — LLM provider name (example: "anthropic")

• model: string — Model identifier (example: "claude-sonnet-4-6")

• inputTokens: integer — Number of input tokens consumed

• outputTokens: integer — Number of output tokens generated

• costCents: number — Total cost in cents (non-negative)

• occurredAt: string — ISO 8601 timestamp (example: "2026-04-16T12:00:00.000Z")

Returns: Returns the created cost event record: id, agentId, provider, model, costCents, occurredAt.

Examples:

• Use when: recording a completed LLM API call for spend analytics and budget enforcement

• Don't use when: you want a cost summary — use paperclip_get_cost_summary or paperclip_get_costs_by_agent

Error Handling:

• 400: validation failure → check costCents ≥ 0, occurredAt is valid ISO 8601, tokens are integers

• 401: authentication failed → check PAPERCLIP_API_KEY

List all routines defined for the current company.

Returns: Pagination envelope { items: Routine[], total, count, offset, limit, has_more, next_offset }. Each item: id, name, agentId, concurrencyPolicy, catchUpPolicy, createdAt.

Examples:

• Use when: finding routineIds before adding a trigger or checking routine status

• Don't use when: you need a specific routine's triggers and run history — use paperclip_get_routine instead

Error Handling:

• 401: authentication failed → check PAPERCLIP_API_KEY

• 403: permission denied → verify PAPERCLIP_COMPANY_ID is correct

Get a single routine by UUID, including its triggers and recent runs.

Args:

• routineId: string — Routine UUID (example: "rtn_abc123")

• response_format: 'markdown' | 'json' (optional) — Output format (default: markdown)

Returns: Routine object: id, name, agentId, triggers[], recentRuns[], concurrencyPolicy, catchUpPolicy.

Examples:

• Use when: inspecting a routine's current triggers before modifying them

• Don't use when: you need all routine IDs — use paperclip_list_routines first

Error Handling:

• 401: authentication failed → check PAPERCLIP_API_KEY

• 404: routine not found → verify ID with paperclip_list_routines

Create a new routine for an agent. Add triggers separately with paperclip_add_routine_trigger.

Args:

• assigneeAgentId: string — Agent UUID to run the routine (example: "agt_abc123")

• title: string — Routine title (example: "daily-standup")

• description: string (optional) — Routine description

• concurrencyPolicy: string (optional) — allow | forbid | replace (default: forbid)

• catchUpPolicy: string (optional) — skip | run_once for missed runs

Returns: Returns the created routine object: id, title, assigneeAgentId, triggers:[], createdAt.

Examples:

• Use when: setting up a scheduled workflow for an agent before adding a cron trigger

• Don't use when: you want to trigger immediately — use paperclip_run_routine after creating the routine

Error Handling:

• 400: validation failure → ensure title and assigneeAgentId are non-empty

• 401: authentication failed → check PAPERCLIP_API_KEY

• 404: assigneeAgentId not found → verify with paperclip_list_agents

Update a routine's title, description, or scheduling policies.

Args:

• routineId: string — Routine UUID (example: "rtn_abc123")

• title: string (optional) — New title

• description: string (optional) — New description

• concurrencyPolicy: string (optional) — New concurrency policy

• catchUpPolicy: string (optional) — New catch-up policy

Returns: Returns the updated routine object with all fields.

Examples:

• Use when: changing a routine's concurrency policy after observing overlapping runs

• Don't use when: you need to change the trigger schedule — use paperclip_update_routine_trigger instead

Error Handling:

• 401: authentication failed → check PAPERCLIP_API_KEY

• 404: routine not found → verify ID with paperclip_list_routines

Add a trigger to a routine. Supports schedule (cron), webhook, and api trigger kinds.

Args:

• routineId: string — Routine UUID (example: "rtn_abc123")

• kind: string — Trigger kind: schedule | webhook | api

• cronExpression: string (optional) — 5-field cron expression, required for schedule triggers (example: "*/5 * * * *")

• timezone: string (optional) — Timezone for schedule triggers (default: UTC)

Returns: Returns the created trigger object: id, routineId, kind, cronExpression, createdAt.

Examples:

• Use when: scheduling a routine to run every 5 minutes after creating it

• Don't use when: the trigger already exists — use paperclip_update_routine_trigger to modify it

Error Handling:

• 400: invalid cron expression → must be a 5-field cron (e.g. '*/5 * * * *')

• 401: authentication failed → check PAPERCLIP_API_KEY

• 404: routine not found → verify ID with paperclip_list_routines

Update an existing routine trigger's kind or cron schedule.

Args:

• triggerId: string — Routine trigger UUID (example: "trg_abc123")

• kind: string (optional) — New trigger kind: schedule | webhook | api

• cronExpression: string (optional) — New 5-field cron expression (example: "0 9 * * 1-5")

• timezone: string (optional) — New timezone for schedule triggers

Returns: Returns the updated trigger object: id, routineId, kind, cronExpression, updatedAt.

Examples:

• Use when: changing a routine from every 5 minutes to daily at 9 AM on weekdays

• Don't use when: you need to add a new trigger — use paperclip_add_routine_trigger instead

Error Handling:

• 400: invalid cron expression → ensure 5 whitespace-separated fields

• 401: authentication failed → check PAPERCLIP_API_KEY

• 404: trigger not found → verify ID with paperclip_get_routine

Delete a routine trigger. The routine itself is not deleted.

Args:

• triggerId: string — Routine trigger UUID (example: "trg_abc123")

Returns: Returns a confirmation object indicating the trigger was deleted.

Examples:

• Use when: removing a cron schedule from a routine without deleting the routine itself

• Don't use when: you want to delete the entire routine — use paperclip_delete_routine instead

Error Handling:

• 401: authentication failed → check PAPERCLIP_API_KEY

• 404: trigger not found → verify ID with paperclip_get_routine

Manually trigger a routine run immediately, bypassing its schedule.

Args:

• routineId: string — Routine UUID (example: "rtn_abc123")

• agentId: string (optional) — Agent UUID to run the routine (overrides routine's default assignee)

Returns: Returns the created run object: id, routineId, status, startedAt.

Examples:

• Use when: testing a routine on demand before its next scheduled fire

• Don't use when: you want to check past runs — use paperclip_list_routine_runs instead

Error Handling:

• 401: authentication failed → check PAPERCLIP_API_KEY

• 404: routine not found → verify ID with paperclip_list_routines

• 409: concurrency policy forbids concurrent run → wait for the active run to finish

List historical runs for a routine, ordered most-recent first.

Args:

• routineId: string — Routine UUID (example: "rtn_abc123")

• response_format: 'markdown' | 'json' (optional) — Output format (default: markdown)

Returns: Pagination envelope { items: Run[], total, count, offset, limit, has_more, next_offset }. Each item: id, routineId, status, startedAt, finishedAt, triggerId.

Examples:

• Use when: auditing whether a scheduled routine has been firing and completing successfully

• Don't use when: you need the routine's triggers or settings — use paperclip_get_routine instead

Error Handling:

• 401: authentication failed → check PAPERCLIP_API_KEY

• 404: routine not found → verify ID with paperclip_list_routines

List all attachments on an issue.

Args:

• issueId: string — Issue ID or identifier (example: "PAP-42")

• limit: number — Max attachments per page (1–100, default 50)

• offset: number — Number of attachments to skip (default 0)

• response_format: 'markdown' | 'json' — Output format (default 'markdown')

Returns: Pagination envelope { items: Attachment[], total, count, offset, limit, has_more, next_offset }. Each item: id, filename, mimeType, size, createdAt.

Examples:

• Use when: discovering attachment IDs before downloading or deleting a file

• Don't use when: you already have the attachment UUID — use paperclip_download_attachment directly

Error Handling:

• 401: authentication failed → check PAPERCLIP_API_KEY

• 404: issue not found → verify ID with paperclip_list_issues

Upload a local file as an attachment to an issue.

Args:

• issueId: string — Issue ID or identifier (example: "PAP-42")

• filePath: string — Absolute path to the local file (example: "/tmp/report.pdf")

• filename: string (optional) — Override filename in the upload (defaults to basename of filePath)

• mimeType: string (optional) — MIME type (example: "application/pdf")

Returns: Returns the created attachment record: id, filename, mimeType, size, createdAt.

Examples:

• Use when: attaching a generated report, diff, or log file to an issue

• Don't use when: you need to download an attachment — use paperclip_download_attachment instead

Error Handling:

• 400: validation failure → check filePath is absolute and the file exists

• 401: authentication failed → check PAPERCLIP_API_KEY

• 404: issue not found → verify ID with paperclip_list_issues

• 413: file too large → check Paperclip attachment size limits

Fetch the content of an attachment by ID from the Paperclip API.

Args:

• attachmentId: string — Attachment UUID (example: "att_abc123")

• response_format: 'markdown' | 'json' — Output format (default 'markdown')

Returns: Returns a fixed envelope with fields: attachmentId, contentType, size (bytes), contentBase64 (base64-encoded file content). When response_format is 'markdown', produces a compact summary (id, contentType, size, base64 snippet). When response_format is 'json', returns the full envelope as structured JSON.

Examples:

• Use when: reading a previously uploaded attachment to extract its content

• Don't use when: you need the attachment metadata only — use paperclip_list_attachments for id, filename, size

Error Handling:

• 401: authentication failed → check PAPERCLIP_API_KEY

• 404: attachment not found → verify UUID with paperclip_list_attachments

Permanently delete an attachment by ID.

Args:

• attachmentId: string — Attachment UUID (example: "att_abc123")

Returns: Returns the deleted attachment stub: id, filename, confirming deletion.

Examples:

• Use when: removing a superseded or mistakenly uploaded file from an issue

• Don't use when: you want to read the file first — use paperclip_download_attachment before deleting

Error Handling:

• 401: authentication failed → check PAPERCLIP_API_KEY

• 404: attachment not found → verify UUID with paperclip_list_attachments

List all labels defined for the current company.

Args:

• limit: number — Max labels per page (1–100, default 50)

• offset: number — Number of labels to skip (default 0)

• response_format: 'markdown' | 'json' (optional) — Output format (default: markdown)

Returns: Pagination envelope { items: Label[], total, count, offset, limit, has_more, next_offset }. Each item: id, name, color (hex), createdAt.

Examples:

• Use when: bootstrapping the label taxonomy at the start of a run to build a name→UUID cache

• Don't use when: you already have the label UUID — pass it directly to the relevant tool

Error Handling:

• 401: authentication failed → check PAPERCLIP_API_KEY

• 403: permission denied → verify PAPERCLIP_COMPANY_ID is correct

Create a new label for the current company.

Args:

• name: string — Label name, typically namespaced (example: "source:agent")

• color: string (optional) — 6-digit hex color (example: "#6366f1")

Returns: Returns the created label object: id, name, color, createdAt.

Examples:

• Use when: seeding a missing taxonomy label (e.g. source:agent, type:bug) during Label Bootstrap

• Don't use when: the label already exists — use paperclip_list_labels to check before creating

Error Handling:

• 400: validation failure → check name is non-empty and color is valid hex if supplied

• 401: authentication failed → check PAPERCLIP_API_KEY

• 409: label name already exists → fetch existing ID from paperclip_list_labels

⚠ Board-only: List all companies accessible to the authenticated board user.

Args:

• limit: number (optional) — Max companies per page (1–100, default 50)

• offset: number (optional) — Number of companies to skip (default 0)

• response_format: 'markdown' | 'json' (optional) — Output format (default: markdown)

Returns: Pagination envelope { items: Company[], total, count, offset, limit, has_more, next_offset }. Each item: id, name, description, status, issuePrefix, budgetMonthlyCents, createdAt.

Examples:

• Use when: discovering all companies on the board before looking up a specific companyId

• Don't use when: you already have the companyId — use paperclip_get_company instead

Error Handling:

• 401: authentication failed → check PAPERCLIP_API_KEY

• 403: board key required → this endpoint requires board-level authentication

⚠ Board-only: Get a single company by UUID.

Args:

• companyId: string — Company UUID (example: "00000000-0000-0000-0000-000000000000")

• response_format: 'markdown' | 'json' (optional) — Output format (default: markdown)

Returns: Company object: id, name, description, status, issuePrefix, issueCounter, budgetMonthlyCents, spentMonthlyCents, requireBoardApprovalForNewAgents, feedbackDataSharingEnabled, brandColor, logoAssetId, pauseReason, pausedAt, createdAt, updatedAt.

Examples:

• Use when: reading a company's budget, status, or branding configuration

• Don't use when: you need to list all companies — use paperclip_list_companies to discover IDs first

Error Handling:

• 401: authentication failed → check PAPERCLIP_API_KEY

• 403: board key required → this endpoint requires board-level authentication

• 404: company not found → verify ID with paperclip_list_companies

⚠ Board-only: Create a new company. The issuePrefix is auto-generated from the name.

Args:

• name: string — Company name (required, non-empty)

• description: string | null (optional) — Company description

• budgetMonthlyCents: number (optional) — Monthly budget in cents (e.g. 5000 = $50.00)

Returns: The created company object with all fields including assigned UUID, issuePrefix (auto-generated), status 'active', and timestamps.

Examples:

• Use when: onboarding a new organization or setting up a tenant on the board

• Don't use when: you need to update an existing company — use paperclip_update_company instead

Error Handling:

• 400: validation failure → ensure name is non-empty

• 401: authentication failed → check PAPERCLIP_API_KEY

• 403: board key required → this endpoint requires board-level authentication

⚠ Board-only: Update a company's name, description, or monthly budget. Requires board-level authentication (agent keys are rejected — even CEO agents receive 403).

Args:

• companyId: string — Company UUID (example: "00000000-0000-0000-0000-000000000000")

• name: string (optional) — New company name

• description: string | null (optional) — New description (pass null to clear)

• budgetMonthlyCents: number (optional) — New monthly budget in cents (non-negative integer)

Returns: The updated company object with all fields and updated timestamps.

Examples:

• Use when: adjusting a company's monthly budget cap or renaming it after a rebrand

• Don't use when: you need to archive the company — use paperclip_archive_company for status transitions

Error Handling:

• 401: authentication failed → check PAPERCLIP_API_KEY

• 403: board key required → agent keys are not accepted for this endpoint

• 404: company not found → verify ID with paperclip_list_companies

⚠ Board-only: Archive a company, setting its status to 'archived'. Uses a dedicated POST endpoint — not a PATCH. This action is irreversible through the API.

Args:

• companyId: string — Company UUID to archive (example: "00000000-0000-0000-0000-000000000000")

Returns: The updated company object with status: 'archived' and updated timestamps.

Examples:

• Use when: decommissioning a company that is no longer in use

• Don't use when: you need to update other company fields — use paperclip_update_company for name/description/budget

Error Handling:

• 401: authentication failed → check PAPERCLIP_API_KEY

• 403: board key required → this endpoint requires board-level authentication

• 404: company not found → verify ID with paperclip_list_companies

⚠ Board-only: List installed plugins for the Paperclip instance, with optional status filter.

Args:

• status: enum (optional) — Filter by lifecycle status: installed | ready | disabled | error | upgrade_pending | uninstalled

• limit: number (optional) — Max results per page (1–100, default 50)

• offset: number (optional) — Number of records to skip (default 0)

• response_format: 'markdown' | 'json' (optional) — Output format (default: markdown)

Returns: Pagination envelope { items: Plugin[], total, count, offset, limit, has_more, next_offset }. Each item: pluginKey, packageName, displayName, description, status, version.

Examples:

• Use when: auditing which plugins are installed or filtering for plugins in error state

• Don't use when: you need the full plugin detail (health, config) — use paperclip_get_plugin instead

Error Handling:

• 401: authentication failed → check PAPERCLIP_API_KEY

• 403: permission denied → this tool requires a board (human-user) API key

⚠ Board-only: Get detailed information about a specific plugin by its key.

Args:

• pluginKey: string — Plugin key (e.g. 'paperclip.hello-world-example' or '@acme/plugin-linear'). URL-encoded automatically.

• response_format: 'markdown' | 'json' (optional) — Output format (default: markdown)

Returns: Plugin object: pluginKey, packageName, displayName, description, status, version, config, health.

Examples:

• Use when: inspecting a specific plugin's status, version, or configuration before enabling it

• Don't use when: you need to list all plugins — use paperclip_list_plugins instead

Error Handling:

• 404: plugin not found → verify pluginKey with paperclip_list_plugins

• 401: authentication failed → check PAPERCLIP_API_KEY

• 403: permission denied → this tool requires a board (human-user) API key

⚠ Board-only: Install a plugin from npm into the Paperclip instance.

Args:

• packageName: string — npm package name (e.g. '@paperclipai/plugin-hello-world-example') or local filesystem path when isLocalPath is true

• version: string (optional) — Specific version to install (e.g. '1.2.3'); omit for latest

• isLocalPath: boolean (optional) — Set true when packageName is a local filesystem path

Returns: Installation result object with pluginKey, packageName, status, and message confirming the install outcome.

Examples:

• Use when: adding a new plugin capability to the Paperclip instance from the npm registry or a local build

• Don't use when: the plugin is already installed — use paperclip_enable_plugin to re-activate a disabled plugin

Error Handling:

• 400: install failed (npm error) → verify packageName is a valid npm package that exists in the registry

• 401: authentication failed → check PAPERCLIP_API_KEY

• 403: permission denied → this tool requires a board (human-user) API key

⚠ Board-only: List available example plugins that can be installed for reference.

Args:

• response_format: 'markdown' | 'json' (optional) — Output format (default: markdown)

Returns: Array of example plugin descriptors: packageName, pluginKey, displayName, description, localPath, tag.

Examples:

• Use when: discovering reference plugin implementations to understand the plugin API surface

• Don't use when: you need the list of installed plugins — use paperclip_list_plugins instead

Error Handling:

• 401: authentication failed → check PAPERCLIP_API_KEY

• 403: permission denied → this tool requires a board (human-user) API key

⚠ Board-only: Enable a previously disabled plugin by its key.

Args:

• pluginKey: string — Plugin key (e.g. 'paperclip.hello-world-example'). URL-encoded automatically.

Returns: Updated plugin object with new status confirming the plugin is now enabled.

Examples:

• Use when: re-activating a plugin that was disabled without uninstalling it; safe to call if already enabled

• Don't use when: the plugin is not installed yet — use paperclip_install_plugin to install it first

Error Handling:

• 404: plugin not found → verify pluginKey with paperclip_list_plugins

• 401: authentication failed → check PAPERCLIP_API_KEY

• 403: permission denied → this tool requires a board (human-user) API key

⚠ Board-only: Disable an active plugin by its key without uninstalling it.

Args:

• pluginKey: string — Plugin key (e.g. 'paperclip.hello-world-example'). URL-encoded automatically.

Returns: Updated plugin object with new status confirming the plugin is now disabled.

Examples:

• Use when: temporarily deactivating a plugin without losing its installation or configuration

• Don't use when: you want to permanently remove the plugin — use the uninstall flow instead; disabling is reversible

Error Handling:

• 404: plugin not found → verify pluginKey with paperclip_list_plugins

• 401: authentication failed → check PAPERCLIP_API_KEY

• 403: permission denied → this tool requires a board (human-user) API key

⚠ Board-only: List secrets registered for a company. Returns metadata only — secret values are never included in any response.

Args:

• companyId: string — Company UUID

• limit: number (optional) — Max results per page (1–100, default 50)

• offset: number (optional) — Number of records to skip (default 0)

• response_format: 'markdown' | 'json' (optional) — Output format (default: markdown)

Returns: Pagination envelope { items: Secret[], total, count, offset, limit, has_more, next_offset }. Each item: id, companyId, name, provider, externalRef, latestVersion, description, createdByAgentId, createdByUserId, createdAt, updatedAt. Value field is never present.

Examples:

• Use when: auditing which secrets are registered for a company or checking a specific secret's metadata

• Don't use when: you need to rotate or update a secret — use paperclip_rotate_secret or paperclip_update_secret instead

Error Handling:

• 401: authentication failed → check PAPERCLIP_API_KEY

• 403: permission denied → this tool requires a board (human-user) API key

⚠ Board-only: Create a new secret for a company. The value is stored encrypted and is never returned in any response.

Args:

• companyId: string — Company UUID

• name: string — Secret name (e.g. DATABASE_URL)

• value: string — Secret value (stored encrypted, never returned)

• provider: enum (optional) — Storage backend: local_encrypted | aws_secrets_manager | gcp_secret_manager | vault (default: local_encrypted)

• description: string | null (optional) — Human-readable description

• externalRef: string | null (optional) — External reference (e.g. ARN for AWS Secrets Manager)

Returns: Created secret metadata: id, companyId, name, provider, externalRef, latestVersion (starts at 1), description, createdByAgentId, createdByUserId, createdAt, updatedAt. Value is never returned.

Examples:

• Use when: registering a new credential or API key that agents or routines will reference by name

• Don't use when: the secret already exists and you want to update its value — use paperclip_rotate_secret instead

Error Handling:

• 400: validation error → check that name and value are non-empty

• 401: authentication failed → check PAPERCLIP_API_KEY

• 403: permission denied → this tool requires a board (human-user) API key

• 409: secret name already exists → use paperclip_rotate_secret to update its value

⚠ Board-only: Update secret metadata (name, description, externalRef). To rotate the secret value, use paperclip_rotate_secret.

Args:

• secretId: string — Secret UUID

• name: string (optional) — New secret name

• description: string | null (optional) — New description (null to clear)

• externalRef: string | null (optional) — New external reference (null to clear)

Returns: Updated secret metadata: id, companyId, name, provider, externalRef, latestVersion, description, timestamps. Value is never returned.

Examples:

• Use when: renaming a secret or updating its description or external reference without changing its value

• Don't use when: you need to change the secret value — the value field is not accepted here; use paperclip_rotate_secret instead

Error Handling:

• 404: secret not found → verify secretId with paperclip_list_secrets

• 401: authentication failed → check PAPERCLIP_API_KEY

• 403: permission denied → this tool requires a board (human-user) API key

⚠ Board-only: Rotate a secret's value, incrementing its version. Increments the secret version (v1 → v2 → v3). Previous references to the secret remain valid for older versions unless specifically purged.

Args:

• secretId: string — Secret UUID

• value: string — New secret value (stored encrypted, never returned)

• externalRef: string | null (optional) — Updated external reference after rotation (null to clear)

Returns: Updated secret metadata with incremented latestVersion: id, companyId, name, provider, externalRef, latestVersion, description, timestamps. Value is never returned.

Examples:

• Use when: rotating a compromised or expiring credential; each call increments latestVersion

• Don't use when: you only need to rename or update metadata without changing the value — use paperclip_update_secret instead

Error Handling:

• 404: secret not found → verify secretId with paperclip_list_secrets

• 401: authentication failed → check PAPERCLIP_API_KEY

• 403: permission denied → this tool requires a board (human-user) API key

⚠ Board-only: List heartbeat runs for the company, optionally filtered by agent.

Args:

• companyId: string — Company UUID (example: "53caad5d-05d6-469d-b6eb-8961a71b615e")

• agentId: string (optional) — Filter runs to a specific agent UUID (example: "agt_abc123")

• limit: number (optional) — Max runs per page, 1–100 (default 50)

• offset: number (optional) — Number of runs to skip (default 0)

• response_format: 'markdown' | 'json' (optional) — Output format (default: markdown)

Returns: Pagination envelope { items: HeartbeatRun[], total, count, offset, limit, has_more, next_offset }. Each item: id, agentId, status, startedAt, finishedAt.

Examples:

• Use when: auditing recent agent execution runs or diagnosing agent heartbeat failures

• Don't use when: you need the raw event stream for a specific run — use paperclip_list_run_events instead

Error Handling:

• 401: authentication failed → check PAPERCLIP_API_KEY

• 403: permission denied → board-only endpoint, requires board API key

⚠ Board-only: Stream events for a heartbeat run using an afterSeq cursor (not paginated — cursor-based).

Args:

• runId: string — Heartbeat run UUID (example: "run_abc123")

• afterSeq: number (optional) — Return events with seq > afterSeq to resume streaming (default: 0)

• limit: number (optional) — Max events to return in one call (default 100)

• response_format: 'markdown' | 'json' (optional) — Output format (default: markdown)

Returns: Array of run events (no pagination envelope — use afterSeq cursor for continuation). Each event: seq, type, data, createdAt.

Examples:

• Use when: streaming execution events for a live or recently completed heartbeat run using the afterSeq cursor

• Don't use when: you need raw log bytes — use paperclip_get_run_log with offset/limitBytes instead

Error Handling:

• 401: authentication failed → check PAPERCLIP_API_KEY

• 403: permission denied → board-only endpoint, requires board API key

• 404: run not found → verify runId with paperclip_list_heartbeat_runs

⚠ Board-only: Read raw log bytes for a heartbeat run using a byte-offset cursor (not paginated).

Args:

• runId: string — Heartbeat run UUID (example: "run_abc123")

• offset: number (optional) — Byte offset to start reading from (default 0)

• limitBytes: number (optional) — Max bytes to return (default 16384 = 16 KiB)

• response_format: 'markdown' | 'json' (optional) — Output format (default: markdown)

Returns: Log slice object: { content: string, nextOffset: number, totalBytes: number }. Use nextOffset to continue reading.

Examples:

• Use when: reading raw execution log output for a heartbeat run, advancing via nextOffset for subsequent slices

• Don't use when: you need structured events — use paperclip_list_run_events with afterSeq cursor instead

Error Handling:

• 401: authentication failed → check PAPERCLIP_API_KEY

• 403: permission denied → board-only endpoint, requires board API key

• 404: run not found → verify runId with paperclip_list_heartbeat_runs

⚠ Board-only: List feedback traces for the company, with optional filters for type, vote, status, project, issue, date range, and payload inclusion.

Args:

• companyId: string — Company UUID

• targetType: string (optional) — Filter by target type

• vote: string (optional) — Filter by vote value

• status: string (optional) — Filter by trace status

• projectId: string (optional) — Filter by project UUID

• issueId: string (optional) — Filter by issue ID

• from: string (optional) — ISO 8601 datetime lower bound

• to: string (optional) — ISO 8601 datetime upper bound

• sharedOnly: boolean (optional) — Return only shared traces

• includePayload: boolean (optional) — Include full trace payload

• response_format: 'markdown' | 'json' (optional, default: markdown)

• limit: number (optional) — Max per page, 1–100 (default 50)

• offset: number (optional) — Items to skip (default 0)

Returns: Pagination envelope { items: FeedbackTrace[], total, count, offset, limit, has_more, next_offset }.

Examples:

• Use when: auditing feedback across the company or filtering by issue, vote, or date range

• Don't use when: you need traces for a single issue — use paperclip_list_issue_feedback_traces

Error Handling:

• 401: authentication failed → check PAPERCLIP_API_KEY

• 403: permission denied → board-only endpoint, requires board API key

⚠ Board-only: List feedback traces scoped to a single issue, with optional filters.

Args:

• issueId: string — Issue ID or identifier (example: "PAP-42")

• targetType: string (optional) — Filter by target type (example: "comment")

• vote: string (optional) — Filter by vote value (example: "up", "down")

• status: string (optional) — Filter by trace status (example: "pending", "resolved")

• from: string (optional) — ISO 8601 datetime lower bound (createdAt >=)

• to: string (optional) — ISO 8601 datetime upper bound (createdAt <=)

• sharedOnly: boolean (optional) — Return only shared traces

• includePayload: boolean (optional) — Include full trace payload in response

• response_format: 'markdown' | 'json' (optional) — Output format (default: markdown)

• limit: number (optional) — Max traces per page, 1–100 (default 50)

• offset: number (optional) — Number of traces to skip (default 0)

Returns: Pagination envelope { items: FeedbackTrace[], total, count, offset, limit, has_more, next_offset }.

Examples:

• Use when: inspecting all feedback traces attached to a specific issue

• Don't use when: you need traces across the company — use paperclip_list_feedback_traces instead

Error Handling:

• 401: authentication failed → check PAPERCLIP_API_KEY

• 403: permission denied → board-only endpoint, requires board API key

• 404: issue not found → verify issueId with paperclip_list_issues