Instruction Refinement

Use Instruction Refinement to review system instructions, prompts, and skills before you ship them to a model. The service checks them against a catalog of prompt engineering guidelines compiled from model vendors’ documentation, then returns a score, prioritized problems located in your text, the guidelines behind each problem, and suggested fixes.

It fits prompt reviews in pull requests, audits of AI gateway instructions and skills, and editors that highlight problems as you write. It reports guideline issues; it does not run your prompt or measure how a model performs with it. To test behavior against real conversations, use Agentic Tests.

Before calling this endpoint, create an API key and make sure the account has a positive balance.

Endpoint #

Choose a view #

The review runs in one of two views. Each request runs one view and is billed separately, so run both when you want a complete review.

• micro (default) reviews the wording inside each item: clarity, measurable constraints, structure, examples, emphasis, tool guidance, output format, and similar guidelines. Use it while writing or editing a single prompt.
• macro reviews how the items work together as one agent. It checks that the agent has a clear purpose and limits of authority, that each behavior lives in a single item responsible for it, that skills can be selected from their descriptions without overlapping or being forced, that the context matches the tools the agent really has, and that it avoids over-specification such as scripted conversations or rules the platform already provides. Use it when you review a whole agent or its skill set.

The macro view needs the related items to judge relationships. Send the base instructions together with the skills, tool descriptions, and knowledge the agent uses; a single item gives it little to compare.

Request behavior #

Send in one request the items that the same agent receives. A guideline can be satisfied by another item, and findings can point out items that conflict with or duplicate each other; reviewing items in separate requests misses those relationships. In the micro view, knowledge and documentation items are used only as context.

An unknown view or type, an empty content, or an empty context array returns 400 Bad Request.

{
  "view": "macro",
  "purpose": "Answer billing questions and hand refunds to the finance team.",
  "context": [
    {
      "type": "instruction",
      "title": "support-agent.md",
      "content": "You are a support agent.\nNever promise refunds."
    },
    {
      "type": "skill",
      "title": "refunds",
      "description": "Refunds.",
      "content": "Promise a refund when the customer asks for one."
    }
  ]
}

Read the response #

data contains the review of all items:

Each finding has these properties:

evidenceSpan gives the location of the problem in that item’s content as fromLine, toLine, fromColumn, and toColumn, all 1-based and inclusive. It is null when the problem is an omission, when it lies in a skill’s description, or when the cited text could not be located. Columns count characters from the start of the line, so line breaks inside content must match the text you display when you highlight a span.

Each source has an id that identifies the guideline in its catalog, a number within its type, a type, and references with the vendor documentation URLs behind it. type reflects the guideline’s weight: a rule prevents predictable failures, a practice reliably improves results, a tip is optional and situational, and a dont is an anti-pattern to avoid. Some macro guidelines cover agent design rather than vendor guidance and have an empty references array.

Each suggested fix has a refFinding array with the finding ids it resolves, a description of exactly what to change and in which item, and a type:

title, description, summary, and fix descriptions are written in the language used by most of the analyzed content.

{
  "message": null,
  "data": {
    "overallScore": 0.35,
    "summary": "The instructions and the refunds skill contradict each other about refunds, and the skill description is too vague to be selected reliably.",
    "findings": [
      {
        "id": 1,
        "priority": "P0",
        "title": "Contradictory refund authority",
        "description": "The instructions forbid promising refunds while the skill requires it, so the agent may promise refunds it cannot grant.",
        "locations": [
          {
            "contextIndex": 0,
            "evidenceSpan": { "fromLine": 2, "toLine": 2, "fromColumn": 1, "toColumn": 22 }
          },
          {
            "contextIndex": 1,
            "evidenceSpan": { "fromLine": 1, "toLine": 1, "fromColumn": 1, "toColumn": 48 }
          }
        ],
        "sources": [
          {
            "id": "B.D. 3",
            "number": 3,
            "type": "dont",
            "references": [
              "https://cookbook.openai.com/examples/gpt-5/gpt-5_prompting_guide"
            ]
          }
        ]
      }
    ],
    "suggestedFixes": [
      {
        "refFinding": [ 1 ],
        "type": "modify",
        "description": "In the refunds skill, replace the promise with: \"Explain that the finance team reviews refunds and transfer the request to them.\""
      }
    ]
  }
}

Reviews are model-generated. The score and findings can vary between requests for the same content, and a finding can be wrong or miss context that only you have. A suggested removal can still drop a business rule the review didn’t recognize as critical, so check removals against your requirements, apply fixes deliberately, and confirm that the changed agent still behaves as expected.

Pricing and limits #

Instruction Refinement is billed in processing units (PUs), covering input and output usage. Usage is recorded once per request. The PU price varies with the processing model that serves the request, and the plan multiplier applies. Longer context items consume more input.

Instruction Refinement shares the document limits of Extraction and Summarization. Each item in the request’s context array counts as one document, not each HTTP request. The number of processed documents per minute and per day depends on the plan; see Data processing limits. A request that would exceed any active window returns 429 Too Many Requests.

The embedded API reference contains the server-maintained request, response, authentication, and error details: