Create embeddings with OpenAI
openai_create_embeddingsConvert texts into embedding vectors for semantic search, clustering, or deduplication. Saves vectors to a JSON file and returns its path; optionally returns vectors inline for batches up to 5 texts.
Instructions
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
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| model | No | Embedding model ID. Defaults to OPENAI_DEFAULT_EMBEDDING_MODEL. | |
| texts | Yes | The texts to embed, in order | |
| dimensions | No | Shorten the vectors to this many dimensions; supported by text-embedding-3 models | |
| output_path | No | Absolute path of the JSON file to write. Defaults to a timestamped file in OPENAI_MCP_OUTPUT_DIR. | |
| return_vectors | No | Return the raw vectors inline instead of only the file path. Allowed for at most 5 texts. | |
| response_format | No | Output format: 'markdown' or 'json' | markdown |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| count | Yes | ||
| model | Yes | ||
| usage | Yes | ||
| vectors | No | ||
| file_path | Yes | ||
| dimensions | Yes |