# DevBoy Tools Reference

> Auto-generated by `devboy tools docs` from `base_tool_definitions()` and the static provider catalog. Do not edit by hand — re-run the command to refresh.

DevBoy Tools v0.31.1 ships 54 provider-backed tools across 7 categories, 11 always-on context tools, and 8 providers.

## Provider Support Matrix

| Provider | Issue Tracker | Git Repository | Epics | Meeting Notes | Knowledge Base | Messenger | Jira Structure |
|---|:---:|:---:|:---:|:---:|:---:|:---:|:---:|
| **GitHub** | ✅ | ✅ | — | — | — | — | — |
| **GitLab** | ✅ | ✅ | — | — | — | — | — |
| **ClickUp** | ✅ | — | ✅ | — | — | — | — |
| **Jira** | ✅ | — | — | — | — | — | ⚠️ |
| **Confluence** | — | — | — | — | ✅ | — | — |
| **Fireflies** | — | — | — | ✅ | — | — | — |
| **Slack** | — | — | — | — | — | ✅ | — |
| **Telegram** | — | — | — | — | — | ✅ | — |

Legend: `✅` supported · `⚠️` conditional (see notes) · `—` not applicable.

### Conditional support

- **Jira → Jira Structure**: requires the Structure plugin to be installed and accessible.

## Issue Tracker Tools

Providers: GitHub, GitLab, ClickUp, Jira.

### `add_issue_comment`

Add a comment to an issue with optional file attachments (ClickUp only).

| Parameter | Type | Required | Description |
|---|---|:---:|---|
| `body` | string | ✅ | Comment text |
| `key` | string | ✅ | Issue key |
| `attachments` | array<string> | — | File attachments (ClickUp only, max 10MB per file). Each: {fileData: base64, filename: string} |

### `assign_to_sprint`

Move one or more issues onto a Jira sprint. Pair with `get_board_sprints` to look up the numeric `sprintId`. Issues already on a sprint are silently moved.

| Parameter | Type | Required | Description |
|---|---|:---:|---|
| `issueKeys` | array<string> | ✅ | Issue keys to move onto the sprint. Must contain at least one key. |
| `sprintId` | integer | ✅ | Numeric sprint id. Use `get_board_sprints` to discover ids on a board. Min: 0 |

### `create_issue`

Create a new issue in the configured provider.

| Parameter | Type | Required | Description |
|---|---|:---:|---|
| `title` | string | ✅ | Issue title |
| `assignees` | array<string> | — | Assignee usernames |
| `description` | string | — | Issue description/body |
| `issueType` | string | — | Issue type (e.g., "Task", "Bug", "Story"). Default: "Task". Removed by providers that don't support it. |
| `labels` | array<string> | — | Labels to add |
| `markdown` | boolean | — | Whether the description is markdown (default: true). When true, ClickUp renders formatted text. |
| `parentId` | string | — | Parent issue key to create a subtask (e.g., 'CU-abc123' or 'DEV-42'). Only supported by ClickUp. |
| `projectId` | string | — | Jira project key (not numeric ID) for issue creation (e.g., "PROJ"). Optional — overrides the default project. |

### `delete_asset`

Delete a file attachment from an issue. Not all providers support this — check asset_capabilities first.

| Parameter | Type | Required | Description |
|---|---|:---:|---|
| `asset_id` | string | ✅ | Asset identifier to delete |
| `key` | string | ✅ | Issue key (e.g. 'PROJ-123') |

### `download_asset`

Download a file attachment to local cache. Returns local file path when cache is available, base64-encoded content as fallback.

| Parameter | Type | Required | Description |
|---|---|:---:|---|
| `asset_id` | string | ✅ | Asset identifier from get_assets response |
| `context_type` | string | ✅ | Context type: 'issue' or 'mr'. Allowed values: `issue`, `mr` |
| `key` | string | ✅ | Issue key or MR key |

### `get_assets`

List file attachments for an issue or merge request.

| Parameter | Type | Required | Description |
|---|---|:---:|---|
| `context_type` | string | ✅ | Context type: 'issue' or 'mr' (merge request / pull request). Allowed values: `issue`, `mr` |
| `key` | string | ✅ | Issue key (e.g. 'DEV-123', 'gitlab#42') or MR key (e.g. 'mr#42', 'pr#42') |

### `get_available_statuses`

