MCP reference

MCP tool reference

All tools currently registered by the PrompTessor MCP server, grouped by workflow and required scope.

Verified against the implementation · 2026-09-09

Complete tool contracts

Expand any tool below for selection guidance, inputs, outputs, credits, history behavior, side effects, safety annotations, retry rules, examples, and errors. These entries and the live MCP metadata share one catalog so names, descriptions, scopes, and safety hints stay synchronized.

Confirm consequential actions

Request confirmation before delete, cancel, publish, unpublish, save, or vote actions when the user intent is not explicit. Publishing makes prompt content public.

AI workflow tools

Tool	Scope	Credits	Primary effect
generate_prompt	prompts:generate	1	Runs an AI workflow and writes generator history.
analyze_prompt	prompts:analyze	1	Runs an AI analysis and writes optimization history.
optimize_prompt	prompts:optimize	1	Runs an AI optimization and writes optimization history.
analyze_and_optimize_prompt	prompts:analyze + prompts:optimize	1	Runs AI analysis and optimization and writes history.
refine_prompt	prompts:refine	1	Runs AI refinement and writes refinement history.
refine_optimized_prompt	prompts:refine	1	Runs AI refinement and modifies existing optimization history.
reverse_prompt_from_text	prompts:reverse	1	Runs an AI reverse-prompt operation.
reverse_prompt_from_url	prompts:reverse	1	Fetches a public URL and runs an AI reverse-prompt operation; it does not change the external site.
reverse_prompt_from_image	prompts:reverse	1	Runs AI analysis and consumes/deletes the temporary image best-effort.
reverse_prompt_from_video_frames	prompts:reverse	1	Runs AI analysis over the supplied frames.

generate_prompt

Create a complete ready-to-use prompt or a reusable prompt template from a user goal. Use this for prompt creation; use optimize_prompt when a complete prompt already exists.

Required scope: prompts:generate
Credits: 1 credit when a new operation succeeds; an idempotent replay is not charged again.
History: Creates or updates Prompt Generator history.
Side effects: Runs an AI workflow and writes generator history.
Retry behavior: Retry the same arguments with the same clientRequestId. Use a new clientRequestId for a new logical operation.

Inputs

message: string, 1-6,000 characters (required)
mode: generator mode; default auto
outputMode: ready_to_use | reusable; default ready_to_use
targetModel: supported model; default Universal AI
language: 2-20 characters; default en
generationId/currentPrompt/conversation/attachmentIds: optional continuation context
clientRequestId: unique 8-255 character retry key (required)

Output

id, object, status
data: generated prompt result
history: generation id when stored
usage: creditsCharged and source

Safety annotations

readOnlyHint: falsedestructiveHint: falseidempotentHint: trueopenWorldHint: false

{
  "message": "Create a launch plan for a privacy-first budgeting app",
  "mode": "planning",
  "outputMode": "ready_to_use",
  "targetModel": "ChatGPT",
  "language": "en",
  "clientRequestId": "launch-plan-001"
}

Tool-specific errors

invalid_arguments / idempotency_conflict / rate_limit_exceeded / concurrency_limit_exceeded / usage_exhausted

analyze_prompt

Evaluate an existing prompt and return its analysis without creating optimized versions. Use optimize_prompt for rewriting, or analyze_and_optimize_prompt when both are requested.

Required scope: prompts:analyze
Credits: 1 credit when a new operation succeeds; an idempotent replay is not charged again.
History: Creates optimization history containing the analysis.
Side effects: Runs an AI analysis and writes optimization history.
Retry behavior: Retry the same arguments with the same clientRequestId. Use a new clientRequestId for a new logical operation.

Inputs

prompt: string, 1-50,000 characters (required)
language/context/attachmentIds/targetModel: optional context
variationCount: 1 | 2; accepted but analysis does not need multiple rewrites
promptId: optional related prompt id
clientRequestId: unique 8-255 character retry key (required)

Output

id, object, status
data: analysis, metrics, strengths, weaknesses, and recommendations
history: optimization-history id
usage

Safety annotations

