Generate text with an OpenAI model through the Responses API — OpenAI's current interface for single-turn and chained generation.

Use this as the default text tool. It supports plain prompting, system instructions, reasoning effort control, forced JSON output and multi-turn chaining via previous_response_id.

Args:

• input (string, required): the prompt

• model (string): model ID, defaults to OPENAI_DEFAULT_TEXT_MODEL

• instructions (string): system-level steering

• max_output_tokens (number): 1-200000

• temperature (number): 0-2

• top_p (number): 0-1

• reasoning_effort ('minimal'|'low'|'medium'|'high'): effort for reasoning models

• json_object (boolean): force a valid JSON object as output (default false)

• previous_response_id (string): continue an earlier stored response

• store (boolean): persist the response for later chaining (default false)

• response_format ('markdown'|'json'): default 'markdown'

Returns (JSON format): { "id": string, // response ID, usable as previous_response_id when store=true "model": string, // model that actually served the request "status": string | null, // e.g. "completed" or "incomplete" "output_text": string, // the generated text "usage": { "input_tokens": number|null, "output_tokens": number|null, "total_tokens": number|null } }

Examples:

• Use when: "Summarise this contract clause" -> input=, instructions="Answer in German, max 3 sentences"

• Use when: "Give me the result as JSON" -> json_object=true

• Use when: continuing a stored conversation -> previous_response_id="resp_..."

• Don't use when: you need to send an existing multi-message history verbatim (use openai_chat_completion)

Error Handling:

• "Error: Not found" means the model ID does not exist for this key — call openai_list_models

• "Error: Rate limit or quota exceeded" means retry later or lower the request rate

Send an explicit list of chat messages to an OpenAI model through the Chat Completions API.

Use this when you already hold a structured conversation history (system/user/assistant turns) and want it sent verbatim. For new single-prompt generations prefer openai_generate_text.

Args:

• messages (array, required): [{ role: 'system'|'user'|'assistant'|'developer', content: string }], 1-200 entries

• model (string): model ID, defaults to OPENAI_DEFAULT_TEXT_MODEL

• max_completion_tokens (number): 1-200000

• temperature (number): 0-2

• top_p (number): 0-1

• stop (string[]): up to 4 stop sequences

• response_format ('markdown'|'json'): default 'markdown'

Returns (JSON format): { "id": string, // completion ID "model": string, // model that served the request "finish_reason": string | null, // "stop", "length", "content_filter", ... "content": string, // assistant reply text "refusal": string | null, // set when the model declined "usage": { "input_tokens": number|null, "output_tokens": number|null, "total_tokens": number|null } }

Examples:

• Use when: replaying a saved conversation with a new final user turn

• Use when: you need a stop sequence to cut generation at a delimiter

• Don't use when: chaining stored responses (use openai_generate_text with previous_response_id)

Error Handling:

• "Error: OpenAI rejected the request as invalid" often means an unsupported parameter for that model, e.g. temperature on a reasoning-only model

List the model IDs the configured API key has access to, optionally filtered by substring.

Call this before guessing a model ID — OpenAI adds, renames and retires models regularly, and access differs per project. The response also reports the model IDs this server uses by default for each capability.

Args:

• filter (string): case-insensitive substring match on the model ID, e.g. "embedding"

• limit (number): 1-200 (default 50)

• offset (number): pagination offset (default 0)

• response_format ('markdown'|'json'): default 'markdown'

Returns (JSON format): { "total": number, // number of models matching the filter "count": number, // models in this response "offset": number, // current pagination offset "models": [ { "id": string, "owned_by": string, "created_at": string } // created_at is ISO 8601 UTC ], "has_more": boolean, "next_offset": number, // present only when has_more is true "defaults": { "text": string, "image": string, "embedding": string, "transcription": string, "speech": string, "moderation": string } }

Examples:

• Use when: "Which embedding models can I use?" -> filter="embedding"

• Use when: a generation failed with "model not found" -> call without filter and inspect the list

• Don't use when: you only need the server's configured defaults for a single call — those are applied automatically

Error Handling:

• "Error: Authentication failed" means OPENAI_API_KEY is invalid

• An empty list with a filter set means no model ID contains that substring

Create one or more images from a text prompt and write them to disk.

Images are never returned inline — the tool saves each file and reports its absolute path, so the agent's context stays small.

Args:

• prompt (string, required): what the image should show

• model (string): image model ID, defaults to OPENAI_DEFAULT_IMAGE_MODEL

• n (number): 1-4 images (default 1)

• size ('auto'|'1024x1024'|'1536x1024'|'1024x1536'|'512x512'|'256x256'): default 'auto'

• quality ('auto'|'low'|'medium'|'high'): default 'auto'

• background ('auto'|'transparent'|'opaque'): default 'auto'; 'transparent' needs png or webp

• output_format ('png'|'jpeg'|'webp'): default 'png'

• output_dir (string): absolute target directory, defaults to OPENAI_MCP_OUTPUT_DIR

• response_format ('markdown'|'json'): default 'markdown'

Returns (JSON format): { "model": string, "count": number, "images": [ { "index": number, "path": string, "bytes": number } ], "revised_prompt": string | null // prompt rewrite the model applied, when reported }

Examples:

• Use when: "Draw a logo of a blue fox" -> prompt="minimalist blue fox logo, flat vector"

• Use when: you need a transparent sticker -> background="transparent", output_format="png"

• Don't use when: you want to modify an existing picture (use openai_edit_image)

Error Handling:

• "Error: Access to ... is not permitted" means output_dir is outside OPENAI_MCP_ALLOWED_DIRS

• "Error: OpenAI rejected the request as invalid" often means size or quality is unsupported by that model

Edit or extend existing images according to a text instruction, optionally restricted to a masked region.

Source images are read from disk (only from directories listed in OPENAI_MCP_ALLOWED_DIRS) and results are written back to disk.

Args:

• prompt (string, required): the edit to apply

• image_paths (string[], required): 1-4 absolute paths to source images

• mask_path (string): absolute path to a PNG mask; transparent pixels mark the area to replace

• model (string): image model ID, defaults to OPENAI_DEFAULT_IMAGE_MODEL

• n (number): 1-4 variants (default 1)

• size ('auto'|'1024x1024'|'1536x1024'|'1024x1536'|'512x512'|'256x256'): default 'auto'

• output_dir (string): absolute target directory

• response_format ('markdown'|'json'): default 'markdown'

Returns (JSON format): { "model": string, "count": number, "images": [ { "index": number, "path": string, "bytes": number } ], "revised_prompt": string | null }

Examples:

• Use when: "Replace the sky in photo.png with a sunset" -> image_paths=["/data/photo.png"], prompt="sunset sky"

• Use when: combining several product shots into one scene -> image_paths=[...]

• Don't use when: creating an image from scratch (use openai_generate_image)

Error Handling:

• "Error: File not found" means the path does not exist

• "Error: Access to ... is not permitted" means the file lives outside OPENAI_MCP_ALLOWED_DIRS

Transcribe a local audio file to text.

The file is read from disk (only from directories listed in OPENAI_MCP_ALLOWED_DIRS) and uploaded to OpenAI. Supported containers include mp3, mp4, m4a, wav, webm, flac and ogg; the API limit is 25 MB per file.

Args:

• file_path (string, required): absolute path to the audio file

• model (string): transcription model ID, defaults to OPENAI_DEFAULT_TRANSCRIPTION_MODEL

• language (string): ISO-639-1 code such as "de" or "en"

• prompt (string): vocabulary hint for names and jargon

• response_format ('markdown'|'json'): default 'markdown'

Returns (JSON format): { "model": string, "text": string, // full transcript "language": string | null, // detected or supplied language "duration_seconds": number | null, // audio length when reported "source_file": string // canonical path that was read }

Examples:

• Use when: "What was said in this voice memo?" -> file_path="/data/memo.m4a"

• Use when: transcribing a German interview -> language="de"

• Don't use when: the file is a video you only want summarised — extract the audio track first

Error Handling:

• "Error: File not found" means the path does not exist

• "Error: Payload too large" means the file exceeds 25 MB — split it before retrying

Turn text into spoken audio and write the result to disk.

The audio is never returned inline — the tool reports the absolute path of the generated file.

Args:

• input (string, required): the text to speak, up to 10,000 characters

• voice (string): voice name, default "alloy"

• model (string): speech model ID, defaults to OPENAI_DEFAULT_SPEECH_MODEL

• instructions (string): delivery guidance such as "speak slowly and warmly"

• format ('mp3'|'opus'|'aac'|'flac'|'wav'|'pcm'): default 'mp3'

• speed (number): 0.25-4.0, default 1

• output_path (string): absolute target file, defaults to a timestamped file in OPENAI_MCP_OUTPUT_DIR

• response_format ('markdown'|'json'): default 'markdown'

Returns (JSON format): { "model": string, "voice": string, "path": string, // absolute path of the written audio file "bytes": number, // file size "format": string // container that was written }

Examples:

• Use when: "Read this paragraph aloud as an mp3" -> input=

• Use when: you need a slower narration -> speed=0.85

• Don't use when: you want a transcript of existing audio (use openai_transcribe_audio)

Error Handling:

• "Error: Access to ... is not permitted" means output_path is outside OPENAI_MCP_ALLOWED_DIRS

• "Error: OpenAI rejected the request as invalid" often means the voice name is unknown to that model

Turn texts into embedding vectors for semantic search, clustering or deduplication.

By default the vectors are written to a JSON file and only the path plus metadata are returned, because a single vector holds up to 3072 floats. Set return_vectors=true for small batches when the numbers are needed directly.

Args:

• texts (string[], required): 1-2048 texts to embed

• model (string): embedding model ID, defaults to OPENAI_DEFAULT_EMBEDDING_MODEL

• dimensions (number): shorten vectors (text-embedding-3 models only)

• return_vectors (boolean): inline the vectors, max 5 texts (default false)

• output_path (string): absolute path of the JSON file to write

• response_format ('markdown'|'json'): default 'markdown'

Returns (JSON format): { "model": string, "count": number, // number of vectors produced "dimensions": number, // length of each vector "file_path": string | null, // where the vectors were written "usage": { "input_tokens": number|null, "total_tokens": number|null }, "vectors": number[][] // present only when return_vectors is true }

The written JSON file has the shape: { "model": "text-embedding-3-small", "created_at": "2026-08-23T14:05:00.000Z", "count": 2, "dimensions": 1536, "items": [ { "index": 0, "text_preview": "…", "embedding": [0.0123, -0.0456] } ] }

Examples:

• Use when: building a semantic index over documents -> texts=[...], then read the JSON file

• Use when: comparing two sentences directly -> texts=[a, b], return_vectors=true

• Don't use when: you just want a summary or classification (use openai_generate_text)

Error Handling:

• "Error: return_vectors is only allowed for up to 5 texts" — lower the batch or read the file

• "Error: OpenAI rejected the request as invalid" often means the model does not support the dimensions parameter

Check text against OpenAI's moderation policy and report which categories it triggers.

Use this before publishing or forwarding user-supplied text, or to explain why a generation was refused.

Args:

• input (string, required): the text to check

• model (string): moderation model ID, defaults to OPENAI_DEFAULT_MODERATION_MODEL

• response_format ('markdown'|'json'): default 'markdown'

Returns (JSON format): { "model": string, "flagged": boolean, // true when any category was triggered "flagged_categories": string[], // e.g. ["violence", "harassment/threatening"] "scores": { "": number } // confidence per category, 0.0-1.0 }

Examples:

• Use when: "Is this user comment acceptable?" -> input=

• Use when: auditing a batch of support messages before archiving them

• Don't use when: you need a stylistic or factual review (use openai_generate_text)

Error Handling:

• "Error: Not found" means the moderation model ID is wrong — call openai_list_models with filter="moderation"