Get available statuses for the issue tracker.

_No parameters._

### `get_board_sprints`

List sprints visible on a Jira agile board. Use to discover the numeric `sprintId` accepted by `create_issue` / `update_issue` and `assign_to_sprint`. Returns name, state (active/future/closed), planned start/end, and goal — enough for the agent to pick the right sprint without a follow-up call.

| Parameter | Type | Required | Description |
|---|---|:---:|---|
| `boardId` | integer | ✅ | Numeric Jira board id. The Agile / Boards REST endpoint returns sprints scoped to one board — there is no global sprint list. Min: 0 |
| `state` | string | — | Filter by sprint state. Default `all` returns every sprint on the board. Allowed values: `active`, `future`, `closed`, `all` |

### `get_custom_fields`

List custom fields available on the issue tracker, with their id, name, and field type. Use to discover the `customfield_*` id of a Jira instance — names like `Epic Link`, `Sprint`, `Epic Name` map to different ids on every deployment. Pair with `customFields: { "<id>": <value> }` on `create_issue` / `update_issue` for fields not yet exposed as first-class params.

| Parameter | Type | Required | Description |
|---|---|:---:|---|
| `issueType` | string | — | Optional issue type. Reserved for providers that scope custom fields per create-screen context. |
| `limit` | integer | — | Max fields to return after filtering (default 50). Sorted by name asc. Range: 1 – 200 |
| `project` | string | — | Optional project key. Reserved for providers that scope custom fields per project; ignored on Jira's global `/field` endpoint. |
| `search` | string | — | Case-insensitive substring filter on the field name (e.g. `"Epic"` to find `Epic Link` and `Epic Name`). |

### `get_issue`

Get a single issue by key with optional comments and relations.

| Parameter | Type | Required | Description |
|---|---|:---:|---|
| `key` | string | ✅ | Issue key (e.g., 'gh#123', 'gitlab#456', 'CU-abc', 'DEV-42', 'jira#PROJ-123') |
| `includeComments` | boolean | — | Include issue comments (default: true) |
| `includeRelations` | boolean | — | Include issue relations — parent, subtasks, dependencies (default: true) |

### `get_issue_comments`

Get comments for an issue.

| Parameter | Type | Required | Description |
|---|---|:---:|---|
| `key` | string | ✅ | Issue key |

### `get_issue_relations`

Get relations for an issue (parent, subtasks, linked issues).

| Parameter | Type | Required | Description |
|---|---|:---:|---|
| `key` | string | ✅ | Issue key |

### `get_issues`

Get issues from configured provider. Returns a list with filters.

| Parameter | Type | Required | Description |
|---|---|:---:|---|
| `assignee` | string | — | Filter by assignee username |
| `labels` | array&lt;string&gt; | — | Filter by label names |
| `limit` | integer | — | Maximum number of results (default: 20). Range: 1 – 100 |
| `nativeQuery` | string | — | Native query passed directly to provider (e.g., Jira JQL). Replaces auto-generated filters. If the query omits a project clause, the default project is auto-injected. |
| `offset` | integer | — | Number of results to skip (default: 0). Min: 0 |
| `projectKey` | string | — | Project key to filter issues (e.g., "PROJ"). Overrides default project. Removed by providers that don't support it. |
| `search` | string | — | Search query for title and description |
| `sort_by` | string | — | Sort by field (default: updated_at). Allowed values: `created_at`, `updated_at` |
| `sort_order` | string | — | Sort order (default: desc). Allowed values: `asc`, `desc` |
| `state` | string | — | Filter by issue state (default: open). Allowed values: `open`, `closed`, `all` |

### `get_users`

Get users from the issue tracker (Jira). Search by name, project, or ID.

| Parameter | Type | Required | Description |
|---|---|:---:|---|
| `maxResults` | integer | — | Max results (default: 50). Range: 1 – 1000 |
| `projectKey` | string | — | Get assignable users for project |
| `search` | string | — | Search by name or email |
| `userId` | string | — | Get specific user by ID |

### `link_issues`

Link two issues together (blocks, relates_to, etc.).

| Parameter | Type | Required | Description |
|---|---|:---:|---|
| `linkType` | string | ✅ | Issue link type. Accepts canonical Jira names (`Blocks`, `Relates`, `Causes`, `Implements`, `Created By`, `Duplicate`, `Cloners`) and snake_case aliases (`blocks`, `blocked_by`, `relates_to`, `causes`, `caused_by`, `implements`, `implemented_by`, `created_by`, `creates`, `duplicates`, `duplicated_by`, `clones`, `cloned_by`). The `*_by` variants flip direction. Custom link types configured on the instance also work — pass the exact name. GitHub/GitLab providers ignore this field. |
| `sourceIssueKey` | string | ✅ | Source issue key |
| `targetIssueKey` | string | ✅ | Target issue key |

### `list_project_versions`

List Jira project versions / fixVersion targets (releases). Returns rich per-version payload (description, dates, released/archived flags, optional issue counts). Default filter hides archived versions and limits to 20 most recent (unreleased first, then released by releaseDate desc). For issue-level details on a release, follow up with `get_issues` and a JQL `nativeQuery` such as `fixVersion = "<name>"` — there is no per-id get tool by design.

| Parameter | Type | Required | Description |
|---|---|:---:|---|
| `archived` | string | — | Filter by archived flag (default: "false" — hides archival noise). Allowed values: `true`, `false`, `all` |
| `includeIssueCount` | boolean | — | Fetch issue counts per version via Cloud `?expand=issuesstatus` (default: false). Adds latency on large projects. |
| `limit` | integer | — | Max versions to return (default: 20). Sorted by releaseDate desc; oldest archival entries trimmed first. Range: 1 – 200 |
| `project` | string | — | Jira project key (e.g., "PROJ"). Defaults to the configured project. |
| `released` | string | — | Filter by release state: "true" → only released, "false" → only unreleased, "all" → both (default: "all"). Allowed values: `true`, `false`, `all` |

### `unlink_issues`

Remove a link between two issues.

| Parameter | Type | Required | Description |
|---|---|:---:|---|
| `linkType` | string | ✅ | Issue link type to remove. Accepts the same canonical names and snake_case aliases as `link_issues` (`Blocks`, `Causes`, `Implements`, `Created By`, `Duplicate`, `Cloners`, plus `*_by` direction flips and `subtask`). Custom link types pass through as-is. |
| `sourceIssueKey` | string | ✅ | Source issue key |
| `targetIssueKey` | string | ✅ | Target issue key |

### `update_issue`

Update an existing issue. Only provided fields will be changed.

| Parameter | Type | Required | Description |
|---|---|:---:|---|
| `key` | string | ✅ | Issue key |
| `assignees` | array&lt;string&gt; | — | New assignees |
| `description` | string | — | New description |
| `labels` | array&lt;string&gt; | — | New labels (replaces existing) |
| `markdown` | boolean | — | Whether the description is markdown (default: true). When true, ClickUp renders formatted text. |
| `parentId` | string | — | Parent issue key to move task as subtask (e.g., 'CU-abc123' or 'DEV-42'). Only supported by ClickUp. |
| `state` | string | — | New state (generic open/closed). For ClickUp custom statuses ("in progress", "review", "to do", …) use `status` instead — `get_available_statuses` lists valid names. Allowed values: `open`, `closed` |
| `status` | string | — | Provider-specific status name. ClickUp: any custom status from `get_available_statuses` (e.g. "in progress", "review"). Other providers: ignored. Takes precedence over `state` when both are set. |
| `title` | string | — | New title |

### `upload_asset`

Upload a file attachment to an issue. Returns the download URL.

| Parameter | Type | Required | Description |
|---|---|:---:|---|
| `context_type` | string | ✅ | Context type (currently only 'issue' is supported for uploads). Allowed values: `issue` |
| `fileData` | string | ✅ | Base64-encoded file content |
| `filename` | string | ✅ | Original filename (e.g. 'screenshot.png') |
| `key` | string | ✅ | Issue key (e.g. 'DEV-123') |

### `upsert_project_version`

Create or partially update a Jira project version, keyed by `(project, name)`. If a version with this name exists, fields you supply are updated and unspecified fields are preserved. If not, a new version is created. Useful for writing release notes (`description`) or closing a release (`released: true`, `releaseDate`).

| Parameter | Type | Required | Description |
|---|---|:---:|---|
| `name` | string | ✅ | Version name — both the lookup key and, on create, the value (e.g., "3.18.0"). |
| `archived` | boolean | — | Archive (true) / unarchive (false) the version. |
| `description` | string | — | Release notes / version description. Markdown-style text is preserved on Server/DC; Cloud accepts plain text. |
| `project` | string | — | Jira project key (e.g., "PROJ"). Defaults to the configured project. |
| `releaseDate` | string | — | Planned or actual release date (`YYYY-MM-DD`). |
| `released` | boolean | — | Mark released (true) / unreleased (false). Pair with `releaseDate` when closing a release. |
| `startDate` | string | — | Planned start date as ISO 8601 calendar date (`YYYY-MM-DD`). |

## Git Repository Tools

Providers: GitHub, GitLab.

### `create_merge_request`

Create a new merge request (GitLab) or pull request (GitHub).

| Parameter | Type | Required | Description |
|---|---|:---:|---|
| `source_branch` | string | ✅ | Source branch |
| `target_branch` | string | ✅ | Target branch |
| `title` | string | ✅ | MR/PR title |
| `description` | string | — | MR/PR description |
| `draft` | boolean | — | Create as draft (default: false) |
| `labels` | array&lt;string&gt; | — | Labels |
| `reviewers` | array&lt;string&gt; | — | Reviewers |

### `create_merge_request_comment`

Add a comment to a merge request. Can be general or inline code review.

| Parameter | Type | Required | Description |
|---|---|:---:|---|
| `body` | string | ✅ | Comment text |
| `key` | string | ✅ | MR/PR key |
| `commit_sha` | string | — | Commit SHA for inline comment |
| `discussion_id` | string | — | Reply to existing discussion |
| `file_path` | string | — | File path for inline comment |
| `line` | integer | — | Line number for inline comment |
| `line_type` | string | — | Line type (default: new). Allowed values: `old`, `new` |

### `get_job_logs`

Get CI/CD job logs. Modes: smart (auto errors), search (pattern), paginated, full.

| Parameter | Type | Required | Description |
|---|---|:---:|---|
| `jobId` | string | ✅ | Job ID from get_pipeline |
| `context` | integer | — | Context lines around match (default: 5) |
| `full` | boolean | — | Return entire log |
| `limit` | integer | — | Lines to return (default: 200, max: 1000). Range: 1 – 1000 |
| `maxMatches` | integer | — | Max search results (default: 20) |
| `offset` | integer | — | Start line for paginated mode |
| `pattern` | string | — | Regex/keyword search pattern |

### `get_merge_request`

Get a single merge request by key (e.g., 'pr#123', 'mr#456').

| Parameter | Type | Required | Description |
|---|---|:---:|---|
| `key` | string | ✅ | MR/PR key |

### `get_merge_request_diffs`

Get file diffs for a merge request.

| Parameter | Type | Required | Description |
|---|---|:---:|---|
| `key` | string | ✅ | MR/PR key |

### `get_merge_request_discussions`

Get discussions/review comments for a merge request with code positions.

| Parameter | Type | Required | Description |
|---|---|:---:|---|
| `key` | string | ✅ | MR/PR key |
| `limit` | integer | — | Max discussions (default: 20). Range: 1 – 100 |
| `offset` | integer | — | Skip N discussions (default: 0). Min: 0 |

### `get_merge_requests`

Get merge requests / pull requests from configured provider.

| Parameter | Type | Required | Description |
|---|---|:---:|---|
| `author` | string | — | Filter by author username |
| `labels` | array&lt;string&gt; | — | Filter by label names |
| `limit` | integer | — | Maximum results (default: 20). Range: 1 – 100 |
| `source_branch` | string | — | Filter by source branch |
| `state` | string | — | Filter by state (default: open). Allowed values: `open`, `closed`, `merged`, `all` |
| `target_branch` | string | — | Filter by target branch |

### `get_pipeline`

Get CI/CD pipeline status for branch or MR/PR with job details.

| Parameter | Type | Required | Description |
|---|---|:---:|---|
| `branch` | string | — | Branch name (default: main) |
| `includeFailedLogs` | boolean | — | Include error extraction for failed jobs (default: true) |
| `mrKey` | string | — | MR/PR key (priority over branch) |

### `update_merge_request`

Update a merge request / pull request (title, description, state, labels, draft).

| Parameter | Type | Required | Description |
|---|---|:---:|---|
| `key` | string | ✅ | MR key (e.g. 'mr#1', 'pr#42') |
| `description` | string | — | New description / body (supports markdown) |
| `labels` | array&lt;string&gt; | — | New labels (replaces existing) |
| `state` | string | — | Change MR state. Allowed values: `close`, `reopen` |
| `title` | string | — | New title |

## Epics Tools

Providers: ClickUp.

### `create_epic`

Create a new epic.

| Parameter | Type | Required | Description |
|---|---|:---:|---|
| `title` | string | ✅ | Epic title |
| `description` | string | — | Epic description |

### `get_epics`

Get epics (high-level tasks) from the issue tracker.

| Parameter | Type | Required | Description |
|---|---|:---:|---|
| `limit` | integer | — | Max results (default: 50). Range: 1 – 100 |
| `offset` | integer | — | Skip N results (default: 0). Min: 0 |
| `search` | string | — | Search in epic title |

### `update_epic`

Update an existing epic.

| Parameter | Type | Required | Description |
|---|---|:---:|---|
| `epicKey` | string | ✅ | Epic key (e.g., 'CU-abc', 'DEV-123') |
| `assignees` | array&lt;string&gt; | — | Assignees to set |
| `description` | string | — | New description |
| `goalId` | string | — | Goal ID (G1-G9) to associate with the epic |
| `labels` | array&lt;string&gt; | — | Labels to set |
| `priority` | string | — | New priority (urgent/high/normal/low) |
| `state` | string | — | New epic state (generic open/closed). For ClickUp custom statuses use `status`. |
| `status` | string | — | Provider-specific status name. Same as `update_issue.status` — for ClickUp, any custom status from `get_available_statuses`. Takes precedence over `state`. |
| `title` | string | — | New title |

## Meeting Notes Tools

Providers: Fireflies.

### `get_meeting_notes`

Get meeting notes and transcripts with optional filters (date range, participants, host).

| Parameter | Type | Required | Description |
|---|---|:---:|---|
| `from_date` | string | — | Filter from date (ISO 8601, e.g., '2025-01-01T00:00:00Z') |
| `host_email` | string | — | Filter by host email |
| `limit` | integer | — | Maximum number of results (default: 50). Range: 1 – 50 |
| `offset` | integer | — | Number of results to skip (default: 0). Min: 0 |
| `participants` | array&lt;string&gt; | — | Filter by participant email addresses |
| `to_date` | string | — | Filter to date (ISO 8601) |

### `get_meeting_transcript`

Get the full transcript for a meeting. Returns speaker-attributed sentences with timestamps.

| Parameter | Type | Required | Description |
|---|---|:---:|---|
| `meeting_id` | string | ✅ | Meeting ID from get_meeting_notes |
| `format` | string | — | Output format: 'flat' (default, per-sentence) or 'grouped' (same-speaker runs collapsed). Allowed values: `flat`, `grouped` |
| `limit` | integer | — | Maximum number of sentences (default: 50, max: 500). Range: 1 – 500 |
| `offset` | integer | — | Number of sentences to skip for pagination (default: 0). Min: 0 |
| `search_text` | string | — | Search sentence text (case-insensitive substring match) |
| `speaker_filter` | string | — | Filter sentences by speaker name (case-insensitive substring match) |

### `search_meeting_notes`

Search across meetings by keywords, topics, or action items, with optional filters (date range, participants, host).

| Parameter | Type | Required | Description |
|---|---|:---:|---|
| `query` | string | ✅ | Search query |
| `from_date` | string | — | Filter from date (ISO 8601) |
| `host_email` | string | — | Filter by host email |
| `limit` | integer | — | Maximum number of results (default: 50). Range: 1 – 50 |
| `offset` | integer | — | Number of results to skip (default: 0). Min: 0 |
| `participants` | array&lt;string&gt; | — | Filter by participant email addresses |
| `to_date` | string | — | Filter to date (ISO 8601) |

## Knowledge Base Tools

Providers: Confluence.

### `create_knowledge_base_page`

Create a knowledge base page in a space.

| Parameter | Type | Required | Description |
|---|---|:---:|---|
| `content` | string | ✅ | Page body content |
| `spaceKey` | string | ✅ | Target space key |
| `title` | string | ✅ | Page title |
| `contentType` | string | — | Content representation supplied by the caller. Allowed values: `markdown`, `html`, `storage` |
| `labels` | array&lt;string&gt; | — | Labels to set on the page |
| `parentId` | string | — | Optional parent page ID |