readOnlyHint: falsedestructiveHint: falseidempotentHint: trueopenWorldHint: false

{
  "prompt": "Write a launch post.",
  "targetModel": "ChatGPT",
  "language": "en",
  "clientRequestId": "analyze-launch-001"
}

Tool-specific errors

invalid_arguments / idempotency_conflict / rate_limit_exceeded / concurrency_limit_exceeded / usage_exhausted

optimize_prompt

Rewrite an existing prompt into one or two stronger versions. Use analyze_prompt for diagnosis only, or analyze_and_optimize_prompt when the user also wants a full analysis.

Required scope: prompts:optimize
Credits: 1 credit when a new operation succeeds; an idempotent replay is not charged again.
History: Creates optimization history.
Side effects: Runs an AI optimization and writes optimization history.
Retry behavior: Retry the same arguments with the same clientRequestId. Use a new clientRequestId for a new logical operation.

Inputs

prompt: string, 1-50,000 characters (required)
variationCount: 1 | 2; default 1
language/context/attachmentIds/targetModel/promptId: optional
clientRequestId: unique 8-255 character retry key (required)

Output

id, object, status
data: one or two optimized prompt versions
history: optimization-history id
usage

Safety annotations

readOnlyHint: falsedestructiveHint: falseidempotentHint: trueopenWorldHint: false

{
  "prompt": "Write a launch post.",
  "variationCount": 1,
  "targetModel": "ChatGPT",
  "clientRequestId": "optimize-launch-001"
}

Tool-specific errors

invalid_arguments / idempotency_conflict / rate_limit_exceeded / concurrency_limit_exceeded / usage_exhausted

analyze_and_optimize_prompt

Analyze an existing prompt and create one or two optimized versions in the same operation. Use when the user explicitly wants both diagnosis and rewriting.

Required scope: prompts:analyze + prompts:optimize
Credits: 1 credit when a new operation succeeds; an idempotent replay is not charged again.
History: Creates one combined optimization-history item.
Side effects: Runs AI analysis and optimization and writes history.
Retry behavior: Retry the same arguments with the same clientRequestId. Use a new clientRequestId for a new logical operation.

Inputs

prompt: string, 1-50,000 characters (required)
variationCount: 1 | 2; default 1
language/context/attachmentIds/targetModel/promptId: optional
clientRequestId: unique 8-255 character retry key (required)

Output

id, object, status
data: analysis plus optimized prompt versions
history: optimization-history id
usage

Safety annotations

readOnlyHint: falsedestructiveHint: falseidempotentHint: trueopenWorldHint: false

{
  "prompt": "Write a launch post.",
  "variationCount": 2,
  "clientRequestId": "analyze-optimize-001"
}

Tool-specific errors

invalid_arguments / idempotency_conflict / rate_limit_exceeded / concurrency_limit_exceeded / usage_exhausted

refine_prompt

Revise any prompt according to specific written feedback. Use this for a standalone prompt; use refine_optimized_prompt to append a revision to existing optimization history.

Required scope: prompts:refine
Credits: 1 credit when a new operation succeeds; an idempotent replay is not charged again.
History: Creates or continues standalone refinement history.
Side effects: Runs AI refinement and writes refinement history.
Retry behavior: Retry the same arguments with the same clientRequestId. Use a new clientRequestId for a new logical operation.

Inputs

prompt: string, 1-50,000 characters (required)
feedback: string, 1-10,000 characters (required)
language/attachmentIds/targetModel/refinementId: optional
clientRequestId: unique 8-255 character retry key (required)

Output

id, object, status
data: refined prompt result
history: standalone refinement id
usage

Safety annotations

readOnlyHint: falsedestructiveHint: falseidempotentHint: trueopenWorldHint: false

{
  "prompt": "Write a launch post.",
  "feedback": "Make it concise and add a clear call to action.",
  "clientRequestId": "refine-launch-001"
}

Tool-specific errors

invalid_arguments / idempotency_conflict / rate_limit_exceeded / concurrency_limit_exceeded / usage_exhausted

refine_optimized_prompt

Revise one optimized version and attach the new version to its existing optimization history. Requires both the history id and source version id.

Required scope: prompts:refine
Credits: 1 credit when a new operation succeeds; an idempotent replay is not charged again.
History: Appends a refinement to the specified optimization history.
Side effects: Runs AI refinement and modifies existing optimization history.
Retry behavior: Retry the same arguments with the same clientRequestId. Use a new clientRequestId for a new logical operation.

Inputs

optimizationId: optimization-history id (required)
sourceVersionId: optimized version id (required)
feedback: string, 1-10,000 characters (required)
parentRefinementId/language/attachmentIds/targetModel: optional
clientRequestId: unique 8-255 character retry key (required)

Output

id, object, status
data: appended refined version
history: original optimization-history id
usage

Safety annotations

readOnlyHint: falsedestructiveHint: falseidempotentHint: trueopenWorldHint: false

{
  "optimizationId": "hist_125",
  "sourceVersionId": "version_1",
  "feedback": "Add an example.",
  "clientRequestId": "refine-version-001"
}

Tool-specific errors

invalid_arguments / idempotency_conflict / rate_limit_exceeded / concurrency_limit_exceeded / usage_exhausted

reverse_prompt_from_text

Infer a reusable source prompt from an existing text result. Use only when the source is text; this workflow intentionally does not create product history.

Required scope: prompts:reverse
Credits: 1 credit when a new operation succeeds; an idempotent replay is not charged again.
History: No product history is created.
Side effects: Runs an AI reverse-prompt operation.
Retry behavior: Retry the same arguments with the same clientRequestId. Use a new clientRequestId for a new logical operation.

Inputs

content: string, 10-100,000 characters (required)
language: default en
targetModel: default Universal AI
clientRequestId: unique 8-255 character retry key (required)

Output

id, object, status
data: inferred reusable prompt
usage

Safety annotations

readOnlyHint: falsedestructiveHint: falseidempotentHint: trueopenWorldHint: false

{
  "content": "A finished product announcement...",
  "language": "en",
  "clientRequestId": "reverse-text-001"
}

Tool-specific errors

invalid_arguments / idempotency_conflict / rate_limit_exceeded / concurrency_limit_exceeded / usage_exhausted

reverse_prompt_from_url

Inspect the visible experience at a public URL and infer a prompt that could recreate it. Use only for publicly reachable web pages; no product history is created.

Required scope: prompts:reverse
Credits: 1 credit when a new operation succeeds; an idempotent replay is not charged again.
History: No product history is created.
Side effects: Fetches a public URL and runs an AI reverse-prompt operation; it does not change the external site.
Retry behavior: Retry the same arguments with the same clientRequestId. Use a new clientRequestId for a new logical operation.

Inputs

url: absolute public URL, maximum 2,048 characters (required)
language: default en
targetModel: default Universal AI
clientRequestId: unique 8-255 character retry key (required)

Output

id, object, status
data: inferred website prompt
usage

Safety annotations

readOnlyHint: falsedestructiveHint: falseidempotentHint: trueopenWorldHint: false

{
  "url": "https://example.com",
  "language": "en",
  "clientRequestId": "reverse-url-001"
}

Tool-specific errors

invalid_arguments / idempotency_conflict / rate_limit_exceeded / concurrency_limit_exceeded / usage_exhausted

reverse_prompt_from_image

Infer a prompt from a completed temporary image upload. Call create_upload and complete_upload first; the image is deleted best-effort after processing.

Required scope: prompts:reverse
Credits: 1 credit when a new operation succeeds; an idempotent replay is not charged again.
History: No product history is created.
Side effects: Runs AI analysis and consumes/deletes the temporary image best-effort.
Retry behavior: Retry the same arguments with the same clientRequestId. Use a new clientRequestId for a new logical operation.

Inputs

uploadId: completed asset id with reverse_image scope (required)
language: default en
targetModel: default Universal AI
clientRequestId: unique 8-255 character retry key (required)

Output

id, object, status
data: inferred image prompt
usage

Safety annotations

readOnlyHint: falsedestructiveHint: falseidempotentHint: trueopenWorldHint: false

{
  "uploadId": "cmf_asset_123",
  "clientRequestId": "reverse-image-001"
}

Tool-specific errors

invalid_arguments / idempotency_conflict / rate_limit_exceeded / concurrency_limit_exceeded / usage_exhausted

reverse_prompt_from_video_frames

Infer a video-generation prompt from sampled image data URLs. Use 1-30 ordered frames and provide the original duration in seconds; no product history is created.

Required scope: prompts:reverse
Credits: 1 credit when a new operation succeeds; an idempotent replay is not charged again.
History: No product history is created.
Side effects: Runs AI analysis over the supplied frames.
Retry behavior: Retry the same arguments with the same clientRequestId. Use a new clientRequestId for a new logical operation.

Inputs

frames: 1-30 data:image/... URLs (required)
frameCount: integer 1-30 matching frames (required)
videoDuration: seconds, >0 and <=600 (required)
language/targetModel: optional defaults
clientRequestId: unique 8-255 character retry key (required)

Output

id, object, status
data: inferred video prompt
usage

Safety annotations

readOnlyHint: falsedestructiveHint: falseidempotentHint: trueopenWorldHint: false

{
  "frames": [
    "data:image/jpeg;base64,..."
  ],
  "frameCount": 1,
  "videoDuration": 8,
  "clientRequestId": "reverse-video-001"
}

Tool-specific errors

invalid_arguments / idempotency_conflict / rate_limit_exceeded / concurrency_limit_exceeded / usage_exhausted

Account, upload, and history tools

Tool	Scope	Primary effect
get_usage	usage:read	Read-only.
create_upload	uploads:write	Creates a temporary upload record and presigned URL.
complete_upload	uploads:write	Changes a temporary asset from pending to uploaded; deletes mismatched content.
list_history	history:read	Read-only.
get_history_item	history:read	Read-only.
delete_history_item	history:manage	Irreversible deletion.

get_usage

Read the connected account plan, credit usage, add-on balance, reset time, and Public API limits. Use this as the safest connection test; it does not consume an AI credit.

Required scope: usage:read
Credits: 0 credits.
History: No product history.
Side effects: Read-only.
Retry behavior: Safe to retry.

Inputs

No arguments.

Output

monthly usage and limit
add-on balance and availability
plan and next reset
api plan policy and rate limits

Safety annotations

readOnlyHint: truedestructiveHint: falseidempotentHint: trueopenWorldHint: false

{}

Tool-specific errors

invalid_arguments / insufficient_scope / rate_limit_exceeded / not_found

create_upload

Create a 15-minute presigned upload URL for an attachment that will be used by a later prompt workflow. Upload the exact declared content type and size before calling complete_upload.

Required scope: uploads:write
Credits: 0 credits.
History: No product history.
Side effects: Creates a temporary upload record and presigned URL.
Retry behavior: Not idempotent; retrying creates another upload id.

Inputs

scope: analysis | refinement | feedback | generation | reverse_image | reverse_video (required)
filename: 1-255 characters (required)
contentType: 1-100 characters (required)
size: positive integer bytes (required; plan limits apply)

Output

id and pending status
uploadUrl and requiredHeaders
uploadUrlExpiresAt and assetExpiresAt

Safety annotations

readOnlyHint: falsedestructiveHint: falseidempotentHint: falseopenWorldHint: false

{
  "scope": "reverse_image",
  "filename": "reference.png",
  "contentType": "image/png",
  "size": 245760
}

Tool-specific errors

invalid_arguments / upload_too_large / rate_limit_exceeded

complete_upload

Verify that bytes uploaded to a PrompTessor presigned URL match the declared content type and size, then mark the asset ready for a prompt workflow.

Required scope: uploads:write
Credits: 0 credits.
History: No product history.
Side effects: Changes a temporary asset from pending to uploaded; deletes mismatched content.
Retry behavior: Safe after success; a mismatch can delete the invalid asset.

Inputs

uploadId: asset id returned by create_upload (required)

Output

