---
title: Tools
description: Every tool on the Graphon MCP server, grouped by toolset, with the role that each tool needs.
doc_version: 0.1.0-preview
last_updated: 2026-09-14
---

# Tools

Every tool on the Graphon MCP server, grouped by toolset, with the role that each tool needs.

The server has 69 tools. A connection lists only the tools that its role
covers. Role is the lowest role that can call the tool: Viewer, then Editor,
then Admin. A read-only tool does not change data. A destructive tool can
delete or overwrite data.

## Context

- `get_me` (Get the caller). Role: Viewer. Read-only. Returns the signed-in user, or the API key workspace when the caller is a key.
- `list_workspaces` (List workspaces). Role: Viewer. Read-only. Lists workspaces for the signed-in user. An API key cannot call it. Call this first when a tool asks for workspaceId.
- `get_workspace` (Get a workspace). Role: Viewer. Read-only. Returns the workspace the caller can access, with its name and revision.

## API keys

- `list_api_keys` (List API keys). Role: Viewer. Read-only. Lists API keys. owner=me returns the caller's personal keys and needs the viewer role. owner=workspace returns the workspace keys and requires the admin role. Keys are never returned, only masked keys.
- `create_api_key` (Create an API key). Role: Viewer. Creates a personal API key for the caller, or a workspace key when owner is workspace. A viewer can create a personal key. An admin is required for a workspace key. The key works on the API, the storage API, and S3 tools. It appears once. This result holds the new key, so the key enters your context. The server instructions give the S3 settings.
- `get_api_key` (Get an API key). Role: Viewer. Read-only. Returns one API key without the key itself. The owner can read a personal key. An admin can read any key in the workspace.
- `update_api_key` (Update an API key). Role: Viewer. Edits the name or role. The key stays the same.
- `revoke_api_key` (Revoke an API key). Role: Viewer. Destructive. Revokes an API key. The owner can revoke their own personal key. An admin can revoke any key in the workspace. Storage rejects the key when this call returns.

## Webhooks

- `list_webhooks` (List webhooks). Role: Viewer. Read-only. Lists the webhooks the caller can see, newest first. A member sees their own, a workspace key sees workspace webhooks, and an Admin sees every webhook. Signing secrets are never returned.
- `create_webhook` (Create a webhook). Role: Viewer. Registers an HTTPS receiver for the events of the workspace, optionally only some event types and buckets. Any member can make a personal webhook. A workspace key makes a workspace webhook. The signing secret appears once. Register only a URL the user gave you. Show the signing secret to the user now.
- `get_webhook` (Get a webhook). Role: Viewer. Read-only. Returns one webhook with its status and a summary of its delivery log. A member manages their own webhooks, a workspace key manages workspace webhooks, and an Admin manages every webhook.
- `update_webhook` (Update a webhook). Role: Viewer. Changes the name, URL, event types, buckets, or enabled. A member manages their own webhooks, a workspace key manages workspace webhooks, and an Admin manages every webhook.
- `delete_webhook` (Delete a webhook). Role: Viewer. Destructive. Deletes the webhook and its delivery log. To stop deliveries and keep the log, set enabled to false. A member manages their own webhooks, a workspace key manages workspace webhooks, and an Admin manages every webhook.
- `rotate_webhook_secret` (Rotate a webhook secret). Role: Viewer. Makes a new signing secret and shows it once. The previous secret keeps signing for the overlap, 24 hours by default. A member manages their own webhooks, a workspace key manages workspace webhooks, and an Admin manages every webhook. Show the new signing secret to the user now.
- `test_webhook` (Test a webhook). Role: Viewer. Sends one signed webhook.test POST to the receiver now, and returns its response. It works while the webhook is off, and the log does not keep it. A member manages their own webhooks, a workspace key manages workspace webhooks, and an Admin manages every webhook.
- `list_webhook_deliveries` (List webhook deliveries). Role: Viewer. Read-only. Lists the delivery log, newest first: each event the webhook got, its status, and its last attempt. The log keeps 30 days. A member manages their own webhooks, a workspace key manages workspace webhooks, and an Admin manages every webhook.
- `get_webhook_delivery` (Get a webhook delivery). Role: Viewer. Read-only. Returns one event at one webhook: the exact body Graphon sends and every attempt. A member manages their own webhooks, a workspace key manages workspace webhooks, and an Admin manages every webhook.
- `replay_webhook_deliveries` (Replay webhook deliveries). Role: Viewer. Sends past events of this webhook again, by event id or by time range, with the same id and body. A member manages their own webhooks, a workspace key manages workspace webhooks, and an Admin manages every webhook.

