Manage OpenAI vector stores, files, file batches, and perform semantic search through the OpenAI Vector Store API.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@@dotlab-hq/vector-store-mcp search my vector store for 'machine learning basics'"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MCP (Model Context Protocol) server for the OpenAI Vector Store API. Manage vector stores, files, file batches, and perform semantic search — all through a single MCP server.
Supports two transports:
stdio — for local use with Claude Desktop, VS Code Copilot, or any MCP-compatible client
HTTP (Streamable) — for deployment as a web service
21 tools covering the full OpenAI Vector Store API
Fully typed with TypeScript + Zod schema validation
Uses the official OpenAI Node SDK
Two entry points: local stdio and HTTP server
Zero-config for local development
Related MCP server: Universal OpenAI Vector Store MCP Server
# Clone and install
git clone <repo-url>
cd vector-store-mcp
npm install
# Build
npm run buildVariable | Required | Description |
| Yes | Your OpenAI API key |
| No | Custom OpenAI API base URL (for proxies/compatible APIs) |
| No | HTTP server port (default: |
| No | HTTP server host (default: |
# Run directly
npm start
# Or with dev watch mode
npm run dev# Start the HTTP server
npm run start:http
# Or with dev watch mode
npm run dev:httpThe HTTP server exposes:
GET /health — Health check
POST /mcp — MCP Streamable HTTP endpoint
CORS enabled for all origins in development
Add to your claude_desktop_config.json:
{
"mcpServers": {
"vector-store": {
"command": "npx",
"args": ["-y", "@dotlab-hq/vector-store-mcp"],
"env": {
"OPENAI_API_KEY": "your-api-key-here"
}
}
}
}Add to .vscode/mcp.json in your workspace root:
{
"servers": {
"vector-store": {
"command": "npx",
"args": ["-y", "@dotlab-hq/vector-store-mcp"],
"env": {
"OPENAI_API_KEY": "your-api-key-here"
}
}
}
}Windows users:
npxmay fail with'vector-store-mcp' is not recognizeddue to a known Windows shim resolution issue. To fix this, link the package globally once:npm link @dotlab-hq/vector-store-mcpThen use the direct command in
.vscode/mcp.json:{ "servers": { "vector-store": { "command": "vector-store-mcp", "args": [], "env": { "OPENAI_API_KEY": "your-api-key-here" } } } }
With HTTP-based MCP, the server holds the credentials — the client only needs the URL. The API key and base URL are passed as environment variables when starting the server, not in the client config.
1. Start the server with your credentials:
# Pass env vars directly
OPENAI_API_KEY=sk-... npm run start:http
# Or use a .env file / shell profile to set them
export OPENAI_API_KEY=sk-...
export OPENAI_API_BASE=https://your-proxy.example.com/v1 # optional
npm run start:http
# Server running at http://127.0.0.1:3000/mcp2. Connect from your MCP client — just the URL, no keys needed:
VS Code .vscode/mcp.json:
{
"servers": {
"vector-store": {
"url": "http://127.0.0.1:3000/mcp",
"type": "http"
}
}
}Any MCP-compatible HTTP client:
POST http://127.0.0.1:3000/mcp
Content-Type: application/jsonHow it works: The server process reads
OPENAI_API_KEYfrom its own environment and uses it for all OpenAI API calls. The MCP client never sees or transmits the key — it just sends tool requests to the server URL. This means you can run the server anywhere (local, cloud, Docker) and point multiple clients at it.
You can also use this as a library:
import {
McpServer,
registerAllTools,
getClient,
resetClient,
} from "@dotlab-hq/vector-store-mcp";
const server = new McpServer({ name: "my-server", version: "1.0.0" });
registerAllTools(server);Tool | Description |
| Create a new vector store |
| Retrieve a vector store by ID |
| Update a vector store's name or metadata |
| Delete a vector store |
| List all vector stores with pagination and filtering |
| Search a vector store with a query string and optional filters |
Tool | Description |
| List files with filtering by purpose, status, and pagination |
| Retrieve file metadata by ID |
| Delete a file by ID |
| Download the content of a file by ID |
Tool | Description |
| Attach a file to a vector store with optional attributes |
| List files in a vector store with filtering and pagination |
| Retrieve a specific file in a vector store |
| Remove a file from a vector store |
| Download file content from a vector store |
| Update attributes on a vector store file |
Tool | Description |
| Create a batch of files for a vector store |
| Retrieve batch status and details |
| Cancel an in-progress batch |
| List files in a specific batch |
Tool | Description |
| Upload a file to OpenAI (for use with vector stores) |
Script | Description |
| Run stdio transport (local) |
| Run HTTP transport (deployment) |
| Dev mode with watch (stdio) |
| Dev mode with watch (HTTP) |
| Compile TypeScript |
| Remove dist/ |
MIT
Attach a previously uploaded file to a vector store.
The file must already exist in your OpenAI project (use openai_upload_file to upload first). Once attached, the file will be chunked and indexed for semantic search.
For multi-file ingestion, prefer openai_create_vector_store_file_batch to minimize per-vector-store write requests.
| Name | Required | Description | Default |
|---|---|---|---|
| vector_store_id | Yes | The ID of the vector store to attach the file to. | |
| file_id | Yes | The ID of the previously uploaded file. | |
| attributes | No | Up to 16 key-value pairs for filtering and search. | |
| chunking_strategy | No | Chunking strategy for the file. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are minimal but not contradicted. The description adds useful behavioral context: the file will be chunked and indexed for semantic search, and notes that using the batch tool minimizes write requests, implying this tool incurs write requests. This goes beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise at three sentences, front-loading the action, then providing prerequisites and alternatives. Every sentence is necessary and no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with moderate complexity (4 params, nested object) and no output schema, the description covers the core action, prerequisites, and alternative usage. It explains the outcome (chunking and indexing) but could mention what is returned or how to verify attachment. Overall, it is mostly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed descriptions for all parameters. The description does not add additional semantic meaning beyond the schema, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action of attaching a file to a vector store, specifies the prerequisite (file must be uploaded first), and distinguishes from the sibling tool openai_create_vector_store_file_batch for multi-file ingestion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells when to use this tool (single file attachment) and when to prefer the batch alternative for multi-file ingestion. Also provides guidance to use openai_upload_file first if the file hasn't been uploaded.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Cancel processing of a file batch as soon as possible.
Use this to stop ingestion of files that are still being processed. Already-processed files will remain attached.
| Name | Required | Description | Default |
|---|---|---|---|
| vector_store_id | Yes | The ID of the vector store. | |
| batch_id | Yes | The ID of the file batch to cancel. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description reveals that cancellation is not destructive to already-processed files, aligning with annotations (destructiveHint=false). It adds behavioral context beyond the read/write hints, though no mention of idempotency or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no unnecessary words. It is front-loaded with the action and quickly conveys the key information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple cancel operation with no output schema, the description provides essential context about the effect on processed vs. unprocessed files. It could mention potential error states or prerequisites (e.g., batch must be in processing), but overall it is complete enough for an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already describes both parameters (vector_store_id and batch_id) with 100% coverage. The description adds no additional semantic meaning beyond what the schema provides, so baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies the action 'Cancel processing' and the resource 'file batch', distinguishing it from sibling tools like creating a batch or attaching files. It provides the purpose: to stop ingestion of files still being processed.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states when to use this tool ('to stop ingestion of files that are still being processed') and notes the outcome for already-processed files. It does not explicitly mention when not to use or provide alternatives, but the context is clear for a cancel operation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new OpenAI vector store — a collection of processed files that can be used with the file_search tool.
Use this when you need a new vector store to hold uploaded documents for semantic search or retrieval-augmented generation (RAG).
You can optionally provide file_ids to attach already-uploaded files, a chunking strategy, and metadata (up to 16 key-value pairs).
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | The name of the vector store. | |
| file_ids | No | A list of File IDs that the vector store should use. Useful for tools like `file_search`. | |
| expires_after | No | The expiration policy for the vector store. | |
| metadata | No | Set of 16 key-value pairs attached to the object. Keys max 64 chars, values max 512 chars. | |
| chunking_strategy | No | Chunking strategy for files. Default is auto (800 tokens, 400 overlap). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=true. The description adds that it creates a collection for file_search and lists optional parameters, which is consistent and adds minor behavioral context beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: three short sentences. The first defines the tool, the second gives direct usage guidance, the third lists key optional parameters. No wasted words or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (5 parameters, nested objects, no output schema), the description is adequately complete. It explains the resource's purpose, usage context, and key optional features. It could mention that creation returns a vector store object, but since the output schema is missing, the description suffices.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers all 5 parameters with descriptions (100% coverage). The description adds value by summarizing optional parameters and noting the metadata limit of 16 key-value pairs, which aligns with the schema. This enhances understanding without redundancy.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a new OpenAI vector store' with specific verb and resource, and defines it as a collection for file_search. It distinguishes from siblings (e.g., delete, update) by its creation purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Use this when you need a new vector store,' providing clear context for usage. It does not explicitly list when not to use or alternatives, but the context is sufficient given sibling tool names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a batch of files to attach to a vector store.
This is the recommended way to attach multiple files at once — it minimizes per-vector-store write requests and is more efficient than attaching files one by one.
| Name | Required | Description | Default |
|---|---|---|---|
| vector_store_id | Yes | The ID of the vector store. | |
| file_ids | Yes | A list of File IDs to attach. | |
| attributes | No | Up to 16 key-value pairs for filtering and search. | |
| chunking_strategy | No | Chunking strategy for the files. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide limited hints (openWorldHint true) and the description states it creates a batch, implying a write operation. However, it does not disclose that the batch processing may be asynchronous or what the immediate result is. The description is adequate but lacks deeper behavioral context such as post-creation status checks.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, consisting of two sentences. The first sentence clearly states the purpose, and the second provides usage guidance. It is front-loaded with the essential information, with no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (4 parameters, nested objects) and the thorough schema coverage, the description is fairly complete. It covers purpose and usage context but lacks information about return values and the asynchronous nature of batch processing. An output schema would enhance completeness, but it is not expected per instructions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers all parameters with detailed descriptions (100% coverage). The description does not add additional meaning beyond the schema, but the baseline is 3 due to high schema coverage. The description's mention of 'batch' and 'efficient' does not directly aid parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a batch of files to attach to a vector store. It distinguishes from the sibling tool openai_attach_file_to_vector_store by explicitly recommending this approach for multiple files and highlighting efficiency.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly recommends using this tool when attaching multiple files at once, citing efficiency and reduced write requests. It implies that attaching single files might be better handled by the sibling tool, but does not explicitly state when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Permanently delete a file and remove it from all vector stores.
This action cannot be undone. The file will be deleted from OpenAI's storage.
| Name | Required | Description | Default |
|---|---|---|---|
| file_id | Yes | The ID of the file to delete. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide destructiveHint and idempotentHint. The description adds that the deletion is permanent and cannot be undone, and removes from all vector stores, which goes beyond annotations. However, it does not address auth requirements or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, concise and front-loaded with the key purpose. Every sentence adds value, with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with one parameter, full annotations, and no output schema, the description covers the critical effect (permanent deletion from storage and vector stores). It could mention idempotent behavior (file already deleted), but annotations hint that.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single parameter, and the schema already describes file_id. The tool description does not add additional parameter semantics beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'permanently delete a file and remove it from all vector stores'. It uses a specific verb ('delete') and resource ('file'), and distinguishes from siblings like openai_delete_vector_store_file by noting removal from all vector stores.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for permanent deletion (cannot be undone) and mentions removal from all vector stores, but does not explicitly state when to use this vs. alternatives like openai_delete_vector_store_file. No when-not or alternative guidance provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Permanently delete an OpenAI vector store by its ID.
This will remove the vector store and all its associated files. This action cannot be undone.
| Name | Required | Description | Default |
|---|---|---|---|
| vector_store_id | Yes | The ID of the vector store to delete. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds context beyond annotations: highlights permanence, irreversibility, and scope (all associated files). No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, front-loaded with the primary action, no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter destructive tool with no output schema, the description fully covers the effect, side effects, and irreversibility.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema coverage, the description adds no extra meaning to the parameter beyond its schema definition. Adequate baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (delete) and resource (vector store by ID), distinguishing it from sibling tools like create or retrieve.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description indicates permanence and side effects (removes associated files), but does not explicitly mention when not to use or alternatives among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove a file from a vector store (does NOT delete the underlying OpenAI file).
After removal, the file will no longer be searchable in this vector store. To delete the file entirely, use openai_delete_file.
| Name | Required | Description | Default |
|---|---|---|---|
| vector_store_id | Yes | The ID of the vector store. | |
| file_id | Yes | The ID of the vector store file to delete. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavioral context beyond annotations by stating that the file will no longer be searchable in the vector store and that the underlying file is not deleted. Annotations already indicate destructiveHint true, and the description aligns and elaborates.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the key differentiator (does not delete underlying file). Every sentence provides essential information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool, the description fully explains the primary effect, the constraint (file remains), and guides to an alternative. With complete schema and annotations, this is sufficient for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description does not add additional meaning to the parameters beyond what is already in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: remove a file from a vector store. It explicitly distinguishes this from deleting the underlying file, using the sibling openai_delete_file as a contrast.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says when to use this tool (to remove a file from a vector store without deleting the file) and points to the alternative openai_delete_file for full deletion. However, it does not provide explicit when-not scenarios or prerequisites beyond the required parameters.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all files in your OpenAI project with pagination and optional purpose filter.
Returns metadata about each uploaded file including its ID, filename, size, purpose, and creation timestamp. Use the 'purpose' parameter to filter by type (e.g., "assistants", "fine-tune", "batch").
| Name | Required | Description | Default |
|---|---|---|---|
| after | No | Cursor for pagination. | |
| limit | No | Maximum number of files to return (1–10000, default 10000). | |
| order | No | Sort order by created_at timestamp. | desc |
| purpose | No | Only return files with the given purpose. | |
| response_format | No | Output format: 'markdown' for human-readable or 'json' for machine-readable. | markdown |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds useful behavioral context: it returns metadata (ID, filename, size, purpose, creation timestamp) and supports pagination and filtering. This goes beyond annotations without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences: first states the core purpose with key features (pagination, purpose filter), second enriches with return details and filter example. No wasted words, front-loaded, and structured for quick comprehension.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's 5 parameters, no output schema, and strong annotations, the description adequately covers the listing operation, return metadata, and filtering. It is missing explicit mention of pagination mechanics (cursor usage) but the schema covers that. Overall sufficient for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds meaning to the purpose parameter with examples ('assistants', 'fine-tune', 'batch') and mentions pagination in the first sentence, but does not significantly extend beyond the schema's already clear parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The title 'List Files' and description 'List all files in your OpenAI project with pagination and optional purpose filter' clearly state the verb (list), resource (files), scope (project), and key features. This effectively distinguishes it from sibling tools like retrieve_file or upload_file.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains what the tool does but does not provide guidance on when to use it versus alternatives (e.g., retrieve_file for a single file, or vector store file lists for scoped listings). No exclusions or context for selection are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all files in a specific file batch with pagination and optional status filter.
Use this to inspect which files in a batch have been processed, are still in progress, or have failed.
| Name | Required | Description | Default |
|---|---|---|---|
| vector_store_id | Yes | The ID of the vector store. | |
| batch_id | Yes | The ID of the file batch. | |
| after | No | Cursor for pagination. | |
| before | No | Cursor for pagination. | |
| filter | No | Filter by file status. | |
| limit | No | Maximum number of files to return (1–100, default 20). | |
| order | No | Sort order by created_at timestamp. | desc |
| response_format | No | Output format: 'markdown' for human-readable or 'json' for machine-readable. | markdown |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, destructiveHint, idempotentHint, and openWorldHint, covering the safety and idempotency profile. The description adds no additional behavioral context beyond restating the purpose, which is adequate given the annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the main action, and contains no unnecessary words. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (8 parameters, no output schema) and rich annotations, the description is sufficient to understand the tool's purpose and when to use it. It could mention the response structure but is not required for completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with all 8 parameters having descriptions. The description does not add extra meaning; it only mentions pagination and status filter at a high level. Baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists all files in a specific file batch with pagination and status filter. It uses specific verbs and resources, and distinguishes from sibling tools like openai_list_vector_store_files and openai_retrieve_vector_store_file_batch.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use this tool: to inspect the status of files in a batch. It does not provide explicit alternatives or exclusions, but the context is clear enough for an AI agent to differentiate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all files attached to a vector store with pagination and optional status filter.
Shows each file's processing status (in_progress, completed, failed, cancelled) so you can monitor ingestion progress.
| Name | Required | Description | Default |
|---|---|---|---|
| vector_store_id | Yes | The ID of the vector store. | |
| after | No | Cursor for pagination. | |
| before | No | Cursor for pagination. | |
| filter | No | Filter by file status. | |
| limit | No | Maximum number of files to return (1–100, default 20). | |
| order | No | Sort order by created_at timestamp. | desc |
| response_format | No | Output format: 'markdown' for human-readable or 'json' for machine-readable. | markdown |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true, so the safety profile is clear. The description adds value by specifying that the tool shows each file's processing status, which goes beyond the annotations. No contradictions. The pagination behavior is implied but not detailed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is composed of two concise sentences with no redundant information. The first sentence states the primary function and features; the second adds context on monitoring. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given a relatively simple listing operation with 7 parameters and no output schema, the description adequately covers pagination and status filtering. However, it does not explain return format, how pagination cursors work, or sorting details. The schema fills some gaps, but for a complete picture, more context could be provided.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters. The description adds minimal semantic value by mentioning 'optional status filter' and 'pagination', which maps to the 'filter' and pagination params. However, it does not elaborate on cursor usage or other param details beyond what the schema provides. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('list all files attached to a vector store') and specifies key features ('pagination and optional status filter'). It distinguishes from siblings like retrieve_vector_store_file (single file) and list_vector_store_file_batch_files (files in a batch). The verb 'list' and resource 'vector store files' are unambiguous, and the use case of monitoring ingestion progress is highlighted.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description indicates when to use the tool: to list files and monitor ingestion progress. While it does not explicitly state when not to use it or list alternatives, the context of 'monitor ingestion progress' provides clear guidance. The sibling tool list suggests that for specific file retrieval, use retrieve_vector_store_file.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all OpenAI vector stores with pagination support.
Returns a paginated list of vector stores in your project. Use 'after' or 'before' cursors to navigate pages.
| Name | Required | Description | Default |
|---|---|---|---|
| after | No | Cursor for pagination. Pass the ID of the last object. | |
| before | No | Cursor for pagination. Pass the ID of the first object. | |
| limit | No | Maximum number of vector stores to return (1–100, default 20). | |
| order | No | Sort order by created_at timestamp. | desc |
| response_format | No | Output format: 'markdown' for human-readable or 'json' for machine-readable. | markdown |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a safe, idempotent read operation. The description adds behavioral context about paginated returns and cursor navigation, which is useful beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences that front-load purpose and pagination guidance. No redundant or irrelevant content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, the description covers the primary behavior (pagination) and return type. However, it does not explicitly mention that the response includes vector store details like ID and name, though the schema covers parameters. Still complete enough for typical use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema documents all parameters fully. The description merely references 'after' and 'before' cursors without adding meaning beyond the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'list' and the resource 'OpenAI vector stores', and mentions pagination support. It effectively distinguishes from sibling tools that create, delete, or retrieve individual stores.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description advises using cursors for pagination but does not explicitly differentiate from 'openai_search_vector_store' or 'openai_retrieve_vector_store'. It lacks when-not-to-use guidance or alternative recommendations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve metadata about a specific file by its ID, including filename, size, purpose, and status.
| Name | Required | Description | Default |
|---|---|---|---|
| file_id | Yes | The ID of the file to retrieve. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. Description adds specific metadata fields returned (filename, size, purpose, status), providing context beyond annotations. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single, clear sentence that efficiently conveys the tool's action, resource, and output. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, single parameter, and strong annotations, the description is complete. It explains the return value (metadata fields) which is critical since no output schema is provided.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the file_id parameter is fully described. The description's 'by its ID' aligns with schema but adds no new semantic meaning beyond what's already in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Retrieve', resource 'a specific file by its ID', and the output 'metadata including filename, size, purpose, and status'. It distinguishes from siblings like delete_file and retrieve_file_content.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you have a file ID, but does not explicitly state when to use this tool vs alternatives like openai_retrieve_file_content or openai_list_files. No when-not or alternative guidance provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve the raw content of a file by its ID.
Returns the file content as-is (text, JSON, JSONL, etc. depending on the file type). For large files, consider using the file's metadata first to check its size.
| Name | Required | Description | Default |
|---|---|---|---|
| file_id | Yes | The ID of the file whose content to retrieve. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only and idempotent behavior. The description adds that content is returned as-is (text/JSON/etc.) and warns about large file sizes, providing useful behavioral context beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no wasted words. The purpose is stated first, followed by a useful caveat. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple retrieval tool with one parameter, the description adequately covers the action, return format, and a practical consideration (file size). No missing critical information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'file_id' is fully described in the schema (100% coverage). The description adds no additional meaning or constraints beyond what the schema provides, so baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Retrieve the raw content') and the resource ('a file by its ID'), differentiating it from siblings like 'openai_retrieve_file' which likely returns metadata. The return type is specified as raw content as-is.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides a practical caveat: for large files, check metadata first. This guides the agent on when to use this tool versus inspecting file size. However, it does not explicitly list alternatives or exclusions beyond that hint.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve details of a specific OpenAI vector store by its ID.
Use this to check the status, file counts, metadata, and other properties of an existing vector store.
| Name | Required | Description | Default |
|---|---|---|---|
| vector_store_id | Yes | The ID of the vector store to retrieve. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, non-destructive, idempotent traits. Description adds that it retrieves details but no additional behavioral context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences: first states purpose, second provides usage context. No redundancy or wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple retrieval with good annotations and one parameter, the description covers the essential purpose and usage. It could mention return type but is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the parameter 'vector_store_id' is well-described in the schema. The description does not add semantic meaning beyond stating retrieval by ID.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'retrieve' and the resource 'vector store', and specifies it is by ID, distinguishing it from listing and other retrieve tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description advises using this to check status, file counts, metadata, and properties, providing clear context. It does not explicitly exclude alternatives, but the single filter by ID is implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve details of a specific file attached to a vector store, including its processing status and any errors.
| Name | Required | Description | Default |
|---|---|---|---|
| vector_store_id | Yes | The ID of the vector store. | |
| file_id | Yes | The ID of the vector store file to retrieve. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and nondestructive. The description adds value by specifying what data is returned (processing status and errors), which is not covered by annotations. It does not discuss rate limits or auth, but the core behavior is well disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, 17 words, front-loaded with action and key output. No extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description adequately explains the return content (details including status and errors). Simple retrieval operation with two required parameters; combined with annotations, it is fully sufficient for an agent to understand usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with clear parameter descriptions. The tool description does not add additional semantic detail beyond the schema, so baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (Retrieve), the resource (details of a specific file attached to a vector store), and specifies included details (processing status and errors). This distinguishes it from siblings like list or delete operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly indicates when to use (when needing details of a specific file) but does not explicitly state when not to use or compare to alternatives like listing all files. Context from sibling names helps but is not directly in the description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve the status and details of a file batch, including file counts by status.
| Name | Required | Description | Default |
|---|---|---|---|
| vector_store_id | Yes | The ID of the vector store. | |
| batch_id | Yes | The ID of the file batch to retrieve. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only, non-destructive, idempotent. The description adds context about what specific details are retrieved (e.g., file counts by status), which enhances transparency without contradicting annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-formed sentence that conveys the core functionality without any wasted words. It is front-loaded with the action and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple retrieval tool with good annotations and two required parameters, the description adequately covers the purpose and return details (status and file counts). Missing an output schema, but the description partially compensates by mentioning what is returned.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage for parameters is 100%, so the schema already defines 'vector_store_id' and 'batch_id' fully. The description does not add any additional meaning or usage hints for the parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('retrieve'), the resource ('file batch'), and what is returned ('status and details, including file counts by status'). It effectively distinguishes from sibling tools like 'list' or 'cancel'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention prerequisites, context, or when not to use it. Usage is implied but not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve the parsed text content of a vector store file.
Returns the chunks of text that were extracted from the file and indexed in the vector store. Useful for inspecting what content is available for search.
| Name | Required | Description | Default |
|---|---|---|---|
| vector_store_id | Yes | The ID of the vector store. | |
| file_id | Yes | The ID of the vector store file whose content to retrieve. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds behavioral context by specifying the output format (chunks of text) and that the content is indexed, which augments the annotations without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description consists of three concise sentences, each adding distinct value: action, return type, and use case. It is front-loaded and wastes no words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple retrieval tool with two parameters and no output schema, the description is complete: it explains what the tool does, what it returns, and when to use it. It sufficiently covers the context needed for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage with clear explanations for both parameters. The tool description does not add additional semantics beyond what the schema provides, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Retrieve the parsed text content of a vector store file') and explains the return value ('chunks of text that were extracted from the file and indexed'). It distinguishes from siblings like openai_retrieve_vector_store_file (metadata) and openai_search_vector_store (search) by emphasizing content inspection.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states the utility: 'Useful for inspecting what content is available for search.' While it does not list when not to use or alternatives, the context of sibling tools and the clear purpose provide sufficient guidance for an agent to select appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search an OpenAI vector store for relevant chunks based on a query and optional file-attribute filters.
Use this to perform semantic search across the documents in a vector store. You can provide a single query string or an array of queries, and optionally filter by file attributes (e.g., department = "engineering").
Results include ranked search hits with content snippets, file IDs, and relevance scores.
| Name | Required | Description | Default |
|---|---|---|---|
| vector_store_id | Yes | The ID of the vector store to search. | |
| query | Yes | A query string or array of query strings for search. | |
| max_num_results | No | Maximum number of results to return (1–50, default 10). | |
| rewrite_query | No | Whether to rewrite the query for better search results. | |
| filters | No | Filter to apply based on file attributes. | |
| response_format | No | Output format: 'markdown' for human-readable or 'json' for machine-readable. | markdown |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds that results include 'ranked search hits with content snippets, file IDs, and relevance scores,' which provides useful behavioral context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences, front-loaded with purpose, follows with usage and result description. Every sentence adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description details return values (snippets, file IDs, scores). Covers query types, filters, and usage context completely for a search tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with good descriptions. The description adds usage examples (e.g., 'department = "engineering"') and explains result format, but does not significantly deepen understanding of individual parameters beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Search an OpenAI vector store for relevant chunks based on a query and optional file-attribute filters,' specifying verb and resource. Among siblings, only this tool performs search, so it is well-differentiated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description says 'Use this to perform semantic search' but does not explicitly mention when not to use it. However, since it is the only search tool among siblings, context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Modify an existing OpenAI vector store — rename it, update metadata, or change the expiration policy.
Use this when you need to update properties of an existing vector store without recreating it.
| Name | Required | Description | Default |
|---|---|---|---|
| vector_store_id | Yes | The ID of the vector store to modify. | |
| name | No | The new name of the vector store. | |
| expires_after | No | New expiration policy for the vector store. | |
| metadata | No | Updated set of 16 key-value pairs attached to the object. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate idempotent and non-destructive. Description adds that it modifies properties but doesn't elaborate on specific behaviors. No contradiction; provides sufficient context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: first describes action, second provides usage guidance. No fluff, front-loaded. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and annotations indicating openWorldHint, description adequately covers the mutation. Could mention return type or that omitted fields remain unchanged.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers all parameters with descriptions (100% coverage). Description does not add extra meaning beyond what schema provides. Baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'modify an existing OpenAI vector store' and lists specific properties (rename, metadata, expiration policy). This effectively distinguishes it from sibling tools like create_vector_store or delete_vector_store.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use this when you need to update properties of an existing vector store without recreating it.' This clarifies when to use compared to create. Could be improved by mentioning when not to use (e.g., for adding files).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update or clear the attributes (up to 16 key-value pairs) on a vector store file.
Attributes can be used to filter and organize files within a vector store. Pass null to clear all attributes.
| Name | Required | Description | Default |
|---|---|---|---|
| vector_store_id | Yes | The ID of the vector store. | |
| file_id | Yes | The ID of the vector store file to update. | |
| attributes | Yes | Updated set of up to 16 key-value pairs, or null to clear attributes. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds context beyond annotations: constraint on number of key-value pairs, clearing behavior with null. No contradiction with annotations (readOnlyHint=false, idempotentHint=true, etc.).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with action, no fluff. Each sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Explanation covers action, constraints, intended use case, and clearing behavior. No output schema, but not essential for this mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but description adds meaning by specifying limit (up to 16) and clearing via null, which is not explicit in schema's description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Specifies clear verb ('Update or clear') and resource ('attributes on a vector store file'). Includes constraint ('up to 16 key-value pairs') and distinguishes from sibling tools like delete, attach, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Describes purpose ('filter and organize files') and how to clear attributes ('Pass null'), but does not explicitly state alternative tools or when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Upload a local file to OpenAI.
The file is uploaded using multipart/form-data. Once uploaded, you can attach the returned file ID to a vector store using openai_attach_file_to_vector_store.
Supported purposes:
assistants: Used in the Assistants API
batch: Used in the Batch API
fine-tune: Used for fine-tuning
vision: Images for vision fine-tuning
user_data: Flexible file type for any purpose
evals: Used for eval data sets
Individual files can be up to 512 MB.
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | Absolute or relative path to the local file to upload. | |
| purpose | Yes | The intended purpose of the uploaded file. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide basic hints (readOnlyHint=false, etc.), but the description adds behavioral context: multipart/form-data upload, 512 MB size limit, and the six supported purposes. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured with bullet points for purposes. Every sentence adds information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description mentions 'returned file ID' but does not describe the full response format or return object. Given no output schema, more detail on the response would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema already has 100% coverage with descriptions and enums. The description adds value by elaborating on each purpose (e.g., 'assistants: Used in the Assistants API') and clarifying that file_path is a local path.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Upload a local file to OpenAI' with a specific verb and resource. It lists supported purposes and size limits, distinguishing it from sibling tools like 'openai_attach_file_to_vector_store' which attaches the returned file ID.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains that after upload, the file ID can be attached to a vector store using a specific sibling tool. It does not explicitly state when not to use, but the context of purposes and the sibling list imply appropriate use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Every tool has a clearly distinct purpose: vector store CRUD, file upload/attach/delete, batch operations, search, and attribute updates. No two tools overlap in functionality.
All tools follow the pattern 'openai_verb_noun' with consistent snake_case (e.g., openai_create_vector_store, openai_delete_vector_store_file). No mixing of styles.
21 tools cover the full lifecycle of vector store and file management without being excessive. Each tool serves a specific, necessary operation.
The server provides complete CRUD for vector stores and files, batch operations, search, and attribute management. No obvious gaps like missing detach functionality, as openai_delete_vector_store_file handles removal.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Remote ChromaDB vector database MCP server with streamable HTTP transport
MCP server that lets AI assistants use all OneSchema features exposed via the public API.
An MCP server that provides an API to LLMs to manage their JumpCloud resources.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/dotlab-hq/vector-store-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
