Expected Format for Plugin Descriptions in OpenAI Plugins: Requirements and Examples

The expected format for plugin descriptions in the OpenAI Plugins repository is a plain-text string limited to approximately 120 characters, written as a single sentence without Markdown, HTML, or special formatting.

Each plugin in the openai/plugins repository defines its functionality through a description field stored in the manifest file. Understanding the expected format for plugin descriptions ensures your submission meets the OpenAI Plugin Marketplace requirements and displays correctly to users. The specification mandates specific formatting rules that all contributed plugins must follow, as demonstrated by existing implementations in the codebase.

Where Plugin Descriptions Are Defined

In the openai/plugins repository, plugin descriptions reside in the manifest file located at .codex-plugin/plugin.json (or occasionally .app.json). The manifest contains two critical fields: description_for_human and description_for_model, both of which follow identical formatting constraints according to the repository standards.

Format Requirements for Plugin Descriptions

The source code analysis reveals three strict requirements for the description field across all plugin manifests.

Plain Text Only (No Markdown or HTML)

The description must be a plain-text string without any formatting syntax. Do not include Markdown italics (*text*), bold (**text**), HTML tags (<br>), or line breaks. The OpenAI Plugin Marketplace UI renders these descriptions as raw text, so special characters or formatting directives will display literally rather than render as styled content.

Character Limit and Length Constraints

While the JSON schema allows longer strings, the OpenAI Plugin Marketplace enforces a soft limit of approximately 120 characters. Descriptions exceeding this threshold risk truncation in the UI or rejection during the review process. Keep descriptions concise and focused on the plugin's primary capability.

Single Sentence Structure

Write the description as a single, complete sentence that summarizes the plugin's purpose. Avoid bullet points, multiple clauses separated by semicolons, or paragraph breaks. The sentence should clearly state what the plugin enables users to do.

Real-World Examples from the Repository

The following examples from openai/plugins demonstrate the correct format in production manifests.

The Zotero plugin (plugins/zotero/.codex-plugin/plugin.json) uses a descriptive but concise sentence:

"description": "Work with Zotero from Codex: search your library, export BibTeX, insert citations, and import references through the Zotero desktop app."

The ZoomInfo plugin (plugins/zoominfo/.codex-plugin/plugin.json) provides a brief, action-oriented summary:

"description": "Prospecting and account research with ZoomInfo"

The Wix plugin (plugins/wix/.codex-plugin/plugin.json) demonstrates how to handle complex functionality within the constraints:

"description": "Build and deploy Wix apps and headless websites, and manage your Wix business. Includes CLI development skills, Wix Headless for any frontend framework, and Wix MCP server for eCommerce, CMS, dashboard extensions, and more."

Minimal Manifest Template

When creating a new plugin, structure your manifest file following this pattern:

{
  "name_for_human": "My Awesome Plugin",
  "name_for_model": "my_awesome_plugin",
  "description_for_human": "A concise description of what the plugin does in plain text.",
  "description_for_model": "A concise description of what the plugin does in plain text."
}

Summary

• Store plugin descriptions in .codex-plugin/plugin.json under the description_for_human and description_for_model fields.
• Use plain text only without Markdown, HTML, or formatting syntax.
• Limit descriptions to approximately 120 characters to ensure full visibility in the Marketplace UI.
• Write a single sentence that clearly states the plugin's primary function.
• Reference existing plugins like Zotero, ZoomInfo, and Wix as templates for proper formatting.

Frequently Asked Questions

Can I use Markdown formatting in plugin descriptions?

No. The OpenAI Plugins repository requires descriptions to be plain-text strings only. Markdown syntax, HTML tags, and special formatting characters will not render correctly in the Marketplace UI and may cause display issues.

What is the maximum length for a plugin description?

While the JSON format technically supports longer strings, the OpenAI Plugin Marketplace UI enforces a practical limit of approximately 120 characters. Descriptions longer than this risk truncation or rejection during the submission review process.

Should description_for_human and description_for_model be identical?

Yes, according to the patterns found in the repository, both fields should contain the same plain-text description. The description_for_human displays to end users, while description_for_model helps the AI understand the plugin's capabilities, but both follow the same formatting constraints.

Where is the plugin description stored in the repository?

Plugin descriptions are stored in the manifest file located at plugins/{plugin-name}/.codex-plugin/plugin.json. Some older plugins may use .app.json, but new contributions should follow the .codex-plugin/plugin.json structure as seen in Zotero, ZoomInfo, and Wix.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}