id, uploaded status, filename, content type, size, scope, expiry, and creation time

Safety annotations

readOnlyHint: falsedestructiveHint: falseidempotentHint: trueopenWorldHint: false

{
  "uploadId": "cmf_asset_123"
}

Tool-specific errors

upload_not_found / upload_expired / upload_incomplete / upload_mismatch

list_history

List the connected user’s generation, optimization, or standalone refinement history. Use this to obtain an id before get_history_item, refine_optimized_prompt, or delete_history_item.

Required scope: history:read
Credits: 0 credits.
History: Reads existing history only.
Side effects: Read-only.
Retry behavior: Safe to retry.

Inputs

type: generation | optimization | refinement (required)
search: optional, maximum 200 characters
limit: integer 1-100; default 25
offset: non-negative integer; default 0

Output

items
total, limit, and offset pagination fields

Safety annotations

readOnlyHint: truedestructiveHint: falseidempotentHint: trueopenWorldHint: false

{
  "type": "optimization",
  "limit": 25,
  "offset": 0
}

Tool-specific errors

invalid_arguments / insufficient_scope / rate_limit_exceeded / not_found

get_history_item

Read complete detail for one owned generation, optimization, or refinement history item. Use list_history when the id or type is unknown.

Required scope: history:read
Credits: 0 credits.
History: Reads existing history only.
Side effects: Read-only.
Retry behavior: Safe to retry.

Inputs

type: generation | optimization | refinement (required)
id: owned history id (required)

Output

The complete type-specific history record, including optimized refinements when applicable.

Safety annotations

readOnlyHint: truedestructiveHint: falseidempotentHint: trueopenWorldHint: false

{
  "type": "optimization",
  "id": "hist_125"
}

Tool-specific errors

history_not_found / invalid_arguments / insufficient_scope / rate_limit_exceeded / not_found

delete_history_item

Permanently delete one owned generation, optimization, or refinement history item. Use only after the user explicitly confirms the exact item.

Required scope: history:manage
Credits: 0 credits.
History: Deletes the selected history and associated stored attachment keys where applicable.
Side effects: Irreversible deletion.
Retry behavior: Idempotent at the desired state, although a repeated call may return deleted: false.

Inputs

type: generation | optimization | refinement (required)
id: owned history id (required)

Output

id
deleted: boolean

Safety annotations

readOnlyHint: falsedestructiveHint: trueidempotentHint: trueopenWorldHint: false

{
  "type": "generation",
  "id": "gen_123"
}

Tool-specific errors

history_not_found / insufficient_scope / rate_limit_exceeded

Prompt preset tools

Tool	Scope	Primary effect
list_prompt_presets	prompts:presets:read	Read-only.
get_prompt_preset	prompts:presets:read	Read-only.
create_prompt_preset	prompts:presets:write	Creates a private preset.
update_prompt_preset	prompts:presets:write	Updates an owned preset.
delete_prompt_preset	prompts:presets:write	Irreversible preset deletion.
render_prompt_preset	prompts:presets:read	Read-only; overrides are not saved.

list_prompt_presets

Search and paginate reusable prompt presets owned by the connected user. Use this to discover a preset id before reading, rendering, updating, or deleting it.

Required scope: prompts:presets:read
Credits: 0 credits.
History: No history change.
Side effects: Read-only.
Retry behavior: Safe to retry.

Inputs

search: optional, maximum 200 characters
limit: integer 1-100; default 25
offset: non-negative integer; default 0

Output

object=list
data: preset summaries
total, limit, offset, hasMore

Safety annotations

readOnlyHint: truedestructiveHint: falseidempotentHint: trueopenWorldHint: false

{
  "search": "launch",
  "limit": 25,
  "offset": 0
}

Tool-specific errors

invalid_arguments / insufficient_scope / rate_limit_exceeded / not_found

get_prompt_preset

Read one reusable prompt preset owned by the connected user, including its template, saved values, and detected variables.

Required scope: prompts:presets:read
Credits: 0 credits.
History: No history change.
Side effects: Read-only.
Retry behavior: Safe to retry.

