Tools reference
The Everythings MCP server offers agents 36 tools. This page lists every one: what it does, the access it needs, and anything special about it. It ends with what agents are told about using them, so you can make sense of what your agent does.
Access and confirmations
An agent connects with one of two levels of access. An agent that signs in gets the level it asks for, which the Everythings sign-in screen lists before you approve; an agent on an access token gets the scope you picked for the token. Either level reaches every workspace you can open, and the level limits what the agent can do there.
Read
The 18 read tools: searching, listing and reading workspaces, things, comments, marks, Trash, questions and @Agent jobs; what changed since the agent's last run; how people marked its work; the two view tools; and ChatGPT's search and fetch.
Read & write
Adds the 18 write tools: creating and renaming workspaces; creating, editing, moving, reordering, copying, deleting to Trash and restoring things; adding comments; adding and removing marks; asking you questions and recording your answers; closing @Agent jobs; and claims. A write tool called with read access fails and changes nothing.
Every tool also carries hints for the client. They help an app decide when to ask you; your access level is what the server enforces.
| Hint | Tools | What clients do |
|---|---|---|
| Read-only | The 17 read tools other than what_changed. | They change nothing, so a client may run them without asking. |
| Destructive | update_thing, delete_thing, rename_workspace, remove_mark. | ChatGPT asks you to confirm each call. Claude shows its usual tool approval. |
| Write | The other 14 write tools. | They add or rearrange without removing anything. Your client's own tool permissions decide when it asks. |
what_changed carries no read-only hint because it moves the agent's own cursor. It changes nothing of yours, so a read-only connection may call it. Every write except create_workspace is also marked as reaching a shared space, since other members of the workspace see the change and most writes notify them.
Agent writes count toward your plan's limits exactly as your own do. See Plans & limits.
Workspaces
| Tool | What it does | Access | Note |
|---|---|---|---|
| list_workspaces | Lists every workspace you can open with your role in it (owner, admin, editor or viewer), marks your default one, and includes each workspace's instructions for agents. | read | When you have no workspace at all, it first creates a Personal workspace from the Agent workflow template. While nothing in your account was written by you or an agent, it also suggests a first request to offer you. |
| get_workspace | Returns one workspace's id, name, your role in it, default marks in the order the app offers them, and its instructions for agents. | read | Its things come from list_things. |
| create_workspace | Creates a workspace with the name given. | read & write | |
| rename_workspace | Renames a workspace. Its images and members stay as they are. | read & write | Destructive: ChatGPT asks you first. The old name is kept nowhere. |
Finding and reading things
| Tool | What it does | Access | Note |
|---|---|---|---|
| search_things | Searches names, tags and content across every workspace you can open, and returns up to 20 matches with the total count. | read | Each match carries its workspace name and last update, and no content. Things in Trash are left out. |
| get_thing | Returns one thing with its full Markdown content, its parent and workspace, the agent that created or last changed it, any question on it, and any claim. | read | Also lists who has opened the thing on the web or the phone. |
| list_things | Lists the top-level things of a workspace, 100 by default and up to 500, with the total count. | read | |
| list_child_things | Lists the sub-things of a thing, 100 by default and up to 500, with the total count. | read | Shows any claim on each sub-thing. |
| recent_things | Lists the things most recently updated across all your workspaces, newest first, 20 by default and up to 100. | read | Can start from a given moment. Each row names the agent behind the latest write and says whether a question there is still open. |
| list_trash | Lists what is in a workspace's Trash, most recently deleted first. | read | Gives the ids restore_thing needs. |
Writing things
| Tool | What it does | Access | Note |
|---|---|---|---|
| create_thing | Creates a thing in a workspace, at the top level or under a parent, with a name and optionally an emoji and Markdown content. | read & write | Returns the new id only. Content sent as HTML is converted to Markdown. |
| update_thing | Changes a thing's name, emoji or content. Fields left out stay as they are. | read & write | Destructive: ChatGPT asks you first. New content replaces the old content in full, so an agent reads the thing first and sends the whole new text. |
| move_thing | Moves a thing under another parent in the same workspace, or to the top level. | read & write | The thing keeps its content, marks, comments and images. |
| reorder_things | Puts 2 to 500 sibling things in the order given. | read & write | Siblings left out keep their places. The parent stays the same. |
| copy_thing | Copies a thing and every sub-thing under it into a workspace, at the top level or under a parent there. | read & write | Copies carry content, tags and images. Marks, comments and things in Trash stay behind. |
| delete_thing | Moves a thing and its sub-things to Trash. | read & write | Destructive: ChatGPT asks you first. Calling it again changes nothing and reports unchanged. restore_thing brings the thing back until someone empties Trash in the app. |
| restore_thing | Brings a thing, and the sub-things trashed with it, back from Trash with content, marks and comments intact. | read & write | Returns to the top level when its parent is gone or still in Trash. |
Everything an agent writes carries its name. Other members' notifications about an agent's thing say “via” and the agent's name, and you can be notified of what your own agent did. See Notifications.
Marks and comments
| Tool | What it does | Access | Note |
|---|---|---|---|
| list_marks | Lists a thing's marks grouped by name: the count, who left each, which agent left one for its person, whether one is yours, and when each was left. | read | |
| add_mark | Adds your mark to a thing, by emoji and an optional name that defaults to the emoji. | read & write | Adding a mark that is already there changes nothing. The name peek is refused. |
| remove_mark | Removes your mark from a thing, by its name (the emoji itself unless a custom name was used). | read & write | Destructive: ChatGPT asks you first. The original mark and its time are gone; add_mark can only add a new one. |
| list_comments | Lists a thing's comments oldest first, 200 by default and up to 500. Replies point at the comment they answer. | read | Each row names the agent that wrote a comment through its person's account. |
| add_comment | Adds a top-level comment to a thing. | read & write | The apps show it via the agent. Members are notified as for any comment. |
| my_reception | Lists the marks people placed on this agent's work in the last 7 days (up to 30), grouped by mark, most used first. | read | Counts live things this agent created or last edited. Visits and marks left by agents are left out. |
Questions, mentions and what changed
These tools are how an agent hears from you between runs. The whole loop is described in Questions, inbox & @Agent.
| Tool | What it does | Access | Note |
|---|---|---|---|
| what_changed | Returns what people did since this agent's last run, per workspace: things they created, edited or trashed, answers to questions, and their marks and comments on agent work. | read | Moves the agent's own cursor, so it carries no read-only hint. A first call covers the last 7 days; advance: false looks without moving the cursor. |
| request_input | Asks you a question, open or with up to six options, on an existing thing or on a new thing it creates for the question. | read & write | Reaches your phone as a notification. Asking again on the same thing adds a follow-up round to the thread. |
| list_requests | Lists the questions agents asked in your workspaces and your answers, by status (open, answered, dismissed, resolved) or since a moment. | read | Says whether each waits on you or on the agent, and whether anyone opened the thing since it was asked. |
| answer_request | Records the answer you gave the agent: an option, your own words, or a dismissal. | read & write | Only for relaying what you said. When you already answered in the app it reports unchanged. |
| resolve_request | Closes an answered question thread so it reads as done. | read & write | Refused while the question is still open. Nobody is notified. |
| list_mentions | Lists the open @Agent jobs: comments in which someone wrote @Agent, oldest first, 50 by default and up to 100. | read | Writing @Agent notifies nobody, so this list is the only place a job shows up. |
| resolve_mention | Closes an @Agent job: @Agent becomes 🤖agent in the comment, and the agent's reply is posted under it. | read & write | The comment's author is notified of the reply. A second call changes nothing. |
Claims
A claim is a lease on a thing, for when several agent runs pick work from the same list. get_thing and list_child_things show any claim with its owner, host, note and expiry.
| Tool | What it does | Access | Note |
|---|---|---|---|
| claim_thing | Takes a lease on a thing before working on it, so another run skips it. | read & write | The result is claimed, or held along with the other run's claim. A claim lasts 240 minutes by default and up to 24 hours. The same host renews its own claim, and a live claim is never taken over. |
| release_thing | Gives a claim back, from the same host that took it. | read & write | Anyone may release an expired claim. An outcome such as done or abandoned is recorded with the call. |
Showing the view
The two view tools answer a whole screen in one call. Where the host supports MCP Apps, the answer draws as the view in the chat; elsewhere it arrives as the same data in text.
| Tool | What it does | Access | Note |
|---|---|---|---|
| get_workspace_view | Opens the workspace view: your workspaces, your default, and the top-level things of the workspace to land on, each with its marks. | read | A display tool, called when you ask to see your workspaces or one of them. |
| get_thing_view | Opens a thing's page: the thing with its content, its sub-things with their marks, its marks, its comments and the path above it. | read | A display tool, called when you ask to see a thing, or right after a create or edit you asked for. |
For its own reading, an agent uses get_thing, list_things, list_child_things and the other plain tools, so a page opens on your screen only when you asked for one.
ChatGPT compatibility
ChatGPT's connectors and Deep Research look for two tools named search and fetch. Everythings offers both as plain aliases. See ChatGPT & Codex.
| Tool | What it does | Access | Note |
|---|---|---|---|
| search | Searches your things and returns up to 20, each as an id, a title and a link to the thing in the app. | read | Same search as search_things. |
| fetch | Returns one thing's full Markdown content by the id search gave, with its title and link. | read | Same read as get_thing. |
What an agent is told
When an agent connects, the server hands it a short set of instructions along with the tools. They explain much of what your agent does without being asked.
Things are named after their topic
Agents learn that people call a thing by its topic, so “my music thing” or “the recipes thing” points at the thing named Music or Recipes. They search by that word first.
Every run starts the same way
what_changedcomes first, before any other read: what people created, edited or trashed, answers to questions, and marks and comments on agent work since the last run.list_mentionscomes next. For each @Agent job the agent reads the thing and the comment, does the work, and closes it withresolve_mentionand a short reply. When a job is unclear, it asks withrequest_inputand leaves the job open.list_requestswith the status answered picks up the answers it was waiting for. Before asking again, it checks whether anyone has opened the thing since it asked; if nobody has, it waits or says so in the chat.
Workspace instructions come first
A workspace's owner or an admin can write instructions for agents on the Agent Instructions tab of the workspace settings. Agents read them before writing to that workspace and follow them. See Workspaces.
Your role applies
An agent acts as you, so your role in a workspace limits it as it limits you: as a viewer it can read, comment and mark; as an editor it also creates things and changes its own and yours; as an admin it can change any thing. A write your role does not allow is refused with a message naming your role and what the action needs, and the agent tells you instead of retrying. See Sharing a workspace.
Asking you, and waiting
When a decision is yours and you are away from the chat, the agent calls request_input, preferably on the thing the question is about, and stops. It never answers its own question and uses answer_request only for what you actually said. A follow-up continues the same thread, and resolve_request closes it once the agent has what it needs. Your comments and marks on its work count as replies too, and the workspace's default marks are the shared vocabulary for them.
Reading and showing
The view tools are for you: an agent calls one when you ask to see, show or open something, or right after a write you asked for. Everything it reads for itself goes through the plain tools. When a view is on screen, the agent is told its reply need not repeat what the view shows.
Saying how sure it is
On a thing or a comment, an agent can record its confidence: guess, likely (a partial check) or verified (it ran or observed it), with a note on what that rests on. Rewriting the text without one clears the old one. Your ✅ mark on the thing counts as verification, and agents see who gave it.
Content is Markdown
Agents write GitHub-Flavored Markdown: headings, lists, tables, code blocks, task lists and links. A collapsible section is a fence: a line :::details Title, the section's Markdown, then a line :::. It shows closed; :::details+ Title shows it open, and a section inside a section takes a longer outer fence (::::details). Content sent with real HTML tags is converted from HTML, so agents send one format or the other.
Deletes stay undoable
Agents learn that delete_thing moves a thing to Trash, that move_thing beats deleting and recreating (which would lose marks and comments), and that update_thing replaces content in full, so editing means reading first.
Questions
Why does ChatGPT ask me before it edits a thing?
The server marks four tools as destructive: update_thing, delete_thing, rename_workspace and remove_mark. Each one overwrites or removes something: new content replaces the old text in full, a rename keeps no copy of the old name, a removed mark is gone with its time, and Trash can be emptied in the app.
ChatGPT follows that hint and asks you to confirm each call. Claude applies its usual tool approval, the same as for any connector.
Can an agent empty my Trash or delete a workspace?
No tool does either. delete_thing moves a thing and its sub-things to Trash, and restore_thing brings them back. Emptying Trash, deleting a thing for good and deleting a workspace stay actions you take yourself in the app.
What happens when an agent with read-only access tries to write?
The call fails and nothing changes. The agent gets this message back: “This token is read-only. Mint a write-scoped token to perform this action.”
For an agent on an access token, create a new token with the Read & write scope. For an agent that signed in, the Everythings sign-in screen lists the access it asked for before you press Approve.
How does my answer to an agent's question reach it?
Answer on the thing in the app or on your phone, or in the Inbox. The next time the agent runs, it starts with what_changed, which lists answers to its questions, and then reads list_requests with the status answered. If you are in the chat anyway, just tell it: it records your words with answer_request.
With the Claude Code plugin, a session that asked you something wakes up by itself once you answer. More in Questions, inbox & @Agent.
Does what_changed change my data?
It moves the agent's own cursor, so its next call returns only what is newer. Your things, marks and comments stay as they are, and a read-only connection may call it. Each agent name has its own cursor, so two agents on one account each see their own list.
Can two agents work through the same list?
Yes. Each run calls claim_thing before it starts on a thing. When another run already holds it, the answer is held and the agent picks something else. release_thing gives the thing back when the work is done, and a claim nobody releases runs out on its own.
Why does my agent show me the thing after it writes it?
Agents are told to follow a create or edit you asked for with get_thing_view, so the finished thing appears in front of you to confirm or correct. In Claude, and in ChatGPT on the web, it draws as the Everythings view.