---
summary: Every tool of ScaiGit's MCP interface with its risk tier and arguments, generated
  from the gateway's contract.
title: Agent tools (MCP)
path: reference/mcp-tools
status: published
---

# Agent tools (MCP)

All 59 tools of the agent interface, with their risk tier and arguments. This page is generated from the contract the gateway enforces (surface version 1.1.0), so it matches the running service. See [Agents and risk tiers](/docs/scaigit/concepts/agents) for what the tiers mean.

Arguments marked * are required. Repository tools take `owner` and `repo`; list tools take `page` and `limit` (at most 50). Every tool at T1 or above also accepts `idempotency_key`. Tools marked *hidden* appear in `tools/list` only for callers whose role grants them.

## Discovery

| Tool | Tier | Arguments | Returns |
|---|---|---|---|
| `scaigit_repo_list` | T0 | `owner`, `query`, `page`, `limit` | repos visible to caller: owner, name, description, default_branch, private, permissions |
| `scaigit_repo_get` | T0 | `owner`*, `repo`* | repo metadata incl. default_branch, visibility, caller permissions, size, topics |
| `scaigit_search_code` | T0 | `query`*, `owner`, `repo`, `lang`, `page`, `limit` | matches: repo, path, line, fragment, language |
| `scaigit_search_issues` | T0 | `query`*, `state`, `labels`, `type`, `page`, `limit` | issue/PR summaries: repo, number, title, state, labels, updated_at |
| `scaigit_user_get` | T0 | `username`* | public profile: username, full_name, type (user\|org), avatar_url |

## Files and content

| Tool | Tier | Arguments | Returns |
|---|---|---|---|
| `scaigit_file_get` | T0 | `owner`*, `repo`*, `path`*, `ref` | content (utf-8 or base64 for binary), sha, size, encoding; over size cap: truncated sentinel + raw URL |
| `scaigit_dir_list` | T0 | `owner`*, `repo`*, `path`, `ref` | entries: name, type (file\|dir\|symlink\|submodule), size, sha |
| `scaigit_commit_list` | T0 | `owner`*, `repo`*, `ref`, `path`, `since`, `page`, `limit` | commits: sha, message, author, date, parents |
| `scaigit_commit_get` | T0 | `owner`*, `repo`*, `sha`* | commit detail: message, author, committer, parents, stats (files/additions/deletions) |
| `scaigit_diff_get` | T0 | `owner`*, `repo`*, `base`, `head`, `sha`, `pr` | unified diff, size-capped with per-file truncation sentinels |
| `scaigit_blame_get` | T0 | `owner`*, `repo`*, `path`*, `ref`, `line_start`, `line_end` | blame ranges: line span, sha, author, date |

## Commits

| Tool | Tier | Arguments | Returns |
|---|---|---|---|
| `scaigit_commit_create` | T2 (T1 when target branch was created by the same principal in the same session (own-scratch-branch carve-out)) | `owner`*, `repo`*, `branch`*, `message`*, `files`*, `author`, `expected_head` | commit sha, branch head, atomic (bool: false when executor used fallback strategy) |
| `scaigit_repo_create` | T2 | `owner`*, `name`*, `description`, `private`, `template` | created repo metadata |
| `scaigit_repo_fork` | T1 | `owner`*, `repo`*, `target_owner` | fork repo metadata |
| `scaigit_repo_delete` | T3 | `owner`*, `repo`*, `confirm_name`* | confirmation |

## Branches and tags

| Tool | Tier | Arguments | Returns |
|---|---|---|---|
| `scaigit_branch_list` | T0 | `owner`*, `repo`*, `page`, `limit` | branches: name, head sha, protected flag |
| `scaigit_branch_create` | T1 | `owner`*, `repo`*, `name`*, `from_ref`* | created branch: name, head sha |
| `scaigit_branch_delete` | T2 (T3 when target branch is protected) | `owner`*, `repo`*, `name`* | confirmation: name, was_protected |
| `scaigit_branch_protect` | T3 | `owner`*, `repo`*, `pattern`*, `action`, `rules` | effective protection rule, or {removed: pattern} for remove |
| `scaigit_tag_list` | T0 | `owner`*, `repo`*, `page`, `limit` | tags: name, target sha, annotated flag, message |
| `scaigit_tag_create` | T2 | `owner`*, `repo`*, `name`*, `target`*, `message` | created tag |

## Pull requests

| Tool | Tier | Arguments | Returns |
|---|---|---|---|
| `scaigit_pr_list` | T0 | `owner`*, `repo`*, `state`, `page`, `limit` | PR summaries: number, title, state, head, base, author, updated_at |
| `scaigit_pr_get` | T0 | `owner`*, `repo`*, `number`* | PR detail incl. mergeable flag, CI status rollup, review summary, labels |
| `scaigit_pr_create` | T2 (T1 when draft=true) | `owner`*, `repo`*, `title`*, `head`*, `base`*, `body`, `draft` | created PR: number, url |
| `scaigit_pr_update` | T1 | `owner`*, `repo`*, `number`*, `title`, `body`, `labels`, `assignees`, `base`, `draft` | updated PR summary |
| `scaigit_pr_comment` | T1 | `owner`*, `repo`*, `number`*, `body`* | comment id |
| `scaigit_pr_review_create` | T1 | `owner`*, `repo`*, `number`*, `verdict`*, `body`, `comments` | review id, effective_verdict |
| `scaigit_pr_reviewers_request` | T1 | `owner`*, `repo`*, `number`*, `reviewers`, `team_reviewers` | requested reviewer set |
| `scaigit_pr_merge` | T2 (T3 when merge would bypass required status checks or required approvals) | `owner`*, `repo`*, `number`*, `method`*, `delete_branch`, `expected_head` | merge sha |

