Tool reference

This is the complete list of tools an API key can see. Your client sees only the tools whose permission your key holds - see MCP overview. Each tool returns one text item containing a JSON document; the result shapes are shown per tool.

How to read this page. Read tools only read. Write tools create, change, delete or send something. Async tools return before the work is done and must be polled. Arguments typed number are read as integers unless noted. Paged tools take limit and offset and return total_count, limit and offset.

At a glance

Area	Tools
Chat and conversations	send_message, get_conversation, list_conversations, delete_conversation
Prompts and runs	list_prompts, get_prompt, run_prompt, custom_run, list_ai_models
Agents and workflows	list_agents, get_agent, list_workflow_tasks, get_workflow_task, run_workflow_task
Knowledge and files	list_knowledge_bases, search_knowledge_base, list_files, get_file
Projects and teams	list_projects, get_project, create_project, delete_project, list_workspace_members, list_teams, list_team_members
Media generation	generate_image, edit_image, generate_video, get_video_generation_status, delete_video_generation, generate_speech, get_tts_generation_status, delete_tts_generation, generate_music, get_music_generation_status, delete_music_generation
Transcription	transcribe, get_transcription_status, delete_transcription
Spreadsheets	list_spreadsheet_processing_tasks, get_spreadsheet_processing_task, start_spreadsheet_processing, pause_spreadsheet_processing, resume_spreadsheet_processing
Integrations: email	list_email_connections, send_email
Integrations: CRM	list_crm_connections, search_crm_contacts, list_crm_contacts, add_crm_contact, edit_crm_contact, search_crm_deals, list_crm_deals, create_crm_deal, list_crm_lists, list_crm_tags
Integrations: databases	list_database_connections, list_database_tables, describe_database_tables, run_database_query
Integrations: storage	list_storage_connections, browse_storage_folder, search_storage_files, get_storage_entry, import_storage_files, export_file_to_storage
Search	search
Staff only	get_usage_statistics

Chat and conversations

send_message

Send a message to an AI model and get its response, synchronously. Omit conversation_id to start a new conversation; pass one to continue it. This creates or updates the same conversation you see in the StickyPrompts app.

Write Permission conversations_manage

Result: {"conversation_id": <id>, "text": "<assistant reply>"}. A message that @mentions one of your agents by its tag is routed to that agent, as in the app. Errors: tool error conversation not found; model and provider failures are JSON-RPC errors.

get_conversation

Get a conversation you own, including its message transcript.

Read Permission conversations_get

Result: {"id", "name", "messages": [{"is_user": bool, "text": "..."}]}. Errors: tool error conversation not found.

list_conversations

List your own interactive conversations (not team-shared or agent ones), a page at a time, most recently updated first.

Read Permission conversations_get

Result: {"conversations": [{"id", "name"}], "total_count", "limit", "offset"}.

delete_conversation

Delete a conversation you own.

Write Destructive Permission conversations_delete

Result: {"deleted": true}. Errors: tool error conversation not found.

Prompts and runs

list_prompts

List your own prompts (not project-scoped, and not prompts shared with you), a page at a time. Use get_prompt afterwards to see a prompt’s variables before calling run_prompt.

Read Permission prompts_get

Result: {"prompts": [{"id", "name", "slug", "description", "is_favorite"}], "total_count", "limit", "offset"}.

get_prompt

Get a prompt you own, including its current version’s content and the variables it accepts.

Read Permission prompts_get

Result: {"id", "name", "slug", "description", "content", "variables": [{"slug", "name", "description", "required", "default_value"}]}. Errors: tool error prompt not found, also for prompts shared with you that you do not own.

run_prompt

Fill in a prompt’s variables and run it against a model, returning the response text. Runs as a single detached call; it does not create an interactive conversation in the app.

Write Permission run_prompt

Result: {"text": "<model response>"}. Errors: tool errors prompt not found, prompt has no current version, variable "<slug>" must be a string, missing a value for a required variable, or the sensitive-data message if a guardrail blocks the filled prompt. Model and provider failures are JSON-RPC errors.

custom_run

Run raw prompt text against a model and return the response text, without a saved prompt. Runs as a single detached call; it does not create a conversation.

Write Permission custom_run

Result: {"text": "<model response>"}.

