Browse docsTools overview
Tools overview
Gravity's MCP server has twenty-nine tools. Seventeen read and twelve change something.
| Tool | Does | Changes anything |
|---|---|---|
list_people | Lists paginated identities in your own Rolodex | No |
get_person | Reads one owned person's identity and effective profile | No |
create_person | Adds a person to your private Rolodex | Yes |
add_person_email | Adds one address to an existing person | Yes |
update_person | Updates a private person’s contact identity | Yes |
get_self_profile | Reads your current private capabilities, characteristics, pursuits and relationship context | No |
list_statements | Reads current and removed statements for an owned person or self | No |
list_groups | Lists the groups you belong to | No |
get_group | Reads group details, dates, and up to ten member previews | No |
list_group_members | Reads a page of the group’s roster | No |
list_group_goals | Reads a page of goals visible within the group | No |
list_goals | Lists your active goals | No |
get_goal | Reads one goal in Basic or Full view | No |
list_goal_search_networks | Reads eligible or unfinished network identities | No |
list_goal_matches | Reads a page of saved match summaries | No |
get_goal_search | Reads saved search status and coverage | No |
list_goal_connections | Reads your connections for another member’s goal | No |
get_goal_match | Reads one authorized saved assessment | No |
create_goal | Creates a new goal | Yes |
update_goal | Patches your goal's wording, private details, or audience | Yes |
end_goal | Ends one owned goal and archives its introduction chats | Yes |
batch_end_goals | Ends an exact set of owned goals atomically | Yes |
start_goal_search | Starts a search for your goal | Yes |
list_introductions | Lists introductions under way with other members, those waiting on you first | No |
list_action_items | Lists Gravity's current suggestions for you, newest first | No |
complete_action_item | Marks one of Gravity's suggestions done when you've done it | Yes |
create_group | Starts a new group with you as its moderator | Yes |
update_group | Changes the name or description of a group you moderate | Yes |
suggest_group_members | Reads who from your own Rolodex could join a group | No |
issue_invitations | Creates invitation links you send yourself | Yes |
list_invitations | Lists a page of your own open invitation links in a group you moderate | No |
Results#
Each tool returns its result as a JSON object in structuredContent and an explicit readable briefing in the text block, using the same domain renderers as Gravity Agent. get_self_profile returns its current profile Markdown directly in the text block and as markdown in structured content. MCP keeps canonical IDs and continuation tokens usable by stateless clients, with compact named edit-argument sections where exact preconditions are needed. Typed records remain in structuredContent; there is no generic resource-JSON fallback for conversational text. Exact person and goal tools, and group write tools add one more text block: a write's message, if any, then Open in Gravity: and the exact person, goal, or group link. list_introductions gives each introduction its own link; batch_end_goals gives each goal result its own link. Include the relevant links in the reply, and after a write, briefly report its actual outcome. 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 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. Goal views omit search diagnostics. The separate owner-only get_goal_search may return run: null for the current scope without the goal being unavailable. An absent current-scope run does not prove that an earlier scope was never searched.
Errors#
Input schemas are strict. A missing, misspelled, or extra argument fails with isError: true and request_rejected in the common error envelope. No application operation runs. The four group-read tools use invalid_argument and correct_input for invalid arguments, shared with Gravity Agent. Follow the message and recovery guidance to correct the request.
When a tool runs but cannot satisfy the request, it returns { status: "error", code, message, recovery } in structuredContent with readable recovery guidance in the text block, with isError: true. Write failures may also include currentState, goalId, scopeVersion, or matchingRunId. Person errors may include personId and currentPerson. Use the stable code and recovery fields, rather than parsing a message. Errors are text. See Errors and limits for the common codes and safe recovery. Unknown tools and malformed protocol messages remain protocol errors.
Annotations#
Each tool declares MCP annotations so clients can tell reads from writes.
| Tools | readOnlyHint | destructiveHint | idempotentHint | openWorldHint |
|---|---|---|---|---|
| Read tools | true | false | true | false |
create_goal | false | false | false | false |
create_person, add_person_email | false | false | false | false |
create_group, issue_invitations | false | false | false | false |
start_goal_search | false | true | false | false |
update_goal, end_goal, batch_end_goals, update_person, update_group | false | true | true | false |
Creating a goal or group, adding a person, or preparing invitation links changes nothing that already exists, so those tools are not destructive. Goal edits can cancel obsolete searches or replace the audience; ending archives chats; a full search can replace matches nobody has acted on; person sections and notes can be corrected or removed; a group's name and description are replaced. Those tools are marked destructive.
Retries compare against current state: a goal or group edit already applied returns no_change; an already-ended goal returns no_change with its saved reason; and an admitted search is reused. Duplicate goal/group creation returns request_rejected; duplicate person creation or email addition returns already_exists. Person Update always checks the etag, including for a no-op, and returns the canonical Person on success. idempotentHint describes safe repeated effects, not a promise of identical responses. Issuing invitations skips current members and recipients with one of your open links, and succeeds with no_change when everyone is skipped. Read list_invitations for existing open links before issuing new ones, following nextPageToken until empty before claiming complete coverage. Missing open links do not prove an uncertain issuance never committed.
create_goal and start_goal_search receive a fresh request identity on every MCP call and expose no caller retry key. Read the relevant goals or search state after an uncertain response before retrying. Goal duplicate detection checks current active wording; it cannot replay a create after that goal changes or ends.
IDs#
Every ID comes from an earlier tool result. Group IDs are publicId values: 32 lowercase hexadecimal characters. Goal and person IDs are UUIDs. Statement IDs, including those shown as note IDs, are UUID-shaped identifiers; retained migrated IDs may lack RFC version bits. Never build an ID from a name.