# Tools overview

Gravity's MCP server has twelve tools. Eight read, and four change something.

| Tool | Does | Changes anything |
| --- | --- | --- |
| [`find_people`](/docs/mcp/tools/find_people) | Finds bounded identities in your own Rolodex | No |
| [`get_person`](/docs/mcp/tools/get_person) | Reads one owned person's identity and effective profile | No |
| [`save_person`](/docs/mcp/tools/save_person) | Creates or edits a private person and their profile sections | Yes |
| [`get_person_notes`](/docs/mcp/tools/get_person_notes) | Reads one owned person's private note history | No |
| [`save_person_notes`](/docs/mcp/tools/save_person_notes) | Adds, corrects, or explicitly forgets private person notes | Yes |
| [`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. Every tool publishes an `outputSchema` for successful results and validates its response before returning it. The common error contract below applies to `isError` results, which MCP excludes from successful-output validation. Undeclared application and UI fields are removed from successful responses.

An accessible list with no items is a successful empty list. An exact missing or inaccessible group, goal, or own Rolodex person returns `unavailable`; both cases intentionally look the same. Malformed IDs fail input validation. A readable goal may have `search: null` or `matching.run: null` without being unavailable.

## Interactive cards

Compatible clients may show a compact card for an exact goal, saved matches, a save receipt, or search progress. Cards are enabled only when your connection explicitly advertises MCP Apps HTML support. Other clients receive the same tool data and text, including a link to the exact goal. A product name alone does not establish support; older handshake-only connections use the text experience on this stateless server.

Opening or refreshing a card starts no search. A search or retry button is an explicit action and appears only with the required member permissions and host tool support. Progress follows the accepted search, pauses when the card is hidden, and stops at completion, interruption, cancellation, or its update limit. Use Refresh to check again or Open in Gravity to continue. Goal editing and introduction decisions remain in conversation or Gravity.

Private person and note reads and saves can show a compact profile or note view, or a receipt, with an exact-person link. These cards have no editing or search controls. The same capability check and text fallback apply.

## 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 cannot satisfy the request, it returns `{ status: "error", code, message, recovery }` in both content representations, with `isError: true`. Write failures may also include `currentState`, `goalId`, `scopeVersion`, or `matchingRunId`. Person errors may include `personId` and `personState`; note errors may include `personId` and `noteState`. Use the stable `code` and `recovery` fields, rather than parsing a message. See [Errors and limits](/docs/mcp/errors-and-limits) for the common codes and safe recovery. Input-validation errors remain protocol-level errors without this application envelope.

## Annotations

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

| Tools | `readOnlyHint` | `destructiveHint` | `idempotentHint` | `openWorldHint` |
| --- | --- | --- | --- | --- |
| The eight read tools | `true` | `false` | `true` | `false` |
| `save_goal`, `start_goal_matching`, `save_person`, `save_person_notes` | `false` | `true` | `true` | `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, person profile sections can be replaced, and person notes can be corrected or forgotten. They are idempotent for identical arguments and the same member-scoped request ID: retries reconcile current state without repeating effects. Goal saves return no_change or a conflict; search requests reuse their admitted run. A new action uses a new request ID.

## IDs

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