list_ai_models

List the models available to run against, excluding models restricted by your workspace (including data-residency rules) and, by default, deprecated models.

Read Permission ai_models_get

Result: {"models": [{"id", "name", "powered_by", "description", "premium"}]}, in the platform’s sort order.

Agents and workflows

list_agents

List your own agents (not agents shared with you by a team or workspace). Not paginated.

Read Permission agents_get

Result: {"agents": [{"id", "name", "slug", "tag"}]}. The tag is what you @mention in send_message.

get_agent

Get an agent you have access to, including its system prompt and configured model.

Read Permission agents_get

Result: {"id", "name", "slug", "description", "system_prompt", "ai_model_id", "ai_model_name"}. Errors: tool errors agent not found, you don't have access to this agent.

list_workflow_tasks

List your own scheduled workflow tasks, a page at a time.

Read Permission workflow_tasks_get

Result: {"workflow_tasks": [{"id", "name", "slug", "enabled"}], "total_count", "limit", "offset"}.

get_workflow_task

Get a workflow task you manage, including its instructions and run success rate.

Read Permission workflow_tasks_get

Result: {"id", "name", "slug", "description", "instructions", "enabled", "total_run_count", "success_rate"}. Errors: tool error workflow task not found or access denied.

run_workflow_task

Start a run of a workflow task right now, outside its schedule. Returns immediately with the new execution’s id and status; it does not wait for the run to finish.

Write Async Permission workflow_tasks_manage

Result: {"execution_id": <id>, "status": "running"}. There is no MCP tool to read an execution’s outcome: once it finishes, get_workflow_task’s total_run_count and success_rate reflect it. If the owner is out of quota, the execution fails with quota exceeded. Errors: tool error workflow task not found or access denied.

Knowledge and files

list_knowledge_bases

List the knowledge bases you own or have been given access to.

Read Permission knowledge_bases_get

No arguments. Result: {"knowledge_bases": [{"id", "name", "description"}]}.

search_knowledge_base

Search a knowledge base for passages relevant to a query, returning the passages and the files they came from. This is the same semantic search a conversation uses; it has no REST equivalent.

Read Permission knowledge_bases_get

Result: {"context": "<retrieved passages as text>", "files": [{"id", "name"}]}. Recorded as knowledge-base usage. Errors: tool error knowledge base not found or access denied, or the retrieval error message.

list_files

List your own uploaded and generated files, newest first, a page at a time. There is no MCP tool for uploading files.

Read Permission files_get

Result: {"files": [{"id", "name", "file_type"}], "total_count", "limit", "offset"}.

get_file

Get metadata for a file you own, for example to pass its ID to edit_image.

Read Permission files_get

Result: {"id", "name", "file_type"} - no URL and no content. Errors: tool error file not found or access denied.

Projects and teams

list_projects

List the projects you own or that are shared with you, a page at a time.

Read Permission projects_get

Result: {"projects": [{"id", "name", "slug", "description"}], "total_count", "limit", "offset"}.

get_project

Get a project you have access to.

Read Permission projects_get

Result: {"id", "name", "slug", "description", "instructions"}. Errors: tool errors project not found, you don't have access to this project.

create_project

Create a new project that you own.

Write Permission projects_manage

Result: {"id", "slug", "name"}.

delete_project

Delete a project you own. Only the owner can delete.

Write Destructive Permission projects_delete

Result: {"deleted": true}. Errors: tool errors project not found, you don't have access to this project.

list_workspace_members

List the members of your workspace, a page at a time.

Read Permission organization_get

Result: {"members": [{"id", "email", "first_name", "last_name", "is_owner", "permissions": [...]}], "total_count", "limit", "offset"}. The workspace owner is always reported with permissions: ["admin"].

list_teams

List all teams in your workspace. Not paginated.

Read Permission teams_get

Result: {"teams": [{"id", "name", "description", "color", "member_count"}]}.

list_team_members

List the members of a team, a page at a time. You must be a workspace admin or a member of the team.

Read Permission teams_get

Result: {"members": [{"id", "email", "first_name", "last_name", "role"}], "total_count", "limit", "offset"}. Errors: JSON-RPC errors team not found, not authorized to view the members of this team.

Media generation