Inputs

id: owned preset id (required)

Output

id, name, templateTitle, promptText
values and detected variables
generation links and timestamps

Safety annotations

readOnlyHint: truedestructiveHint: falseidempotentHint: trueopenWorldHint: false

{
  "id": "preset_1"
}

Tool-specific errors

prompt_preset_not_found / invalid_arguments / insufficient_scope / rate_limit_exceeded / not_found

create_prompt_preset

Save a reusable prompt template and its variable values for the connected user. Use render_prompt_preset later to fill saved or override values.

Required scope: prompts:presets:write
Credits: 0 credits.
History: Does not create prompt history; may link to existing generation ids.
Side effects: Creates a private preset.
Retry behavior: Not idempotent; retrying can create duplicates.

Inputs

name: 1-120 characters (required)
promptText: 1-20,000 characters (required)
values: up to 100 string values (required)
templateTitle/generationId/generatedVersionId: optional

Output

created preset with id, template, values, variables, links, and timestamps

Safety annotations

readOnlyHint: falsedestructiveHint: falseidempotentHint: falseopenWorldHint: false

{
  "name": "Launch post",
  "promptText": "Write a launch post for {{product}}.",
  "values": {
    "product": "PrompTessor"
  }
}

Tool-specific errors

invalid_arguments / insufficient_scope / rate_limit_exceeded

update_prompt_preset

Change the name or saved variable values of one owned prompt preset. This tool does not replace the template text.

Required scope: prompts:presets:write
Credits: 0 credits.
History: No history change.
Side effects: Updates an owned preset.
Retry behavior: Safe to retry with the same values.

Inputs

id: owned preset id (required)
name: optional 1-120 characters
values: optional map with up to 100 strings
At least name or values is required.

Output

updated preset

Safety annotations

readOnlyHint: falsedestructiveHint: falseidempotentHint: trueopenWorldHint: false

{
  "id": "preset_1",
  "values": {
    "product": "PrompTessor MCP"
  }
}

Tool-specific errors

prompt_preset_not_found / invalid_arguments / insufficient_scope

delete_prompt_preset

Permanently delete one reusable prompt preset owned by the connected user. Confirm the exact preset before calling.

Required scope: prompts:presets:write
Credits: 0 credits.
History: No prompt-history change.
Side effects: Irreversible preset deletion.
Retry behavior: A repeated call returns prompt_preset_not_found.

Inputs

id: owned preset id (required)

Output

id
deleted: true

Safety annotations

readOnlyHint: falsedestructiveHint: trueidempotentHint: trueopenWorldHint: false

{
  "id": "preset_1"
}

Tool-specific errors

prompt_preset_not_found / insufficient_scope

render_prompt_preset

Fill an owned preset with its saved values plus optional one-time overrides. Use this to obtain a completed prompt without changing the stored preset.

Required scope: prompts:presets:read
Credits: 0 credits.
History: No history change.
Side effects: Read-only; overrides are not saved.
Retry behavior: Safe to retry.

Inputs

id: owned preset id (required)
values: optional one-time string overrides

Output

preset identity and template
prompt: compiled output
resolved values, variables, unresolvedVariables

Safety annotations

readOnlyHint: truedestructiveHint: falseidempotentHint: trueopenWorldHint: false

{
  "id": "preset_1",
  "values": {
    "product": "PrompTessor MCP"
  }
}

Tool-specific errors

prompt_preset_not_found / invalid_arguments / insufficient_scope / rate_limit_exceeded / not_found

Prompt Library tools

Tool	Scope	Primary effect
list_prompt_library	library:read	Read-only.
get_prompt_library_item	library:read	Read-only.
create_private_library_item	library:write	Creates a private library item.
update_private_library_item	library:write	Updates an owned library item.
delete_private_library_item	library:write	Irreversible item deletion.
publish_library_item	library:publish	Makes prompt content publicly visible on PrompTessor.
unpublish_library_item	library:publish	Removes publicly visible content and changes it to private.
toggle_saved_library_item	library:interact	Adds or removes a private saved-item relationship.
toggle_library_vote	library:interact	Changes the user’s vote and the public vote count.