## Members

- `list_members` (List members). Role: Viewer. Read-only. Lists active members in the workspace. Requires the viewer role. Use query to filter by display name or email.
- `update_member` (Update a member role). Role: Admin. Changes a member's role. Requires the admin role. The last admin cannot become a viewer or editor.
- `remove_member` (Remove a member). Role: Admin. Destructive. Removes a member from the workspace. Requires the admin role. The last admin cannot be removed. memberId cannot be me.
- `list_member_api_keys` (List a member's API keys). Role: Admin. Read-only. Lists personal API keys for another member. Requires the admin role. Secrets are never returned.

## Invitations

- `list_invitations` (List invitations). Role: Admin. Read-only. Lists pending invitations for the workspace. Requires the admin role.
- `create_invitations` (Invite members). Role: Admin. Invites one or more email addresses with the same role. Requires the admin role. Send between 1 and 50 addresses. Each address returns its own outcome.
- `resend_invitation` (Resend an invitation). Role: Admin. Sends the invitation email again. Requires the admin role. The invitation must still be pending.
- `update_invitation` (Update an invitation role). Role: Admin. Changes the role on a pending invitation. Requires the admin role.
- `revoke_invitation` (Revoke an invitation). Role: Admin. Destructive. Revokes a pending invitation. Requires the admin role. This does not remove an accepted member.

## Buckets

- `get_metadata_fields` (Get metadata fields). Role: Viewer. Read-only. Returns the metadata fields of a bucket: each metadata key that a filter can read, its type, whether it is ready or still indexing, and how many objects hold a value that does not fit the type. A new bucket lists no fields. Requires the viewer role. The bucket must have indexing enabled. The fields work before the first upload and while objects index.
- `update_metadata_fields` (Update metadata fields). Role: Editor. Lists, retypes, or removes metadata fields of a bucket, and returns every field. A key left out keeps its setting, and null removes the field. A filter can read only a listed field. On a bucket with objects, a changed field is indexing while the index is rewritten, which takes up to about 30 minutes; list fields before the first upload to skip the wait. Other fields and queries without a filter keep working meanwhile. A change while the last one is still indexing fails with operation_in_progress. Requires the editor role. The bucket must have indexing enabled. The fields work before the first upload and while objects index.
- `list_buckets` (List buckets). Role: Viewer. Read-only. Lists the buckets in the workspace. Pass name to find one bucket by its exact name. Role: viewer or higher.
- `check_bucket_name` (Check a bucket name). Role: Viewer. Read-only. Returns whether a bucket name is valid and free. Names are case-sensitive and unique within this workspace. Role: viewer or higher.
- `create_bucket` (Create a bucket). Role: Editor. Creates a bucket and returns it when it is active. Provider, location, and indexing are fixed when the bucket is created. A request that omits them gets gcp, the US multi-region, and indexing enabled. Tell the user which provider and location the bucket uses, and that other values are available. Role: editor or higher.
- `get_bucket` (Get a bucket). Role: Viewer. Read-only. Returns one bucket with its settings and usage. Role: viewer or higher.
- `update_bucket` (Update a bucket). Role: Editor. Changes the name, permission, availability, or policy atomically. Send the current revision as a quoted If-Match header. Names are case-sensitive and unique within the workspace. Renaming preserves the bucket ID and stored objects. Update S3 paths after renaming. A missing field keeps its value. Role: editor or higher.
- `retry_bucket_provisioning` (Retry bucket provisioning). Role: Editor. Provisions a bucket again after it failed, and returns it when it is active. Role: editor or higher.
- `empty_bucket` (Empty a bucket). Role: Editor. Destructive. Deletes every object in the bucket. Send the exact bucket name as confirmName. Objects under retention stay, and the call returns object_locked with their keys. Role: editor or higher.
- `delete_bucket` (Delete a bucket). Role: Editor. Destructive. Deletes an empty bucket. Send the exact bucket name as confirmName. The name is free again when the deletion is final. After that, the bucket cannot be restored. Role: editor or higher.
- `restore_bucket` (Restore a bucket). Role: Editor. Restores a deleted bucket within its recovery window. Role: editor or higher.
- `get_job` (Get a job). Role: Viewer. Read-only. Returns the status of background work, such as an empty or a copy. Role: viewer or higher.

## Objects

- `list_objects` (List objects). Role: Viewer. Read-only. Lists live objects in key order, one page at a time. Pass delimiter "/" to group keys into prefixes, or sort=newest to list the most recent writes first. Role: viewer or higher.
- `get_object_metadata` (Get object metadata). Role: Viewer. Read-only. Returns the live version of one object without its bytes: its size, type, checksums, indexing status, and its metadata (the x-amz-meta-* headers it was written with). Role: viewer or higher.
- `list_object_versions` (List object versions). Role: Viewer. Read-only. Lists the live versions and delete markers of one object, newest first. Role: viewer or higher.
- `get_bucket_index_status` (Get bucket index status). Role: Viewer. Read-only. Returns the indexing progress of a bucket: counts by state, and one page of versions. The default page lists the versions that are not indexed yet, in the order they will finish. Filter failed or unsupported to see why versions are not searchable. A bucket with indexing disabled fails with indexing_disabled. Role: viewer or higher.
- `delete_object` (Delete an object). Role: Editor. Destructive. Deletes one object. The deleted version stays recoverable for the bucket recovery window. Role: editor or higher.
- `restore_object` (Restore an object). Role: Editor. Restores a deleted or replaced version from recovery. Get the recoveryId from the recovery list of the bucket. Role: editor or higher. list_bucket_recovery returns the recovery list.
- `copy_object` (Copy an object). Role: Editor. Copies an object to another key in the same bucket. Role: editor or higher.
- `read_object` (Read an object). Role: Viewer. Read-only. Reads one object. Text content up to maxBytes returns as text, and a PNG, JPEG, GIF, or WebP image returns as an image. Anything else, or anything larger, returns its metadata and a download URL that lasts 15 minutes.
- `create_object_download_url` (Create an object download URL). Role: Viewer. Read-only. Returns a presigned GET URL for one object. It lasts up to 15 minutes. Use it to download a file with curl instead of reading it into the conversation.
- `write_object` (Write a new object). Role: Editor. Creates an object from content that you produce, such as generated text or JSON, up to 1 MiB. Do not use it for a file on disk: call create_object_upload_url. It fails with object_exists when the key exists. To overwrite, call replace_object.
- `create_object_upload_url` (Create an object upload URL). Role: Editor. Uploads a file from disk without passing it through the model. Returns a presigned PUT URL and a ready curl command. The URL creates only: storage rejects the PUT when the key exists. For files over 200 MiB, or many files, use graphon objects put.
- `replace_object` (Replace an object). Role: Editor. Destructive. Writes an object from content that you produce, up to 1 MiB, and overwrites the key when it exists. The previous version stays as an older version. list_object_versions lists it.
- `create_object_replace_url` (Create an object replace URL). Role: Editor. Destructive. Like create_object_upload_url, but the PUT overwrites the key when it exists. The previous version stays as an older version. For files over 200 MiB, or many files, use graphon objects put.

## Search

- `list_datasets` (List datasets). Role: Viewer. Read-only. Returns the datasets that Graphon curates, most recently indexed first. Pass a dataset id as target to search_objects, answer_question, or start_research. access.state locked means a paid dataset that this workspace cannot query yet. Requires the viewer role.
- `get_dataset` (Get a dataset). Role: Viewer. Read-only. Returns one dataset by its id or its slug, with its description, source, license, example questions, and access. Requires the viewer role.
- `search_objects` (Search objects). Role: Viewer. Read-only. Ranks the objects or passages of one target against a text. The target is a bucket with indexing enabled, or a dataset from list_datasets. Each result is an object and the spans in it that matched: pages of a document, characters of a text file, or seconds of a video or a recording. A span holds no text. To read spans, call read_spans with up to 50 of them. To read the whole object, call read_spans with include object, or read_object with the result key for a bucket. To use only objects whose metadata matches, send filter; get_metadata_fields lists the fields it can name. For a written answer, call answer_question. Requires the viewer role. An empty bucket returns no results and the warning index_empty. Nothing is stored.
- `read_spans` (Read spans). Role: Viewer. Read-only. Returns the content of 1 to 50 spans, one result for each, in order. Send each span unchanged, as search_objects, answer_question, or a research run returned it. include picks the parts: text (the default) for the text of a document or the speech lines of a video or a recording, raw for the span in its own format (a PDF of the pages, the text of a text file, the image, or a clip), and object for the whole object. Images come back as image content, audio as audio content, and PDFs and other files as embedded resources. One call returns at most 20 MiB of inline data, and a part that does not fit comes back as a link. A large span returns in parts: next holds the spans of the next read, or null. To read the rest, send them until next is null. A span that cannot be read has an error on its own result: not_found, invalid_span (the span does not fit the object), or content_unavailable (the content is not stored or cannot be read). Requires the viewer role. Send the target of the search: a bucket or a dataset.
- `answer_question` (Answer a question). Role: Viewer. Read-only. Answers a question about one target, with a citation for each source. The target is a bucket with indexing enabled, or a dataset from list_datasets. Each [[SRC:0001]] marker in answer matches the source whose ref is SRC:0001. Usually seconds. The call returns an answer or an error within about 2 minutes. The tool waits for the answer. A result over the size limit lists only the cited sources and has the warning sources_trimmed. For a question that needs several steps, call start_research. Requires the viewer role. An image is a premium feature.
- `start_research` (Start research). Role: Viewer. Starts a premium research run on one target: a bucket with indexing enabled, or a dataset from list_datasets. Use it when one search is not enough, and the answer needs several steps. Minutes. At most 600 seconds. The tool waits for the run and returns it when it ends. Its first progress notification names the run id. If the call ends first, read the run with get_research. The result holds at most 50 sources. To read the cited sources or the rest, call get_research. For one short answer, call answer_question. Requires the viewer role. An image is a premium feature.
- `get_research` (Get research). Role: Viewer. Read-only. Returns a run of start_research as it is now. It does not wait. A finished run stays readable until expiresAt: seven days after the end. It stays readable while its bucket is offline. After expiresAt, the tool fails with not_found. Each [[SRC:0001]] marker in answer matches the source whose ref is SRC:0001. When a result is too large, send sources cited and a smaller sourceLimit. Read the rest with sourceCursor set to sourcesNextCursor. Requires the viewer role.

## Insights

- `get_bucket_summary` (Get the bucket summary). Role: Viewer. Read-only. Returns every bucket in the workspace with its usage and indexing counts, in one call. A bucket that is not active, or that could not be read, has null usage and index. A bucket with indexing disabled has null index. Role: viewer or higher.
- `get_bucket_usage` (Get bucket usage). Role: Viewer. Read-only. Returns the bytes and objects that one bucket stores. Role: viewer or higher.
- `list_bucket_recovery` (List bucket recovery). Role: Viewer. Read-only. Lists deleted or replaced versions that can still be restored. Role: viewer or higher.
- `list_bucket_activity` (List bucket activity). Role: Viewer. Read-only. Lists recent changes in one bucket, newest first. Role: viewer or higher.
- `get_bucket_metrics` (Get bucket metrics). Role: Viewer. Read-only. Returns storage metrics for one bucket. Role: viewer or higher.

## Workspace admin

- `update_workspace` (Update a workspace). Role: Admin. Changes the workspace name. Requires the admin role. Send the revision from a read: the update fails with a conflict when another writer changed the workspace first.
- `delete_workspace` (Delete a workspace). Role: Admin. Destructive. Marks the workspace deleted and starts a seven-day recovery window. Requires the admin role. Every bucket must already be deleted. A restore keeps the members.
- `restore_workspace` (Restore a workspace). Role: Admin. Restores a deleted workspace within its recovery window. Requires a signed-in user who was an admin when the workspace was deleted. Returns the same workspace id. An API key cannot call it.

## Account

- `get_notification_preferences` (Get notification preferences). Role: Viewer. Read-only. Returns personal notification preferences for the signed-in user. An API key cannot call it.
- `update_notification_preferences` (Update notification preferences). Role: Viewer. Updates personal notification preferences for the signed-in user. An API key cannot call it.

## Sitemap

See the full [sitemap](/sitemap.md) for all pages.