### `get_knowledge_base_page`

Get a knowledge base page with content, labels, and ancestors.

| Parameter | Type | Required | Description |
|---|---|:---:|---|
| `pageId` | string | ✅ | Knowledge base page ID |

### `get_knowledge_base_spaces`

List available knowledge base spaces.

_No parameters._

### `list_knowledge_base_pages`

List pages in a knowledge base space with pagination.

| Parameter | Type | Required | Description |
|---|---|:---:|---|
| `spaceKey` | string | ✅ | Space key to list pages from |
| `cursor` | string | — | Provider pagination cursor/token |
| `limit` | integer | — | Maximum number of results (default: 25). Range: 1 – 100 |
| `offset` | integer | — | Number of results to skip when offset pagination is supported. Min: 0 |
| `parentId` | string | — | Optional ancestor/parent page ID to scope the listing |
| `search` | string | — | Optional free-text title/content filter |

### `search_knowledge_base`

Search knowledge base pages across spaces using free text or provider-native syntax such as CQL.

| Parameter | Type | Required | Description |
|---|---|:---:|---|
| `query` | string | ✅ | Free-text query or provider-native search expression |
| `cursor` | string | — | Provider pagination cursor/token |
| `limit` | integer | — | Maximum number of matches to return. Range: 1 – 100 |
| `rawQuery` | boolean | — | Whether `query` should be treated as raw provider-native syntax |
| `spaceKey` | string | — | Restrict search to a specific space key |

### `update_knowledge_base_page`

Update a knowledge base page title, content, metadata, or labels.

| Parameter | Type | Required | Description |
|---|---|:---:|---|
| `pageId` | string | ✅ | Knowledge base page ID |
| `content` | string | — | New page body content |
| `contentType` | string | — | Content representation supplied by the caller. Allowed values: `markdown`, `html`, `storage` |
| `labels` | array&lt;string&gt; | — | Labels to replace on the page |
| `parentId` | string | — | Optional new parent page ID |
| `title` | string | — | New page title |
| `version` | integer | — | Expected current version for optimistic locking. Min: 1 |

## Messenger Tools

Providers: Slack, Telegram.

### `get_chat_messages`

Get message history for a chat or fetch replies for a specific thread.

| Parameter | Type | Required | Description |
|---|---|:---:|---|
| `chat_id` | string | ✅ | Messenger chat ID |
| `cursor` | string | — | Provider pagination cursor |
| `limit` | integer | — | Maximum number of messages to return. Range: 1 – 1000 |
| `since` | string | — | Only include messages after this provider timestamp |
| `thread_id` | string | — | Thread identifier to fetch replies for |
| `until` | string | — | Only include messages before this provider timestamp |

### `get_messenger_chats`

List available messenger chats, channels, groups, or direct messages.

| Parameter | Type | Required | Description |
|---|---|:---:|---|
| `chat_type` | string | — | Optional chat type filter. Allowed values: `direct`, `group`, `channel` |
| `cursor` | string | — | Provider pagination cursor |
| `include_inactive` | boolean | — | Include archived or inactive chats |
| `limit` | integer | — | Maximum number of chats to return. Range: 1 – 1000 |
| `search` | string | — | Optional chat name search |

### `search_chat_messages`

Search messages across accessible chats or within a specific chat.

| Parameter | Type | Required | Description |
|---|---|:---:|---|
| `query` | string | ✅ | Message search query |
| `chat_id` | string | — | Optional chat ID to scope the search |
| `cursor` | string | — | Provider pagination cursor |
| `limit` | integer | — | Maximum number of matches to return. Range: 1 – 1000 |
| `since` | string | — | Only include messages after this provider timestamp |
| `until` | string | — | Only include messages before this provider timestamp |

### `send_message`

Send a message to a chat or as a threaded reply.

| Parameter | Type | Required | Description |
|---|---|:---:|---|
| `chat_id` | string | ✅ | Messenger chat ID |
| `text` | string | ✅ | Message body |
| `reply_to_id` | string | — | Direct parent message ID when supported |
| `thread_id` | string | — | Thread identifier to post as a threaded reply |

## Jira Structure Tools

Providers: Jira (conditional).

### `add_structure_rows`

