Writing Effective Instructions

This topic describes how to write the instructions field for the Context API actions that accept it. Instructions give the model additional context about your domain, your requirements, and the output format you want.

Prerequisites

A working Context API integration. For more information, see Enriching Content.
Familiarity with the actions that accept an instructions field, listed in Actions that support instructions.

Overview

The instructions field is an optional parameter on the actions listed in this topic. It passes additional context to the model along with the content being processed.

Actions that support instructions

The following actions accept an instructions field:

Action	Use case
`textSummarization`	Guide summarization style and focus areas
`textClassification`	Provide context for classification decisions
`textMetadataGeneration`	Guide metadata extraction strategy
`namedEntityRecognitionText`	Specify entity types and extraction focus
`imageDescription`	Control description format and detail level
`imageClassification`	Specify classification focus areas
`imageMetadataGeneration`	Control metadata identification approach
`namedEntityRecognitionImage`	Guide optical character recognition (OCR) and entity extraction approach

Best practices

Be specific and clear

Vague instructions lead to inconsistent results. Provide concrete details about what you want to achieve.

Less effective:

{
  "instructions": {
    "focus": "Extract important information"
  }
}

More specific:

{
  "instructions": {
    "focus": "Extract financial metrics including revenue, profit margins, and year-over-year growth percentages",
    "prioritize": "quarterly_comparisons|annual_totals"
  }
}

Provide context about your use case

Describe the domain and the purpose of the request.

The following example applies to insurance claims processing:

{
  "instructions": {
    "context": "Insurance vehicle damage assessment",
    "focus": "Identify visible damage to vehicle exterior including dents, scratches, and broken components",
    "emphasize": "damage_severity|affected_areas|repair_urgency"
  }
}

The following example applies to legal document review:

{
  "instructions": {
    "context": "Contract compliance review",
    "focus": "Extract key obligations, deadlines, and penalty clauses",
    "highlightRisks": true,
    "style": "structured"
  }
}

Specify output style and format

The following parameters control the form of the output:

Parameter	Description	Example values
`style`	Overall tone and format	`"professional"`, `"clinical"`, `"structured"`, `"concise"`
`format`	Output structure	`"bullet_points"`, `"paragraph"`, `"numbered_list"`
`detailLevel`	Amount of detail	`"high"`, `"medium"`, `"low"`

{
  "instructions": {
    "style": "professional",
    "format": "structured",
    "detailLevel": "high",
    "focus": "Key findings and recommendations"
  }
}

Use the `emphasize` parameter

Use pipe-separated values in the emphasize parameter to identify priority areas.

The following example applies to a medical report:

{
  "instructions": {
    "emphasize": "diagnosis|treatment_plan|follow_up_actions|critical_findings"
  }
}

The following example applies to a financial analysis:

{
  "instructions": {
    "emphasize": "revenue_trends|cost_analysis|profit_margins|risk_factors"
  }
}

Industry examples

The following examples show complete actions objects for three industries.

Healthcare

{
  "actions": {
    "textSummarization": {
      "maxWordCount": 200,
      "instructions": {
        "context": "Medical record analysis",
        "focus": "Patient diagnosis, prescribed treatments, and care instructions",
        "style": "clinical",
        "emphasize": "critical_findings|medication_changes|follow_up_appointments"
      }
    }
  }
}

Financial services

{
  "actions": {
    "textMetadataGeneration": {
      "kSimilarMetadata": [
        {
          "document:type": "Statement|Report|Disclosure|Filing",
          "fiscal:period": "Q1|Q2|Q3|Q4|Annual"
        }
      ],
      "instructions": {
        "context": "Financial regulatory compliance",
        "focus": "Identify reporting period, regulatory requirements, and compliance status",
        "detailLevel": "high"
      }
    }
  }
}

Manufacturing

{
  "actions": {
    "imageDescription": {
      "instructions": {
        "context": "Quality control inspection",
        "focus": "Identify product defects, dimensional variations, and surface imperfections",
        "emphasize": "defect_type|severity|location"
      }
    }
  }
}

Common patterns

The following combinations of parameters cover most requirements.

Combining focus, context, and style

This combination specifies what to extract, the domain it comes from, and how to present it.

{
  "instructions": {
    "focus": "Extract action items and deadlines",
    "context": "Project management meeting notes",
    "style": "structured"
  }
}

Combining emphasize with detail level

Use this combination to prioritize specific aspects at a set depth.

{
  "instructions": {
    "emphasize": "risks|mitigation_strategies|timeline_impacts",
    "detailLevel": "high"
  }
}

Providing domain-specific guidance

Use this combination for specialized content that requires domain expertise.

{
  "instructions": {
    "context": "Technical API documentation review",
    "focus": "Identify authentication methods, rate limits, and error handling patterns",
    "terminology": "technical",
    "emphasize": "breaking_changes|deprecations|security_requirements"
  }
}

Additional tips

Keep the following recommendations in mind when you write instructions:

Start simple. Begin with basic instructions and refine them based on the results.
Iterate. If the results do not meet your expectations, adjust the instructions incrementally.
Be consistent. Use consistent terminology across related requests.
Avoid contradictions. Verify that the instructions do not conflict with each other.
Match detail to task. Use a high detail level for complex analysis and a low detail level for quick categorization.
Test first. Validate your instructions against sample documents before you process large batches.

Troubleshooting

The following table lists common issues and their resolutions:

Issue	Possible cause	Resolution
Results are too generic	The instructions lack specificity	Add detail to the `focus` and `context` parameters
Expected information is missing	Emphasis is not set correctly	Use `emphasize` to prioritize specific elements
The tone or format is wrong	Style is not specified	Add the `style` and `format` parameters
Outputs are inconsistent	Instructions vary between requests	Standardize instruction templates for similar content

Next steps

Review the available actions. For the actions that accept an instructions field, with schemas and constraints, see Actions reference.
Review the full workflow. For the complete Context API workflow, see Enriching Content.
Use a code sample. For samples in Python, C#, and JavaScript, see Code Samples.

Prerequisites​

Overview​

Actions that support instructions​

Best practices​

Be specific and clear​

Provide context about your use case​

Specify output style and format​

Use the emphasize parameter​

Industry examples​

Healthcare​

Financial services​

Manufacturing​

Common patterns​

Combining focus, context, and style​

Combining emphasize with detail level​

Providing domain-specific guidance​

Additional tips​

Troubleshooting​

Next steps​