The media tools take no model argument: StickyPrompts uses the configured model for each medium. Results include path, the stored file’s direct URL (not a signed or expiring link), and _attachments, a list of {"type": "file", "id": <file id>} items whose ids you can pass to other tools.

generate_image

Generate an image from a prompt.

Write Permission image_generation_manage

Result (synchronous): {"path": "<storage URL>", "_attachments": [{"type": "file", "id": <file id>}]}.

edit_image

Edit an existing image based on instructions. Returns a new file.

Write Permission image_generation_manage

Result: same shape as generate_image, with a new file id. Errors: JSON-RPC error file not found or access denied.

generate_video

Start generating a video from a prompt, optionally animating a starting image. Returns immediately with the generation’s id and status; poll get_video_generation_status until it reports done or error. Generation can take several minutes.

Write Async Permission video_generation_manage

Result: {"id": <video generation id>, "status": "queued"}. Errors: JSON-RPC errors for an unsupported aspect ratio, resolution or duration, an invalid image combination, or a model your workspace may not use.

get_video_generation_status

Check a video generation started by generate_video. Status is queued, processing, done or error. While it is queued or processing, wait (for example 15-60 seconds) and call again.

Read Permission video_generation_get

Result: {"id", "status"}, plus error when the status is error, or path and _attachments when it is done. Errors: not found is a JSON-RPC error.

delete_video_generation

Delete a video generation you own.

Write Destructive Permission video_generation_delete

Result: {"deleted": true}.

generate_speech

Convert text to spoken audio. Returns once the audio is ready.

Write Permission tts_generation_manage

Result (synchronous): {"path": "<storage URL>", "_attachments": [{"type": "file", "id": <file id>}]}. No generation id is returned.

get_tts_generation_status

Check a past text-to-speech generation. Status is queued, processing, done or error. Because generate_speech does not return a generation id, you would use an id from the app or the REST API.

Read Permission tts_generation_get

Result: {"id", "status"}, plus error, or path and _attachments when done. Errors: tool error tts generation not found.

delete_tts_generation

Delete a text-to-speech generation you own.

Write Destructive Permission tts_generation_delete

Result: {"deleted": true}.

generate_music

Generate a piece of music from a text prompt. Returns once the audio is ready.

Write Permission music_generation_manage

Result (synchronous): {"path", "duration_seconds", "_attachments"}, plus lyrics when the model produced lyrics. No generation id is returned.

get_music_generation_status

Check a past music generation. Status is queued, processing, done or error. Because generate_music does not return a generation id, you would use an id from the app or the REST API.

Read Permission music_generation_get

Result: {"id", "status"}, plus error, or path, duration_seconds, _attachments (and lyrics if any) when done. Errors: tool error music generation not found.

delete_music_generation

Delete a music generation you own.

Write Destructive Permission music_generation_delete

Result: {"deleted": true}.

Transcription

transcribe

Transcribe audio or video to text from a public URL. Returns once the transcript is ready, so give your client a generous timeout for long media.

Write Permission transcription_manage

Result (synchronous): {"text": "<transcript>", "_attachments": [{"type": "transcription", "id": <transcription id>}]}. The transcription id is only in _attachments.

get_transcription_status

Check a past transcription. Status is queued, fetching, preparing, processing, done or error.

Read Permission transcription_get

Result: {"id", "status"}, plus error, or text and _attachments when done. Errors: tool error transcription not found.

delete_transcription

Delete a transcription you own.

Write Destructive Permission transcription_delete

Result: {"deleted": true}.

Spreadsheets

Spreadsheet processing runs a prompt template against each row of an xlsx sheet and writes the answer into an output column. All five tools return a task object: {"task_id", "status", "processed_rows", "total_rows", "original_file_id", "created_at", "credit_cost"}, plus error, result_preview, eta and generated_file_id when present. Status values: queued, initializing, processing, paused, done, error.

list_spreadsheet_processing_tasks

List your own spreadsheet processing tasks, a page at a time.

Read Permission spreadsheet_processing_get

Result: {"tasks": [task], "total_count", "limit", "offset"}.

get_spreadsheet_processing_task

Get the status and progress of a task you own.

Read Permission spreadsheet_processing_get

