Prompts Topics APIBetter labels start with better instructions.

State the decision in plain language

Start with the unit of content and the intended decision. For example: assign the central subject of an article from this vocabulary, and include a secondary subject only when it receives substantial coverage. That is more useful than asking for every topic that seems relevant.

Define what should happen when the document lacks enough context. The instruction should permit an unknown or review outcome. Forcing a choice may make every response appear complete while concealing uncertainty that matters to the editor.

Teach the boundaries with examples

Include a clear positive example, a clear negative example, and a borderline example for categories that are easily confused. Explain the reason for each assignment. A short, relevant contrast can reveal more about the intended task than a long list of unrelated demonstrations.

Keep examples separate from the evaluation set. If you repeatedly tune the prompt against the same documents, improved results may reflect familiarity with those examples. Reserve new documents for checking whether the rule transfers to unfamiliar writing.

Specify a compact output contract

Tell the system which fields to return and which values are permitted. IDs are usually safer integration keys than free-form display names. Put reasons or excerpts in separate fields so they cannot accidentally become new categories.

Avoid requesting elaborate reasoning when a short evidence excerpt serves the workflow. Give reviewers the information needed to inspect the assignment while keeping the record concise. The contract should fit the application’s decision, not the amount of text a model can produce.

Change one decision at a time

Version prompts and keep a short note of the behavior each revision is meant to improve. If you alter definitions, examples, output shape, and model configuration together, it becomes difficult to tell which change produced the result.

Review the new prompt on the same held-out set and inspect category-specific errors. A wording change that helps one topic may hurt another. Keep a rollback path and avoid assuming that a more detailed prompt is automatically a more reliable prompt.

An illustrative record

This example highlights fields worth discussing when you design your own contract. Define their meanings, allowed values, and review rules before an application relies on them.

{
  "task": "assign_central_subject",
  "prompt_version": "example-v1",
  "allowed_topic_ids": [
    "ai.models",
    "ai.evaluation"
  ],
  "max_topics": 2,
  "unknown_policy": "send_to_review"
}

Illustrative schema and example values; adapt them to your data and review process.

Questions about Prompts Topics API