Optimize: Metadata, Skills, and Events

Lesson rewritten on November 3, 2026 based on the OpenAI Plugins documentation pages Optimize Metadata, Build Skills, MCP Events, and Plugin Extensions. The previous version of this lesson relied on analytics and experiment modules from a non-existent SDK. Sources: Optimize Metadata · Build Skills · MCP Events · Plugin Extensions.

Metadata is product copy

ChatGPT and Codex decide when to call your tools based on the metadata you provide. Well-written names, descriptions, and parameters ensure your tool is invoked when needed and prevent unwanted triggers. OpenAI recommends treating this metadata as product copy: iterate on it, test it, and measure its performance.

A reference prompt set

Before touching your metadata, build a labeled set of test prompts:

• Direct prompts that name your product or data source explicitly.
• Indirect prompts that describe the desired outcome without naming your tool.
• Negative prompts that should be handled by built-in tools or other plugins.

For each prompt, document the expected behavior: call your tool, do nothing, or defer to another solution. Use this set for every non-regression test.

Metadata that guides the model

• The name should combine the domain and the action, such as calendar.create_event.
• The description should start with “Use when…” and explicitly list excluded cases, such as “Do not use for reminders.”
• Each parameter must be documented with examples and a list of allowed values if the input is constrained.
• Annotations must reflect actual behavior (see Lessons 3 and 11).

Measure, then iterate

Connect your server, install the plugin, run your prompt set, and record which tool was selected, what arguments were passed, and whether any UI component was displayed. Track two metrics: precision (was the correct tool called?) and recall (was the tool called every time it should have been?). Aim for high precision on negative prompts first before chasing marginal gains in recall.

Change only one field at a time to isolate what drives improvement. Keep a dated revision log with results, and have someone else review changes before deployment. In production, review tool usage weekly. A spike in “wrong tool” confirmations usually signals metadata drift. Gather user feedback and re-run your prompt tests regularly, especially after adding a new tool or modifying a structured field.

Skills for recurring workflows

Your server provides data, authentication, and controlled actions. A skill provides the sequence of tool calls, decision points, output formatting, examples, and templates. The fastest way to get started is with the built-in @skill-creator, where you describe the user’s goal and the MCP tools that support it.

A strong SKILL.md file specifies which steps to follow, what result the user should receive, what facts the model must not invent, when to ask questions, stop, or refuse, and which files to consult. Prefer a focused skill for a specific workflow over a large set of disparate instructions. Split workflows that differ in their trigger, inputs, or success criteria. Keep SKILL.md concise and store details elsewhere: use references/ for policies, schemas, and examples; assets/ for templates to copy or transform; and scripts/ for deterministic calculations—but only if existing instructions and tools are insufficient.

If a skill depends on an MCP server, declare that dependency in agents/openai.yaml. This makes the tool available but does not replace the need for clear instructions on which tools to use, in what order, and how to handle missing or ambiguous results. For GPT-6 Astra, OpenAI advises reviewing its guidance on instruction following: eliminate vague or contradictory directives, and make it explicit that user instructions take priority over skill instructions.

Test skill activation and output quality using direct, indirect, incomplete (which should trigger a clarifying question), off-topic, and edge-case prompts where the skill must avoid hallucinating or acting outside its scope. If a skill activates at the wrong time, fix its description. If it selects the right workflow but produces inconsistent results, fix its instructions.

MCP Events: Reacting to changes

MCP Events lets ChatGPT subscribe to updates from your server, such as new messages, modified content, or status changes. The user chooses what to monitor and how ChatGPT should react when an update arrives—for example, “Monitor this document and apply the corrections requested in the comments.”

1. Your server lists the events it supports.
2. The user tells ChatGPT what to monitor and how to react.
3. ChatGPT subscribes via your MCP server, providing a callback URL and a signing secret.
4. Your server sends relevant events to that URL.
5. ChatGPT receives the event in the subscribed conversation and follows the user’s instructions.

This feature is available in ChatGPT Work conversations on the web and in the desktop app with Cloud selected. ChatGPT relies on webhook delivery as defined in the MCP Events specification draft. Your server must persist subscriptions and be able to reach callback URLs over HTTPS.

ChatGPT interface extensions

OpenAI MCP Extensions allow a plugin to integrate into key areas of the ChatGPT interface: the sidebar, the input area, and file viewers. Mentions in the input area are available only in the desktop app. OpenAI publishes a sample plugin, Bits & Bolts, which demonstrates these extensions and tracks their deployment. It is the best starting point for exploring this capability.

Key takeaways

• Treat metadata as product copy: use a reference prompt set, track precision and recall, and change one field at a time.
• Write descriptions starting with “Use when…”, list excluded cases explicitly, and document all parameters.
• Create one focused skill per workflow, keep SKILL.md concise, store resources separately, and declare MCP dependencies.
• MCP Events subscribes ChatGPT to your server updates, delivered via webhook.
• Extensions integrate your plugin into the sidebar, input area, and file viewers.

Test your knowledge

From MCP tools to publication: verify that you have mastered the fundamentals.

1. Do I need an `@openai/apps-sdk` package to create an app in ChatGPT?

Answer: No, that package does not exist. You build an MCP server using the official protocol SDKs (@modelcontextprotocol/sdk for TypeScript, mcp for Python), optionally add an interface compliant with the MCP Apps standard, and distribute the whole thing as a plugin.

2. Can a tool exist without a UI?

Answer: Yes, and it should: a tool returns structuredContent and a short text summary, which is sufficient for the model. The UI, attached via _meta.ui.resourceUri, is added only when it helps users inspect, compare, edit, confirm, or navigate information.

3. Who decides whether a user has permission to access data?

Answer: The MCP server decides on every request, based on the verified OAuth token (signature, issuer, audience, expiration, scopes). Annotations help ChatGPT choose the appropriate confirmation level, but they never replace server-side authorization.

4. Can a plugin sell a subscription to its service?

Answer: No. Rules restrict commerce to physical goods. An existing subscriber can log in and use the features included in their plan. The plugin may explain that a feature is not included and link to an information page, but it must never link to a payment page.

5. How do tools update for a published plugin?

Answer: Without a new ZIP file: OpenAI re-scans the server, and any new or modified tool becomes available after passing automated checks. A deleted tool disappears immediately. However, metadata and skills require a new ZIP file and a new review.

Well-described tools, optional UIs, server-side authorization, and adherence to rules: this is the framework that makes a plugin a reliable service in ChatGPT and Codex.