Result: a task object. Errors: tool error task not found. A poll immediately after starting may briefly report this while the task is being created.

start_spreadsheet_processing

Start processing an xlsx file you already have in StickyPrompts. Runs in the background and returns a task_id at once; poll get_spreadsheet_processing_task until the status is done or error.

Write Async Permission spreadsheet_processing_manage

Result: {"task_id": "<32-character id>"}. Errors: tool error file not found.

pause_spreadsheet_processing

Pause a running task you own. Only tasks that are queued, initializing or processing can be paused.

Write Permission spreadsheet_processing_manage

Result: the task object. Errors: tool errors task not found, file processing cannot be paused currently, file processing is already paused, file processing is already finished, file processing is not running.

resume_spreadsheet_processing

Resume a paused task you own. It is queued again, and any partial output file is discarded and regenerated.

Write Async Permission spreadsheet_processing_manage

Result: the task object with status: "queued". Errors: tool errors task not found, file processing is already running, file processing is already finished, file processing is not paused.

Integrations: email

Works with the email account connected in StickyPrompts (Postmark, Resend, SendGrid or SMTP). Connections are set up in the app; see Email sending.

list_email_connections

List the email accounts you have connected, personal or shared with your workspace. Returns an empty list if none is connected.

Read Permission integration_email_get

No arguments. Result: {"connections": [{"connection_id", "provider", "name", "description", "sends_from"}]}.

send_email

Send an email through one of your connected email accounts. This really delivers mail and cannot be undone, so confirm recipients and content before calling it. Either html_body or text_body is required.

Write Permission integration_email_manage

Result: {"message_id": "...", "provider": "..."}.

Integrations: CRM

Works with ActiveCampaign, Brevo or Pipedrive connected in StickyPrompts; see CRM. The write tools (add_crm_contact, edit_crm_contact, create_crm_deal) also need the connection itself to allow write access. Connections are read-only by default.

list_crm_connections

List the CRM accounts you have connected, personal or shared with your workspace. Returns an empty list if none is connected.

Read Permission integration_crm_get

No arguments. Result: {"connections": [{"connection_id", "provider", "name", "description"}]}.

search_crm_contacts

Search contacts in a connected CRM. Use it before edit_crm_contact to find the contact, or before add_crm_contact to avoid duplicates.

Read Permission integration_crm_get

Result: {"contacts": [{"remote_id", "provider", "contact"}]}.

list_crm_contacts

Browse contacts a page at a time, in the provider’s own order, with no query.

Read Permission integration_crm_get

Result: {"contacts": [...], "has_more": bool, "next_cursor": "..."} (next_cursor omitted when empty).

add_crm_contact

Add a new contact. Always creates a new contact and never updates an existing one.

Write Permission integration_crm_manage

Result: {"remote_id", "provider", "contact": {...}}.

edit_crm_contact

Edit an existing contact, looked up by email. Fails if no contact with that email exists; it never creates one.

Write Permission integration_crm_manage

Omitted fields are left unchanged; an explicitly sent empty string clears the field. Result: {"remote_id", "provider", "contact": {...}}.

search_crm_deals

Search deals by title or by the linked contact’s email. Use it before create_crm_deal to check for an existing deal.

Read Permission integration_crm_get

Result: {"deals": [{"remote_id", "provider", "deal"}]}.

list_crm_deals

Browse deals a page at a time, in the provider’s own order. Not every CRM provider manages deals; check the connection’s provider first.

Read Permission integration_crm_get

Result: {"deals": [...], "has_more", "next_cursor"}.

create_crm_deal

Create a deal linked to an existing contact. Not every CRM provider manages deals; check the connection’s provider first.

Write Permission integration_crm_manage

Result: {"remote_id", "provider", "deal": {"title", "value", "currency", "contact_email", "stage"}}.

list_crm_lists

List the contact lists or segments on a connected CRM (Brevo and ActiveCampaign only, not Pipedrive). Use the ids as a list_id filter or in list_ids.

Read Permission integration_crm_get

Result: {"lists": [{"id", "name"}]}.

list_crm_tags

List the contact tags on a connected CRM (ActiveCampaign only). Use the ids as a tag_id filter or in tag_ids.

Read Permission integration_crm_get

Result: {"tags": [{"id", "name"}]}.

