Browse docsTools overview

Tools overview

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

Tool	Does	Changes anything
`find_people`	Finds bounded identities in your own Rolodex	No
`get_person`	Reads one owned person's identity and effective profile	No
`save_person`	Creates or edits a private person and their profile sections	Yes
`get_person_notes`	Reads one owned person's private note history	No
`save_person_notes`	Adds, corrects, or explicitly forgets private person notes	Yes
`list_groups`	Lists the groups you belong to	No
`get_group_details`	Reads a group's roster and the goals shared with it	No
`list_goals`	Lists your active goals	No
`get_goal`	Reads one goal, its versions, audience, and search state	No
`get_goal_matches`	Reads the saved matches for your goal	No
`save_goal`	Creates, edits, shares, hides, or ends your goal	Yes
`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 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.