# Best Practices for Designing Plugin Descriptions in OpenAI Plugins

> Learn best practices for designing plugin descriptions. Write concise summaries, punchy short descriptions, and detailed long descriptions for your OpenAI plugins.

- Repository: [OpenAI/plugins](https://github.com/openai/plugins)
- Tags: best-practices
- Published: 2026-06-14

---

**The best practices for designing plugin descriptions include writing concise top-level summaries (50–70 characters), punchy short descriptions (≤120 characters), detailed long descriptions with markdown formatting, and including 3–5 searchable keywords along with starter prompts in your [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) file.**

Designing plugin descriptions for the OpenAI plugins repository requires strict adherence to the schema defined in the Plugin JSON specification. The repository enforces specific character limits and formatting rules that directly impact how your plugin appears in the Marketplace and how easily users can discover it. According to the openai/plugins source code, the metadata fields documented in [`.agents/skills/plugin-creator/references/plugin-json-spec.md`](https://github.com/openai/plugins/blob/main/.agents/skills/plugin-creator/references/plugin-json-spec.md) determine both UX consistency and search visibility.

## Core Description Fields in [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json)

The OpenAI plugins repository defines description semantics across multiple fields in the [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) manifest. Each field serves a distinct purpose in the user interface and search indexing.

### Top-Level Description

The **`description`** field at the top level of [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) serves as the primary search result snippet. According to the specification in [`.agents/skills/plugin-creator/references/plugin-json-spec.md`](https://github.com/openai/plugins/blob/main/.agents/skills/plugin-creator/references/plugin-json-spec.md) (lines 52-55), this field should contain a "Short purpose summary" of approximately 50–70 characters. This brief, user-focused sentence appears in quick search results and serves as the first impression of your plugin's functionality.

### Interface Short Description

The **`shortDescription`** field inside the `interface` object provides a subtitle-style blurb displayed on plugin cards. Keep this under 120 characters and avoid jargon to ensure readability across different user contexts. This field bridges the gap between the top-level description and the detailed explanation.

### Interface Long Description

Use **`longDescription`** within the `interface` object to expand on capabilities with up to a few paragraphs. The specification recommends using proper markdown formatting for readability, allowing you to explain core use cases, unique value propositions, and implementation details that help users understand when to install your plugin.

### Default Prompts

The **`defaultPrompt`** field suggests up to three starter prompts, each limited to 128 characters. These prompts help users immediately understand practical applications. The Zoom plugin demonstrates this pattern effectively in [`plugins/zoom/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/zoom/.codex-plugin/plugin.json) (lines 44-46), providing examples like "Search my recent Zoom meetings for the discussion about pricing."

## Metadata and Discoverability Optimization

Beyond descriptive text, specific metadata fields determine how the Marketplace indexes and displays your plugin.

### Keywords and Searchability

Include 3–5 relevant terms in the **`keywords`** array at the top level of [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json). These tags should reflect your domain (e.g., `zoom`, `meeting`, `transcripts`) because the Marketplace search engine indexes these terms to improve discoverability. Accurate keyword selection ensures your plugin appears in relevant category searches.

### Branding Assets and Path Conventions

Visual consistency requires specific asset configurations. The **`brandColor`**, **`composerIcon`**, **`logo`**, and **`screenshots`** fields must reference files stored under `./assets/`. According to the specification (lines 88-89), screenshots must be PNG files. All relative paths must start with `./` and remain inside the plugin root directory (lines 91-95). This ensures portable installations across different environments.

## Compliance and Trust Signals

The schema requires **`privacyPolicyURL`** and **`termsOfServiceURL`** fields to signal legal compliance. Including these URLs demonstrates respect for user data obligations and builds trust with potential adopters. While not strictly "description" fields, their presence in the metadata affects user confidence and Marketplace approval.

## Implementation Examples

The following minimal example demonstrates properly configured description fields:

```json
{
  "name": "my-awesome-plugin",
  "version": "0.1.0",
  "description": "Summarize documents and generate quick insights",
  "author": {
    "name": "Acme Corp",
    "url": "https://github.com/acme"
  },
  "keywords": ["summarization", "insights", "documents"],
  "skills": "./skills/",
  "interface": {
    "displayName": "My Awesome Plugin",
    "shortDescription": "Fast document summarization with AI",
    "longDescription": "Leverages OpenAI models to read PDFs, Word docs, and plain‑text files, then returns concise bullet‑point summaries and key take‑aways. Ideal for research, reporting, and quick reviews.",
    "defaultPrompt": [
      "Summarize the attached PDF in 5 bullet points.",
      "Give me the main take‑aways from this meeting transcript."
    ],
    "brandColor": "#4F46E5",
    "composerIcon": "./assets/icon.svg",
    "logo": "./assets/logo.png",
    "screenshots": [
      "./assets/screenshot-1.png",
      "./assets/screenshot-2.png"
    ]
  }
}

```

The Zoom plugin provides a concrete reference implementation in [`plugins/zoom/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/zoom/.codex-plugin/plugin.json):

```json
{
  "description": "Connect Codex to Zoom meeting context and build Zoom apps, bots, API integrations, SDK workflows, webhooks, and automations.",
  "interface": {
    "shortDescription": "Use Zoom meeting context and build Zoom integrations.",
    "longDescription": "Zoom connects Codex to Zoom meeting context through the Zoom app connector and provides developer workflows for planning, building, debugging, and reviewing Zoom integrations across APIs, SDKs, webhooks, WebSockets, bots, and automation use cases.",
    "defaultPrompt": [
      "Search my recent Zoom meetings for the discussion about pricing.",
      "Run /plan-zoom-product for a Zoom integration idea."
    ]
  }
}

```

## Summary

- Write a **concise top-level description** (50–70 characters) that summarizes purpose for search results.
- Craft a **punchy short description** (≤120 characters) for plugin card displays.
- Provide a **detailed long description** with markdown formatting to explain use cases.
- Add **3–5 searchable keywords** to improve Marketplace discoverability.
- Include **up to three starter prompts** (≤128 characters each) to demonstrate functionality.
- Store **branding assets** in `./assets/` using relative paths starting with `./`.
- Provide **privacy and terms URLs** to establish trust and meet compliance requirements.

## Frequently Asked Questions

### What is the maximum length for a plugin description in OpenAI's schema?

The top-level `description` field should be approximately 50–70 characters, serving as a brief purpose summary. The `shortDescription` field under `interface` has a recommended limit of 120 characters, while the `longDescription` field supports multiple paragraphs for detailed explanation.

### Where should I store screenshots and icons for my plugin?

Store all visual assets in the `./assets/` directory within your plugin root. Reference these files using relative paths starting with `./` as specified in [`.agents/skills/plugin-creator/references/plugin-json-spec.md`](https://github.com/openai/plugins/blob/main/.agents/skills/plugin-creator/references/plugin-json-spec.md) (lines 91-95). Screenshots must be PNG files, and all paths must remain inside the plugin root directory.

### How do default prompts improve plugin adoption?

The `defaultPrompt` field provides up to three starter examples (≤128 characters each) that demonstrate immediate practical use. These prompts appear in the user interface and help potential adopters understand concrete applications without reading documentation, significantly reducing the barrier to first-time use.

### What fields are required for Marketplace compliance?

In addition to description fields, you must include `privacyPolicyURL` and `termsOfServiceURL` in your [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json). These fields signal legal compliance and data handling transparency. The specification also requires proper keyword tagging and adherence to character limits for all description fields.