Integrations: databases

Works with MySQL, MariaDB, PostgreSQL and SQL Server databases connected in StickyPrompts; see Databases. Each connection has its own permission level, which is the real guard on what a query may do: read_only accepts only a single SELECT or WITH statement, create_update also allows a single INSERT or UPDATE, and full_access applies no filtering.

list_database_connections

List the databases you have connected, personal or shared with your workspace, with each connection’s database_permission. Returns an empty list if none is connected.

Read Permission integration_database_get

No arguments. Result: {"connections": [{"connection_id", "provider", "name", "description", "database_permission"}]}.

list_database_tables

List the tables and views in a connected database, without column detail.

Read Permission integration_database_get

Result: {"tables": ["schema.name", ...]}.

describe_database_tables

Get column detail (name, data type, nullability) for specific tables.

Read Permission integration_database_get

Result: {"tables": [{"schema", "name", "columns": [{"name", "data_type", "nullable"}]}]}. Errors: JSON-RPC error for a table reference without a dot.

run_database_query

Run a single statement against a connected database, within the connection’s permission level. Row count and timeout are clamped on the server.

Write Destructive Permission integration_database_manage

Result: {"columns": [...], "rows": [[...]], "row_count": n, "truncated": bool}. The API-key permission only decides whether the tool is callable; connect the database as Read only if a key should never change data.

Integrations: storage

Works with Google Drive. The provider argument on every storage tool accepts the single value google_drive. Storage connections are personal, not shared with the workspace.

Several tools return a RemoteEntry object: {"id", "name", "kind", "mime_type", "size", "modified_at", "icon_url", "web_url", "parent_id", "shared", "owned_by_me", "can_add_children", "importable", "import_name"}.

list_storage_connections

List the cloud drives you have personally connected. Returns an empty list if none is connected.

Read Permission integration_storage_get

No arguments. Result: {"connections": [{"provider", "name", "description", "account_name"}]}.

browse_storage_folder

List the folders and files directly inside a folder. Omit folder_id to browse the root.

Read Permission integration_storage_get

Result: {"entries": [RemoteEntry], "next_page_token", "breadcrumbs": [RemoteEntry]}. Breadcrumbs run root-first when the provider can resolve them.

search_storage_files

Search a connected drive by name or content, optionally within one folder.

Read Permission integration_storage_get

Result: {"entries": [...], "next_page_token", "breadcrumbs": null}.

get_storage_entry

Get metadata for a single file or folder, from a browse or search result’s id.

Read Permission integration_storage_get

Result: a single RemoteEntry.

import_storage_files

Download files from a connected drive and save them as StickyPrompts files. Google Docs, Sheets and Slides are converted to PDF, XLSX and PPTX; Google Forms, Sites and Apps Script projects cannot be imported. Entries succeed or fail independently. This is the only way to bring a new file into StickyPrompts over MCP.

Write Permission integration_storage_manage

Result: {"files": [{"id", "name", "file_type"}], "failed": [{"entry_id", "error"}], "_attachments": [...]}. Check failed even when some files succeed. The file ids work with edit_image, generate_video and start_spreadsheet_processing.

export_file_to_storage

Upload one of your StickyPrompts files to a folder on a connected drive. The folder must already exist and be writable by the connected account.

Write Permission integration_storage_manage

Result: {"entry": RemoteEntry} for the uploaded file.

Search

search

Search your own prompts and conversations by name and text. Unlike search in the app, this does not include prompts shared with you or the public prompt catalogue.

Read Permission search

Result: {"prompts": [{"id", "name", "description"}], "conversations": [{"id", "name", "relevant_message": {"id", "text"}}]} - at most 5 of each. Matched text is trimmed to about 50 characters around the first match, with the match wrapped in <span class="search-highlight">...</span>.

Staff only

get_usage_statistics

Returns the caller’s credit usage and run count over a date range, by category. It needs statistics_get, a permission reserved for StickyPrompts staff that customers cannot put on a key, so this tool never appears for customer keys. Workspace admins see usage in the app under Usage, credits and billing.

Read Permission statistics_get (staff only)

Result: {"from_date", "to_date", "total_credits", "total_runs", "by_category": [{"category", "credits", "runs"}]}.