Add items (Jira issues or folders) to a Structure. Specify position with under (parent row) and/or after (sibling row). Use forestVersion for optimistic concurrency.

| Parameter | Type | Required | Description |
|---|---|:---:|---|
| `items` | array&lt;string&gt; | ✅ | Items to add |
| `structureId` | integer | ✅ | Structure ID |
| `after` | integer | — | Sibling row ID — items placed after this row |
| `forestVersion` | integer | — | Forest version for optimistic locking (from get_structure_forest) |
| `under` | integer | — | Parent row ID — items become children of this row |

### `create_structure`

Create a new Jira Structure. After creation, use add_structure_rows to populate and save_structure_view to configure columns.

| Parameter | Type | Required | Description |
|---|---|:---:|---|
| `name` | string | ✅ | Structure name |
| `description` | string | — | Structure description |

### `get_structure_forest`

Get the hierarchy tree of a Jira Structure. Returns nested tree with rowId, itemId (Jira issue key), itemType, and children. Supports pagination for large structures.

| Parameter | Type | Required | Description |
|---|---|:---:|---|
| `structureId` | integer | ✅ | Structure ID. Use get_structures to find it. |
| `limit` | integer | — | Max rows to return (default: 200). Range: 1 – 10000 |
| `offset` | integer | — | Offset for pagination (default: 0). Min: 0 |

### `get_structure_values`

Read column values (including Expr formulas like SUM, PROGRESS, COUNT) for specific rows in a Jira Structure. Values are computed server-side.

| Parameter | Type | Required | Description |
|---|---|:---:|---|
| `columns` | array&lt;string&gt; | ✅ | Columns to read |
| `rows` | array&lt;integer&gt; | ✅ | Row IDs to read values for |
| `structureId` | integer | ✅ | Structure ID |

### `get_structure_views`

Get views for a Jira Structure. Without viewId: lists all views. With viewId: returns full view configuration (columns, grouping, sorting, filter).

| Parameter | Type | Required | Description |
|---|---|:---:|---|
| `structureId` | integer | ✅ | Structure ID |
| `viewId` | integer | — | View ID for full config (optional — omit to list all views) |

### `get_structures`

List all available Jira Structures. Returns structure ID, name, and description. Requires Jira with Structure plugin.

_No parameters._

### `move_structure_rows`

Move rows within a Jira Structure hierarchy. Specify new position with under (new parent) and/or after (sibling).

| Parameter | Type | Required | Description |
|---|---|:---:|---|
| `rowIds` | array&lt;integer&gt; | ✅ | Row IDs to move (from get_structure_forest) |
| `structureId` | integer | ✅ | Structure ID |
| `after` | integer | — | Sibling row ID to place after |
| `forestVersion` | integer | — | Forest version for optimistic locking |
| `under` | integer | — | New parent row ID |

### `remove_structure_row`

Remove a row from a Jira Structure. Only removes from the structure hierarchy — the underlying Jira issue is NOT deleted.

| Parameter | Type | Required | Description |
|---|---|:---:|---|
| `rowId` | integer | ✅ | Row ID to remove (from get_structure_forest) |
| `structureId` | integer | ✅ | Structure ID |

### `save_structure_view`

Create or update a Jira Structure view. Views define column layout (fields and formulas), grouping, sorting, and filters. Omit id to create new.

| Parameter | Type | Required | Description |
|---|---|:---:|---|
| `name` | string | ✅ | View name |
| `structureId` | integer | ✅ | Structure ID this view belongs to |
| `columns` | array&lt;string&gt; | — | Column definitions |
| `filter` | string | — | JQL filter expression |
| `groupBy` | string | — | Field name to group by |
| `id` | integer | — | View ID to update (omit to create new) |
| `sortBy` | string | — | Field name to sort by |

## Context Management Tools

Always-on tools attached to every `tools/list` response, independent of which providers are configured. They let the agent inspect or switch the active context.

### `list_contexts`

List configured contexts and indicate the active context.

_No parameters._

### `use_context`

Switch active context at runtime.

| Parameter | Type | Required | Description |
|---|---|:---:|---|
| `name` | string | ✅ | Context name to activate |

### `get_current_context`

Get current active context name.

_No parameters._

### `secrets_list`

List secrets the active context's manifest declares. Returns metadata only — values are never included. Optional filter narrows by path substring, scope, status, or whether to include framework-internal paths.

