> ## Documentation Index
> Fetch the complete documentation index at: https://goldengoose.zue.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# gg Tools

> The 6 built-in MCP tools: 3 team tools and 3 process tools.

goldengoose exposes a small set of built-in **MCP tools** that agent threads can call.

These tools are intentionally limited and high-signal:

* **3 Team tools**: coordinate a team (status, messaging, membership)
* **3 Process tools**: run and monitor background commands (run, status, kill)

In the UI, tool calls show up as tool cards in the timeline so you can see what happened and what output the agent saw.

## Quick reference

### Team tools

* `gg_team_status`
* `gg_team_message`
* `gg_team_manage`

### Process tools

* `gg_process_run`
* `gg_process_status`
* `gg_process_kill`

## Team tools

### `gg_team_status`

Get current status for each team member.

**Arguments**

* `team_id` (string, required): the team you want status for.

### `gg_team_message`

Send a message scoped to a team.

This can be either:

* a **direct message** (one recipient), or
* a **broadcast** (everybody on the team).

**Arguments**

* `team_id` (string, required): the team to send into.
* `recipient_agent_id` (string, required):
  * set to an agent id for a direct message, or
  * set to `broadcast` to send to the whole team.
* `message` (string, required): the text content.
* `image_paths` (string\[], optional): paths to images on disk to attach after the text message (advanced).

### `gg_team_manage`

Add or remove team members.

This tool supports two modes:

* **Add member**: omit `remove_agent_ids`
* **Remove member(s)**: set `remove_agent_ids` to a non-empty list of agent ids

Who can use it depends on your team permissions:

* By default, membership changes are lead-driven.
* If you enable **Preferences → General → Team Permissions**, non-lead members can also add/remove members via `gg_team_manage(...)`. That’s what unlocks “delegation to delegation” (a member can add another member to take on a sub-task).

**Arguments**

* `team_id` (string, required)
* Add-member options:
  * `title` (string, optional): a human-readable role label (for example `Reviewer`, `Docs`, `Frontend`).
  * `prompt` (string or `null`, optional): extra onboarding context for the new member.
  * `image_paths` (string\[], optional): image files to attach to onboarding in-order after the onboarding text.
  * `model_preset` (string or `null`, optional): a named preset (see [Model Presets](/how-it-works/model-presets)).
  * `worktree_name` (string or `null`, optional): native worktree slug. When provided, gg derives branch/worktree/cwd from runtime settings. For create-new bootstrap timing and failure behavior, see [Configure: Worktree Init](/configure/worktree-init).
  * `use_existing_worktree` (boolean, optional): when `true`, `worktree_name` is treated as an existing worktree to reuse instead of creating a new one.
  * `unsubscribe_from_compaction_notifications` (boolean, optional): when omitted/false, the agent that adds the member will receive a timeline notice if that member’s chat is compacted. Set this to true if you don’t want compaction notices.
* Remove-member options:
  * `remove_agent_ids` (string\[], required for remove mode): list of agent ids to remove.

**Validation rules**

* `remove_agent_ids` switches the call into remove mode and must contain at least one id.
* In remove mode, add-only fields are rejected: `title`, `prompt`, `image_paths`, `model_preset`, `worktree_name`, `use_existing_worktree`, `unsubscribe_from_compaction_notifications`.
* `use_existing_worktree=true` requires a non-empty `worktree_name`.

**Worktree behavior in add mode**

Think about add mode as three simple cases:

* No `worktree_name`: gg does not create a new native worktree.
* `worktree_name` set, with `use_existing_worktree` omitted or `false`: gg creates a new native worktree with that name. If `.agents/gg/worktree-init.sh` exists in the new checkout, gg runs it before the session starts. See [Configure: Worktree Init](/configure/worktree-init).
* `worktree_name` set, with `use_existing_worktree=true`: gg reuses an existing native worktree with that name. The worktree must already exist, and the init script does not run in this path.

## Process tools

Process tools are how agents run long commands **without blocking the conversation**.

They’re backed by the Process Manager, which:

* captures logs with bounds,
* tracks ownership and status,
* and injects results back into the owning thread when the command exits.

For deeper behavior and safety policy, see:

* [Process Manager](/how-it-works/process-manager)
* [Configure: Process Manager](/configure/process-manager)

### `gg_process_run`

Run a shell command in the background and return immediately with a pid and process metadata.

**Arguments**

* `command` (string, required): the shell command to run.
* `cwd` (string or `null`, optional): working directory (when omitted, uses the session’s current context).
* `timeout_ms` (integer, optional): maximum lifetime in milliseconds; `0` disables timeout.

**What happens next**

* The command runs in the background.
* You can watch it in the Process Monitor and/or query it with `gg_process_status`.
* When it exits, gg injects a structured completion result back into the thread that started it.

### `gg_process_status`

Inspect a background process.

**Arguments**

* `pid` (integer, optional): process id to inspect.
  * If omitted, gg lists caller-owned running processes (team-scoped when in a team).
* `head_lines` (integer, optional): how many lines from the start of logs to include.
* `tail_lines` (integer, optional): how many lines from the end of logs to include.

### `gg_process_kill`

Request termination of a background process started by the caller session.

**Arguments**

* `pid` (integer, required)

## Related pages

* [Process Manager](/how-it-works/process-manager)
* [Configure: Process Manager](/configure/process-manager)
* [Communication System](/how-it-works/communication-system)
* [Configure: Worktree Init](/configure/worktree-init)