Skip to content
Browse docsTools overview

Tools overview

Gravity's MCP server has twenty-nine tools. Seventeen read and twelve change something.

ToolDoesChanges anything
list_peopleLists paginated identities in your own RolodexNo
get_personReads one owned person's identity and effective profileNo
create_personAdds a person to your private RolodexYes
add_person_emailAdds one address to an existing personYes
update_personUpdates a private person’s contact identityYes
get_self_profileReads your current private capabilities, characteristics, pursuits and relationship contextNo
list_statementsReads current and removed statements for an owned person or selfNo
list_groupsLists the groups you belong toNo
get_groupReads group details, dates, and up to ten member previewsNo
list_group_membersReads a page of the group’s rosterNo
list_group_goalsReads a page of goals visible within the groupNo
list_goalsLists your active goalsNo
get_goalReads one goal in Basic or Full viewNo
list_goal_search_networksReads eligible or unfinished network identitiesNo
list_goal_matchesReads a page of saved match summariesNo
get_goal_searchReads saved search status and coverageNo
list_goal_connectionsReads your connections for another member’s goalNo
get_goal_matchReads one authorized saved assessmentNo
create_goalCreates a new goalYes
update_goalPatches your goal's wording, private details, or audienceYes
end_goalEnds one owned goal and archives its introduction chatsYes
batch_end_goalsEnds an exact set of owned goals atomicallyYes
start_goal_searchStarts a search for your goalYes
list_introductionsLists introductions under way with other members, those waiting on you firstNo
list_action_itemsLists Gravity's current suggestions for you, newest firstNo
complete_action_itemMarks one of Gravity's suggestions done when you've done itYes
create_groupStarts a new group with you as its moderatorYes
update_groupChanges the name or description of a group you moderateYes
suggest_group_membersReads who from your own Rolodex could join a groupNo
issue_invitationsCreates invitation links you send yourselfYes
list_invitationsLists a page of your own open invitation links in a group you moderateNo

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.

ToolsreadOnlyHintdestructiveHintidempotentHintopenWorldHint
Read toolstruefalsetruefalse
create_goalfalsefalsefalsefalse
create_person, add_person_emailfalsefalsefalsefalse
create_group, issue_invitationsfalsefalsefalsefalse
start_goal_searchfalsetruefalsefalse
update_goal, end_goal, batch_end_goals, update_person, update_groupfalsetruetruefalse

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.