list_prompt_library

Browse private, Community, Official, saved, or upvoted Prompt Library collections. Use this to find an item id before reading or changing an item.

Required scope: library:read
Credits: 0 credits.
History: No history change.
Side effects: Read-only.
Retry behavior: Safe to retry.

Inputs

scope: my | community | official | saved | upvoted; default my
query: optional, maximum 200 characters
page: integer >=1; default 1

Output

items and categories
pagination
collection stats

Safety annotations

readOnlyHint: truedestructiveHint: falseidempotentHint: trueopenWorldHint: false

{
  "scope": "community",
  "query": "marketing",
  "page": 1
}

Tool-specific errors

invalid_arguments / insufficient_scope / rate_limit_exceeded / not_found

get_prompt_library_item

Read one Prompt Library item when it is owned by the user or publicly accessible. Use list_prompt_library when the id is unknown.

Required scope: library:read
Credits: 0 credits.
History: No history change.
Side effects: Read-only.
Retry behavior: Safe to retry.

Inputs

id: library item id (required)

Output

prompt content, instructions, category, models, visibility
public interaction and ownership flags
author display name and timestamps

Safety annotations

readOnlyHint: truedestructiveHint: falseidempotentHint: trueopenWorldHint: false

{
  "id": "lib_1"
}

Tool-specific errors

library_item_not_found / invalid_arguments / insufficient_scope / rate_limit_exceeded / not_found

create_private_library_item

Create a private Prompt Library item for the connected user. This never publishes automatically; call publish_library_item separately after explicit confirmation.

Required scope: library:write
Credits: 0 credits.
History: No workflow history change.
Side effects: Creates a private library item.
Retry behavior: Not idempotent; retrying can create duplicates.

Inputs

title: required, within library title limit
promptText: 1-20,000 characters (required)
recommendedModels: 1-8 supported models (required)
category: 1-120 characters (required)
description/guides/exampleText/tokenEstimate: optional
visibility is always private

Output

created private library item

Safety annotations

readOnlyHint: falsedestructiveHint: falseidempotentHint: falseopenWorldHint: false

{
  "title": "Launch campaign",
  "promptText": "Act as a campaign strategist...",
  "recommendedModels": [
    "ChatGPT"
  ],
  "category": "Marketing",
  "visibility": "private"
}

Tool-specific errors

invalid_arguments / insufficient_scope / rate_limit_exceeded

update_private_library_item

Update fields on one Prompt Library item owned by the connected user. This does not publish the item or change its visibility.

Required scope: library:write
Credits: 0 credits.
History: No workflow history change.
Side effects: Updates an owned library item.
Retry behavior: Safe to retry with the same field values.

Inputs

id: owned library item id (required)
Any editable private-item fields: title, promptText, description, guides, recommendedModels, category, exampleText, tokenEstimate

Output

updated library item

Safety annotations

readOnlyHint: falsedestructiveHint: falseidempotentHint: trueopenWorldHint: false

{
  "id": "lib_1",
  "title": "Updated launch campaign"
}

Tool-specific errors

library_item_not_found / invalid_arguments / insufficient_scope

delete_private_library_item

Permanently delete one Prompt Library item owned by the connected user. Confirm the exact item before calling.

Required scope: library:write
Credits: 0 credits.
History: No workflow history change.
Side effects: Irreversible item deletion.
Retry behavior: Idempotent at the desired state; a repeated call may return deleted: false.

Inputs

id: owned library item id (required)

Output

id
deleted: boolean

Safety annotations

readOnlyHint: falsedestructiveHint: trueidempotentHint: trueopenWorldHint: false

{
  "id": "lib_1"
}

Tool-specific errors

library_item_not_found / insufficient_scope

publish_library_item

Publish one owned private Prompt Library item to Community Prompts. Use only after the user explicitly chooses public sharing; paid plans and moderation rules apply.

Required scope: library:publish
Credits: 0 credits.
History: No workflow history change.
Side effects: Makes prompt content publicly visible on PrompTessor.
Retry behavior: Safe to retry when the item remains publishable.

