# Tools overview

Gravity's MCP server has seven tools. Five read, and two change something.

| Tool | Does | Changes anything |
| --- | --- | --- |
| [`list_groups`](/docs/mcp/tools/list_groups) | Lists the groups you belong to | No |
| [`get_group_details`](/docs/mcp/tools/get_group_details) | Reads a group's roster and the goals shared with it | No |
| [`list_goals`](/docs/mcp/tools/list_goals) | Lists your active goals | No |
| [`get_goal`](/docs/mcp/tools/get_goal) | Reads one goal, its versions, audience, and search state | No |
| [`get_goal_matches`](/docs/mcp/tools/get_goal_matches) | Reads the saved matches for your goal | No |
| [`save_goal`](/docs/mcp/tools/save_goal) | Creates, edits, shares, hides, or ends your goal | Yes |
| [`start_goal_matching`](/docs/mcp/tools/start_goal_matching) | Starts a search for your goal | Yes |

## Results

Each tool returns its result twice: as a JSON object in `structuredContent`, and as the same JSON in a text block for clients that read only text. Tools don't publish an output schema, so rely on the fields documented on each tool's page.

A read that finds nothing you're allowed to see returns `null` or an empty list, not an error. A missing goal, one you can't read, and a malformed ID all look the same.

## Errors

Input schemas are strict. A missing, misspelled, or extra argument fails with `isError: true` and text starting `Input validation error`, and nothing runs.

When a tool runs but can't do what you asked, it returns `"status": "error"` with a `message`, and the result has `isError: true`. Each tool's page lists its messages. See [Errors and limits](/docs/mcp/errors-and-limits) for retries.

## Annotations

Each tool declares MCP annotations so clients can tell reads from writes.

| Tools | `readOnlyHint` | `destructiveHint` | `idempotentHint` | `openWorldHint` |
| --- | --- | --- | --- | --- |
| The five read tools | `true` | `false` | `true` | `false` |
| `save_goal`, `start_goal_matching` | `false` | `true` | `false` | `false` |

The write tools are marked destructive because ending a goal archives its chats, and a new search can replace matches nobody has acted on.

## IDs

Every ID comes from an earlier tool result. Group IDs are `publicId` values: 32 lowercase hexadecimal characters. Goal IDs are UUIDs. Never build an ID from a name.