# MCP tools: what an AI agent can do

*Everything a connected AI agent can find, use and change in PromptMason, what works in Read-only, and requests you can try.*

Online version: https://promptmason.ai/docs/agent-tools

These are the tools PromptMason's [built-in MCP server](https://promptmason.ai/docs/mcp-server) gives an AI agent. Once PromptMason is connected to your AI agent (see [Connect an AI agent through MCP](https://promptmason.ai/docs/connect-ai-agent)), you ask the agent in plain words and it uses PromptMason's tools to do the work. What it may do depends on **What connected apps can do** in **Settings → AI & connected apps** ([Control what connected apps can do](https://promptmason.ai/docs/agent-access)). PromptMason must be open while the agent works.

## Find and read (Read-only and Full access)

An agent can do all of this with either **Read-only** or **Full access**:

- **Search** your blocks, prompts and variables. A search looks at names, descriptions, text, tags, comments and expected output. Archived items are left out unless you ask for them. A search can also ask for only the blocks and prompts that use a variable nothing defines, and it names those variables.
- **List** your libraries, blocks, prompts, folders and variables.
- **Read** a block or a prompt, including its tags, folder and which prompts use a block. A variable shows which blocks, prompts and Markdown documents use it. For a Markdown document it gets the text exactly as stored.
- **Read the history** of a block or prompt, with the full text of each saved version.
- **Read comments and expected output** on a block or prompt.
- **Read your block types, prompt types and settings.** It can't change your settings.

## Use a prompt (Read-only and Full access)

An agent can get the finished text of a prompt, the same text you'd copy from the Prompts screen, with your variables filled in.

- If the prompt has values that are asked each time, PromptMason fills in neither the value nor its default until the agent sends one. It tells the agent to ask you for the values, or to confirm the defaults with you.
- If a variable offers a list of choices, the agent sees them and offers them to you. If the variable allows only values from its list, PromptMason refuses any other value and tells the agent which values are allowed.
- It can run the same prompt several times with different values, for example once for each item in a list.
- A block that was deleted shows as `[Block removed: name]`, and a block it can't reach shows as `[Block unavailable]`. The rest of the prompt still comes through.
- A Markdown document comes back exactly as written. Nothing in it is filled in.

See [Variables](https://promptmason.ai/docs/variables) for how values work.

## Create and change (Full access only)

With **Full access**, an agent can also change your library:

- **Blocks:** create, change, copy, archive, take out of the archive, and delete. A copy includes the block's expected output and attachments but not its comments, starts with no rating, and isn't a favorite.
- **Prompts:** create a static prompt, a dynamic prompt or a Markdown document; change a prompt's name, description, text, blocks, tags, Type, folder, rating or favorite; copy, archive, take out of the archive, and delete. A copy includes expected output but not comments, and starts with no rating and isn't a favorite. It can't turn a Markdown document into an ordinary prompt or the other way round. It can also create or replace a prompt from code (see [Edit a prompt as code](https://promptmason.ai/docs/code-view)).
- **Folders:** create (inside another folder too), rename, move and delete. An agent can also move blocks and prompts into a folder, or back to **My Files**.
- **Libraries:** move a block or prompt to another library, with its history, comments and expected output. Its favorite is cleared.
- **Variables:** create (a fixed value, or one asked each time with an optional default or a list of choices), change and delete. If a variable is deleted, prompts that use it keep `{{name}}` but it's no longer filled in.
- **Comments:** add, edit and delete.
- **Expected output:** add an entry (it needs the AI tool and model used) and delete one.
- **Tags:** add or remove tags without touching the others.

### Deleting

When an agent deletes a block or prompt, it goes to **Recently deleted** in the Archive screen for 30 days, so you can restore it there. An agent can't restore from **Recently deleted** and can't delete anything for good. In a team library, a deleted item is deleted for everyone. See [Archive, delete and restore](https://promptmason.ai/docs/archive-and-delete).

A folder that still has something in it isn't deleted unless the agent is asked to delete its contents too. Otherwise the agent reports "Folder is not empty — move or delete its contents first". When a folder is deleted with its contents, the blocks and prompts in it go to **Recently deleted**.

## What an agent can't do

Some things are only done in PromptMason itself:

- Create, join or share a library, or add, approve or remove people and PCs
- Your recovery kit and backups
- Change settings or tokens
- AI assist and Chat
- Import, export your whole library, or add a block pack
- Restore from **Recently deleted**, or delete for good

## Example requests

You can ask in your own words. For example:

- "Search PromptMason for my onboarding prompts."
- "Get the finished text of my Weekly report prompt. Ask me for any values it needs."
- "Run my Product description prompt once for each of these three products."
- "Show me the last three versions of my Cold email block and what changed." (The agent compares the versions itself.)
- "Save this paragraph as a new block called Brand voice in my Marketing folder." (Full access)
- "Make a dynamic prompt from my Role, Audience and Output format blocks." (Full access)
- "Add the tag draft to my Q3 launch prompt." (Full access)

If your AI app asks for permission before it uses a PromptMason tool, allow it.

## Team libraries

An agent sees your personal library and the team libraries on this PC that aren't hidden from AI apps. New blocks and prompts go to your personal library unless you ask for a specific library.

What an agent may do in a team library is set by its primary owner, and is **Read only (recommended)** unless they change it. Your own **What connected apps can do** setting still applies, and the stricter one wins. See [Set what AI apps can do in a team library](https://promptmason.ai/docs/agent-access#set-what-ai-apps-can-do-in-a-team-library).

Messages an agent may pass on:

| Message | What to do |
|---|---|
| "This library is read-only for AI apps. An owner can change this in Settings → Libraries & sharing." | The library allows AI agents to read only. Only the library's primary owner can change this, in **Settings → Libraries & sharing → Manage → Name and AI apps**. Ask them to change it. |
| "You can view this library but not change it. Ask a library owner for edit access." | You can only view this library. Ask a library owner for edit access. |
| "Too many changes from an AI app. Try again later." | The agent reached the library's limit of changes per hour. Try again later, or ask the primary owner to raise **Most changes an AI app can make per hour**. |

In a team library, a change an agent made is marked **via AI app**.

## Free plan limits and a paused library

On the Free plan you can have up to 25 blocks and 15 prompts, counted across all your libraries. Markdown documents count as prompts. If an agent tries to create or copy past a limit, PromptMason refuses and the agent passes on a message that starts "The Free plan includes up to…". Upgrade to Pro, or permanently delete items you no longer need (archived items count). See [Plans and limits](https://promptmason.ai/docs/plans).

If your library is paused (on the Free plan and over a limit after your 14 days of Pro or Pro end), an agent can't search, read, use or change anything, even in **Read-only**. It passes on a message that starts "Your library is paused." See [When your library is paused](https://promptmason.ai/docs/paused-library).

## Tool names

Some AI apps show the name of each tool when they ask for permission. This is what each one does. The last column shows whether it works when **What connected apps can do** is set to **Read-only**.

### Find and read

| Tool | What it does | Works in Read-only |
|---|---|---|
| `search` | Finds blocks, prompts and variables by words, tags, folder, type or favorite, and says where each match was found. | Yes |
| `list_libraries` | Lists your personal library and the team libraries an AI app can see, with each one's name, your role in it and what AI apps may do there. | Yes |
| `list_blocks` | Lists all your blocks, in every library the agent can see. | Yes |
| `get_block` | Reads one block in full, including which prompts use it. | Yes |
| `list_prompts` | Lists all your prompts and Markdown documents, or only one of the two. | Yes |
| `get_prompt` | Reads one prompt or Markdown document in full. | Yes |
| `get_markdown` | Returns the text of a Markdown document exactly as saved, ready to save as a file. It refuses an ordinary prompt. | Yes |
| `list_folders` | Lists all your folders, in every library the agent can see. | Yes |
| `list_variables` | Lists all your variables and shows where each one is used. | Yes |
| `list_versions` | Lists the saved versions of a block or prompt, newest first, each with its full text. | Yes |
| `list_notes` | Lists the comments on a block or prompt, oldest first. | Yes |
| `list_expected_outputs` | Lists the expected output entries saved on a block or prompt, newest first. | Yes |
| `get_config` | Lists your block types and prompt types. | Yes |
| `get_settings` | Reads your PromptMason settings. It can't change them. | Yes |

### Use a prompt

| Tool | What it does | Works in Read-only |
|---|---|---|
| `resolve_prompt` | Returns the finished text of a prompt with its variables filled in, and says which ask-each-time values it still needs before it can. | Yes |

### Blocks

| Tool | What it does | Works in Read-only |
|---|---|---|
| `create_block` | Saves a new block, in your personal library unless you name another. | No |
| `update_block` | Changes an existing block. | No |
| `copy_block` | Makes a copy of a block with its expected output and attachments, but not its comments. | No |
| `archive_block` | Archives a block, so it leaves the main list but keeps its history. | No |
| `restore_block` | Takes a block out of the archive. It doesn't restore from **Recently deleted**. | No |
| `delete_block` | Moves a block to **Recently deleted**, where it can be restored for 30 days. | No |

### Prompts

| Tool | What it does | Works in Read-only |
|---|---|---|
| `create_prompt` | Saves a new static prompt, dynamic prompt or Markdown document. | No |
| `update_prompt` | Changes a prompt's name, description, text, blocks, tags, Type, folder, rating or favorite. It can't change whether it's a Markdown document. | No |
| `create_prompt_from_code` | Saves a new prompt from code, and can create new blocks in the same step. | No |
| `update_prompt_from_code` | Replaces a prompt's blocks with the ones in the code. It isn't used for Markdown documents. | No |
| `copy_prompt` | Makes a copy of a prompt with its expected output, but not its comments. | No |
| `archive_prompt` | Archives a prompt, so it leaves the main list but keeps its history. | No |
| `restore_prompt` | Takes a prompt out of the archive. It doesn't restore from **Recently deleted**. | No |
| `delete_prompt` | Moves a prompt to **Recently deleted**, where it can be restored for 30 days. | No |

### Folders and libraries

| Tool | What it does | Works in Read-only |
|---|---|---|
| `create_folder` | Creates a folder, at the top level or inside another folder. | No |
| `rename_folder` | Renames a folder, or moves it inside another folder. | No |
| `delete_folder` | Deletes a folder. If it has anything in it, it refuses unless asked to delete the contents too, and then the blocks and prompts go to **Recently deleted**. | No |
| `move_block_to_folder` | Moves a block into a folder, or back to **My Files**. | No |
| `move_prompt_to_folder` | Moves a prompt into a folder, or back to **My Files**. | No |
| `move_to_library` | Moves a block or prompt to another library with its history, comments and expected output. It refuses a move that would leave a prompt without its blocks, and names them. | No |

### Variables

| Tool | What it does | Works in Read-only |
|---|---|---|
| `create_variable` | Creates a variable with a fixed value, or one asked each time with an optional default or list of choices. | No |
| `update_variable` | Renames a variable or changes its value, description, default or choices. | No |
| `delete_variable` | Deletes a variable. Prompts that use it keep `{{name}}` but it's no longer filled in. | No |

### Comments, expected output and tags

| Tool | What it does | Works in Read-only |
|---|---|---|
| `create_note` | Adds a comment to a block or prompt. | No |
| `update_note` | Edits a comment. | No |
| `delete_note` | Deletes a comment. | No |
| `create_expected_output` | Adds an expected output entry to a block or prompt. It needs the AI tool and model used. | No |
| `delete_expected_output` | Deletes an expected output entry. | No |
| `add_tags` | Adds tags to a block or prompt and keeps the ones it already has. | No |
| `remove_tags` | Removes the named tags from a block or prompt and keeps the rest. | No |

`restore_block` and `restore_prompt` take an item out of the archive. They don't restore from **Recently deleted**.

## Want a hand?

Paste this prompt into Claude, ChatGPT or another AI assistant, together with this guide, to be walked through it step by step:

> I've connected PromptMason to my AI agent. Show me what I can ask it to do with my blocks and prompts, and suggest a few requests I can try for my kind of work.