| Parameter | Type | Required | Description |
|---|---|:---:|---|
| `include_internal` | boolean | — | Include framework-internal paths (default: false). |
| `path_contains` | string | — | Substring to match against the full ADR-020 path. |
| `scope` | string | — | Exact match against the first path segment (e.g. team / personal). |
| `status` | string | — | Lifecycle status filter computed from expires_at.. Allowed values: `registered`, `expiring`, `expired` |

### `secrets_describe`

Describe one secret by ADR-020 path. Returns the same metadata fields as `secrets_list` plus description, retrieval URL, rotation method, last rotated date, rotation cadence, and pattern ID. The value is never returned.

| Parameter | Type | Required | Description |
|---|---|:---:|---|
| `path` | string | ✅ | Full ADR-020 path to describe. |

### `secrets_request_provision`

Open the provisioning UI dialog for the given ADR-020 path. The dialog hands the user-entered value directly to the local daemon — the agent never sees it. Returns a `request_id` that can be polled with `secrets_poll_status`. Mode defaults to `provision`; pass `rotation` to surface the destructive-confirm checkbox. Pending requests expire 5 minutes after issuance.

| Parameter | Type | Required | Description |
|---|---|:---:|---|
| `path` | string | ✅ | Full ADR-020 path to provision. |
| `mode` | string | — | Dialog mode (default: provision).. Allowed values: `provision`, `rotation` |

### `secrets_poll_status`

Poll a provisioning or rotation request issued by `secrets_request_provision` / `secrets_request_rotation`. Returns one of pending / ok / cancelled / expired / failed plus the request's age in seconds and the path it was opened for.

| Parameter | Type | Required | Description |
|---|---|:---:|---|
| `request_id` | string | ✅ | Opaque id returned by request_provision / request_rotation. |

### `secrets_request_rotation`

Open the rotation UI dialog for the given ADR-020 path. Same lifecycle as `secrets_request_provision` but the dialog surfaces the destructive-confirm checkbox so the user explicitly acknowledges that the existing value is being overwritten. Reuses `secrets_poll_status` for status. Pending requests expire 5 minutes after issuance.

| Parameter | Type | Required | Description |
|---|---|:---:|---|
| `path` | string | ✅ | Full ADR-020 path to rotate. |

### `secrets_request_use_approval`

Open the use-approval dialog for an ADR-020 path whose `approve_on_use` is set to `session` or `per-call`. The agent supplies a short human-facing `reason` that the dialog renders verbatim alongside the path; the user picks `once`, `session`, or `denied`. Returns a `request_id` to poll via `secrets_poll_status`. Pending requests expire 5 minutes after issuance; `ttl_seconds` may shorten the window but never extend it. The agent never sees the secret — only whether the user approved its use.

| Parameter | Type | Required | Description |
|---|---|:---:|---|
| `path` | string | ✅ | Full ADR-020 path the agent intends to resolve. |
| `reason` | string | ✅ | Short human-facing reason rendered in the dialog (e.g. 'pushing image to staging registry'). |
| `ttl_seconds` | integer | — | Optional lifetime in seconds; capped at the registry-wide TTL (5 minutes). |

### `secrets_propose_metadata`

Suggest metadata edits for an existing ADR-020 path. The dialog renders the manifest's current values as the diff baseline (read straight from the index — agent strings never replace trusted fields, mitigating prompt-injection). The user picks which proposed fields to accept. Reuses `secrets_poll_status` for status. Pending requests expire 5 minutes after issuance.

| Parameter | Type | Required | Description |
|---|---|:---:|---|
| `fields` | object | ✅ | Proposed field overrides (description, retrieval_url, rotate_every_days, expires_at, pattern_id). Omitted fields are not proposed for change. |
| `path` | string | ✅ | Full ADR-020 path to edit. |

### `secrets_propose_new_path`

Suggest registering a new secret at the given path. The dialog opens with the suggested path editable and the proposed metadata visible in a diff column for review. The user has the final say on the path and the metadata that lands in the manifest. Reuses `secrets_poll_status` for status. Pending requests expire 5 minutes after issuance.

| Parameter | Type | Required | Description |
|---|---|:---:|---|
| `metadata` | object | ✅ | Proposed metadata fields for the new entry. |
| `suggested_path` | string | ✅ | Suggested ADR-020 path; user may edit. |