Tools overview

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

Tool	Does	Changes anything
`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. 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 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.