Inputs

id: owned library item id (required)

Output

itemId, public visibility, published=true, updatedAt

Safety annotations

readOnlyHint: falsedestructiveHint: falseidempotentHint: trueopenWorldHint: true

{
  "id": "lib_1"
}

Tool-specific errors

library_item_not_found / public_platform_requires_paid_plan / publishing_blocked / insufficient_scope

unpublish_library_item

Remove one owned item from Community Prompts by making it private. Use only after the user explicitly identifies the public item to remove.

Required scope: library:publish
Credits: 0 credits.
History: No workflow history change.
Side effects: Removes publicly visible content and changes it to private.
Retry behavior: Safe to retry when the item still exists.

Inputs

id: owned public library item id (required)

Output

itemId, private visibility, published=false, updatedAt

Safety annotations

readOnlyHint: falsedestructiveHint: trueidempotentHint: trueopenWorldHint: true

{
  "id": "lib_1"
}

Tool-specific errors

library_item_not_found / insufficient_scope

toggle_saved_library_item

Toggle whether a public Community Prompt appears in the connected user’s saved collection. Use only when the user clearly asks to save or remove that item.

Required scope: library:interact
Credits: 0 credits.
History: No workflow history change.
Side effects: Adds or removes a private saved-item relationship.
Retry behavior: Not idempotent: repeating the same call reverses the previous action.

Inputs

id: public library item id not owned by the user (required)

Output

item: updated public item
action: saved | removed

Safety annotations

readOnlyHint: falsedestructiveHint: falseidempotentHint: falseopenWorldHint: false

{
  "id": "lib_2"
}

Tool-specific errors

library_item_not_found / invalid_library_action / insufficient_scope

toggle_library_vote

Toggle the connected user’s vote on a public Community Prompt. Use only when the user clearly asks to add or remove their vote.

Required scope: library:interact
Credits: 0 credits.
History: No workflow history change.
Side effects: Changes the user’s vote and the public vote count.
Retry behavior: Not idempotent: repeating the same call reverses the previous action.

Inputs

id: public library item id (required)

Output

item: updated public item
action: added | removed

Safety annotations

readOnlyHint: falsedestructiveHint: falseidempotentHint: falseopenWorldHint: false

{
  "id": "lib_2"
}

Tool-specific errors

library_item_not_found / invalid_library_action / insufficient_scope

Operation tools

Tool	Scope	Credits	Primary effect
get_operation	operations:read	0	Read-only.
cancel_operation	operations:cancel	0	Irreversibly cancels queued work and releases its reservation.

get_operation

Read the public status and result of one owned API or MCP operation. The result excludes credentials, request bodies, hashes, IP addresses, internal metadata, and account identifiers.

Required scope: operations:read
Credits: 0 credits.
History: No history change.
Side effects: Read-only.
Retry behavior: Safe to retry.

Inputs

id: owned operation id (required)

Output

id, object, kind, status
response, responseStatus, errorCode
history and usage
createdAt, startedAt, completedAt

Safety annotations

readOnlyHint: truedestructiveHint: falseidempotentHint: trueopenWorldHint: false

{
  "id": "op_123"
}

Tool-specific errors

operation_not_found / invalid_arguments / insufficient_scope / rate_limit_exceeded / not_found

cancel_operation

Cancel one owned asynchronous operation only while it is still pending. Use after explicit confirmation; running or completed operations cannot be cancelled.

Required scope: operations:cancel
Credits: 0 credits; a reserved credit is released.
History: A pending operation has not created product history.
Side effects: Irreversibly cancels queued work and releases its reservation.
Retry behavior: A repeated call fails because the operation is no longer pending.

Inputs

id: owned pending operation id (required)

Output

The same sanitized public operation view with status cancelled.

Safety annotations

readOnlyHint: falsedestructiveHint: trueidempotentHint: trueopenWorldHint: false

{
  "id": "op_pending"
}

Tool-specific errors

operation_not_found / operation_not_cancellable / insufficient_scope