Gemini 2.5 Pro

Preferred instruction format

Gemini uses a dedicated systemInstruction field in the API request, separate from user messages. System instructions are processed BEFORE user prompts and persist across the entire conversation. They can be a single string or an array of strings. In Python SDK: system_instruction=['Role description', 'Behavioral rules']. In REST: systemInstruction.parts[].text. This is NOT embedded in the user message — it is a first-class API parameter. (source: Vertex AI docs, System Instructions, https://docs.cloud.google.com/vertex-ai/generative-ai/docs/learn/prompts/system-instructions)

Recommended practices

• Use XML-style tags (<context>, <task>) or Markdown headings as consistent delimiters to structure prompt sections — choose one format and use it consistently within a single prompt (source: Google AI docs, Prompt Design Strategies, https://ai.google.dev/gemini-api/docs/prompting-strategies)
• Place critical instructions and constraints at the BEGINNING of the prompt, and for long contexts, put the specific question/task at the END after all context data (source: Vertex AI docs, Gemini 3 Prompting Guide, https://docs.cloud.google.com/vertex-ai/generative-ai/docs/start/gemini-3-prompting-guide)
• Always include 3-5 few-shot examples with consistent formatting — Google explicitly recommends 'always include few-shot examples in your prompts' but warns too many cause overfitting (source: Google AI docs, Prompt Design Strategies, https://ai.google.dev/gemini-api/docs/prompting-strategies)
• For structured output, set response_mime_type='application/json' with response_schema — do NOT duplicate the schema description in the prompt text; use the schema's 'description' fields instead to guide the model (source: Vertex AI docs, Structured Output, https://docs.cloud.google.com/vertex-ai/generative-ai/docs/multimodal/control-generated-output)
• Use propertyOrdering in JSON schemas to enforce field generation order, and ensure any in-prompt schema references use the SAME property order as the schema definition (source: Vertex AI docs, Structured Output, https://docs.cloud.google.com/vertex-ai/generative-ai/docs/multimodal/control-generated-output)
• Use objective constraints instead of subjective qualifiers — e.g. 'write a summary of 3 sentences or less' rather than 'write a brief summary' (source: Google AI docs, Prompt Design Strategies, https://ai.google.dev/gemini-api/docs/prompting-strategies)
• For grounding to provided context only, explicitly state 'the provided context is the only source of truth for the current session' in system instructions (source: Vertex AI docs, Gemini 3 Prompting Guide, https://docs.cloud.google.com/vertex-ai/generative-ai/docs/start/gemini-3-prompting-guide)
• Add current date context and knowledge cutoff statement for time-sensitive queries (source: Google AI docs, Prompt Design Strategies, https://ai.google.dev/gemini-api/docs/prompting-strategies)
• Keep temperature at default 1.0 — lowering it may cause 'looping or degraded performance, particularly with complex mathematical or reasoning tasks' (source: Vertex AI docs, Gemini 3 Prompting Guide, https://docs.cloud.google.com/vertex-ai/generative-ai/docs/start/gemini-3-prompting-guide)

Anti-patterns to avoid

• DO NOT lower temperature below 1.0 for reasoning tasks — Gemini's reasoning is optimized for temp=1.0 and lower values cause looping and degraded performance (source: Vertex AI docs, Gemini 3 Prompting Guide, https://docs.cloud.google.com/vertex-ai/generative-ai/docs/start/gemini-3-prompting-guide)
• DO NOT duplicate JSON schema in prompt text when using response_schema — include the schema only in the response_schema parameter to avoid confusion; use schema description fields for guidance (source: Vertex AI docs, Structured Output, https://docs.cloud.google.com/vertex-ai/generative-ai/docs/multimodal/control-generated-output)
• DO NOT use too many few-shot examples — overfitting occurs; stick to 3-5 varied examples (source: Google AI docs, Prompt Design Strategies, https://ai.google.dev/gemini-api/docs/prompting-strategies)
• DO NOT place essential instructions at the end of very long prompts — model may drop them during complex processing (source: Vertex AI docs, Gemini 3 Prompting Guide, https://docs.cloud.google.com/vertex-ai/generative-ai/docs/start/gemini-3-prompting-guide)
• DO NOT use vague or subjective language ('brief', 'detailed', 'good') without measurable definitions (source: Google AI docs, Prompt Design Strategies, https://ai.google.dev/gemini-api/docs/prompting-strategies)
• DO NOT combine structured output (response_mime_type) with function calling on Gemini 2.5 — they are incompatible and will fail (source: GitHub issue googleapis/python-genai#867)
• DO NOT use inconsistent formatting across few-shot examples — responses will mirror the inconsistency (source: Google AI docs, Prompt Design Strategies, https://ai.google.dev/gemini-api/docs/prompting-strategies)