## Issues

| Tool | Tier | Arguments | Returns |
|---|---|---|---|
| `scaigit_issue_list` | T0 | `owner`*, `repo`*, `state`, `labels`, `milestone`, `page`, `limit` | issue summaries |
| `scaigit_issue_get` | T0 | `owner`*, `repo`*, `number`* | issue detail incl. comments (capped), dependencies, timeline summary |
| `scaigit_issue_create` | T1 | `owner`*, `repo`*, `title`*, `body`, `labels`, `assignees`, `milestone` | created issue: number, url |
| `scaigit_issue_update` | T1 | `owner`*, `repo`*, `number`*, `title`, `body`, `state`, `labels`, `assignees`, `milestone` | updated issue summary |
| `scaigit_issue_comment` | T1 | `owner`*, `repo`*, `number`*, `body`* | comment id |
| `scaigit_issue_dependency_set` | T1 | `owner`*, `repo`*, `number`*, `relation`*, `target_number`*, `action`* | current dependency edges for the issue |
| `scaigit_label_manage` | T1 | `owner`*, `repo`*, `action`*, `name`*, `new_name`, `color`, `description` | label state after action |
| `scaigit_milestone_manage` | T1 | `owner`*, `repo`*, `action`*, `id`, `title`, `due_on`, `description` | milestone state after action |

## Actions

| Tool | Tier | Arguments | Returns |
|---|---|---|---|
| `scaigit_actions_workflow_list` | T0 | `owner`*, `repo`* | workflows: id, name, path, state, dispatchable flag |
| `scaigit_actions_run_list` | T0 | `owner`*, `repo`*, `workflow`, `status`, `page`, `limit` | runs: id, workflow, ref, sha, status, conclusion, started_at |
| `scaigit_actions_run_get` | T0 | `owner`*, `repo`*, `run_id`* | run detail: jobs, per-job status, timing, trigger |
| `scaigit_actions_logs_get` | T0 | `owner`*, `repo`*, `run_id`*, `job`, `tail_lines`, `grep` | log window with truncation sentinels |
| `scaigit_actions_dispatch` | T2 | `owner`*, `repo`*, `workflow`*, `ref`*, `inputs` | dispatched run id (best effort correlation) |
| `scaigit_actions_run_cancel` | T2 | `owner`*, `repo`*, `run_id`* | confirmation with final status |
| `scaigit_actions_secret_set` *for migrations only* | T3 | `owner`*, `repo`*, `name`*, `value`* | confirmation + warning |

## Releases

| Tool | Tier | Arguments | Returns |
|---|---|---|---|
| `scaigit_release_list` | T0 | `owner`*, `repo`*, `page`, `limit` | releases: tag, title, draft/prerelease flags, published_at, asset summaries |
| `scaigit_release_get` | T0 | `owner`*, `repo`*, `tag`* | release detail incl. notes and assets |
| `scaigit_release_create` | T2 | `owner`*, `repo`*, `tag`*, `target`, `title`, `notes`, `draft`, `prerelease` | created release |
| `scaigit_release_asset_upload` | T2 | `owner`*, `repo`*, `tag`*, `filename`*, `content_base64`* | asset id, download url |

## Packages

| Tool | Tier | Arguments | Returns |
|---|---|---|---|
| `scaigit_package_list` | T0 | `owner`*, `type`, `query`, `page`, `limit` | packages: type, name, latest version, size |
| `scaigit_package_get` | T0 | `owner`*, `type`*, `name`*, `version` | package version detail incl. files and metadata |
| `scaigit_package_delete` | T3 | `owner`*, `type`*, `name`*, `version`* | confirmation |

## Wiki

| Tool | Tier | Arguments | Returns |
|---|---|---|---|
| `scaigit_wiki_page_list` | T0 | `owner`*, `repo`* | page names + last edit metadata |
| `scaigit_wiki_page_get` | T0 | `owner`*, `repo`*, `page`* | page content (markdown) + revision info |
| `scaigit_wiki_page_put` | T1 | `owner`*, `repo`*, `page`*, `content`*, `message` | revision info |

## Administration

| Tool | Tier | Arguments | Returns |
|---|---|---|---|
| `scaigit_org_get` | T0 | `org`* | org metadata, visibility, repo count |
| `scaigit_org_team_list` | T0 | `org`*, `page`, `limit` | teams: name, permission level, member count, scaikey_managed flag |
| `scaigit_org_team_manage` *hidden* | T3 | `org`*, `action`*, `team`, `member`, `repo`, `permission`, `reason`* | team state after action + reconciler_warning when object is scaikey_managed |
| `scaigit_webhook_manage` *hidden* | T3 | `owner`*, `repo`, `action`*, `hook_id`, `config`, `reason`* | hook state / test delivery result |
| `scaigit_admin_user_list` *hidden* | T3 | `page`, `limit` | instance users: username, active/suspended, scaikey_sub linkage, last login |

## Error codes

| Code | Meaning |
|---|---|
| `policy_denied` | The caller's role does not allow this tool, or the policy hides it. |
| `hitl_denied` | A reviewer denied the request. |
| `hitl_timeout` | Nobody decided the request in time (default 30 minutes). |
| `not_found` | The repository, branch or object does not exist or is not visible to the caller. |
| `conflict` | The change conflicts with the current state (for example a stale commit). |
| `forge_unavailable` | The forge did not answer; retry later. |
| `rate_limited` | Too many calls; slow down and retry. |
| `invalid_params` | An argument is missing or malformed. |
| `auth_expired` | The token is missing, malformed or expired. |
| `scope_insufficient` | The caller's credential lacks the permission this tool needs. |
