AI guidance

AI guidance allows you to provide context and instructions that help Scout and other AI features understand the purpose and requirements of your components, parameters, fields, and content types.

By adding AI guidance to your Uniform definitions, you give AI tools better context about what content should be created, resulting in more accurate and relevant AI-generated suggestions.

Where AI guidance is used#

AI guidance is applied when content is created or edited using Uniform's AI capabilities:

• Scout when editing compositions or entries
• AI quick edits for rapid content updates
• MCP server when editing content programmatically

Three levels of AI guidance#

AI guidance can be applied at three different levels, each serving a specific purpose in your content creation workflow.

Project-level guidance#

Project-level AI guidance in Uniform project settings

Location: Settings > AI Guidance

Purpose: Define overarching editorial conventions and brand voice that apply across your entire project.

Character limit: 3000 characters maximum

What to include:

• Company-wide writing style and tone
• Brand voice guidelines
• Terminology preferences and standards
• Inclusive language requirements
• Industry-specific conventions

Example:

"Write in a conversational yet professional tone. Use active voice and present tense. Avoid jargon unless writing for technical audiences. Follow AP style for punctuation and capitalization. Use inclusive language that respects all identities."

Component and content type level#

Component description field in component editor

Location: Description field of components and content types

Purpose: Define what the component or content type is for and when it should be used.

What to include:

• The purpose of the component or content type
• Common use cases
• When to use it versus other components
• Contextual information about its role

Example for a Hero component:

"A large, attention-grabbing section typically used at the top of landing pages to communicate the primary value proposition. Features a headline, supporting text, an optional image, and call-to-action."

Example for an Article content type:

"Long-form editorial content for the blog and knowledge base. Articles provide in-depth information, how-to guides, and thought leadership content for our audience."

Parameter and field level#

AI guidance field in parameter editor

Location: AI guidance field on individual parameters and fields

Purpose: Provide specific instructions for individual content fields to guide AI in generating appropriate values.

What to include:

• Expected content type and format
• Length recommendations
• Writing style specific to this field
• Specific constraints or requirements

Note: Block and Image URL parameter types do not support AI guidance.

Example for a headline parameter:

"A compelling headline of 6-10 words that captures attention and communicates the main value proposition"

Example for a meta description field:

"Meta description optimized for search engines, 150-160 characters, clearly communicating the page's value and benefits to encourage clicks"

Example for a CTA button text:

"Action-oriented text, 2-4 words, using imperative verbs like 'Get,' 'Start,' 'Download,' or 'Learn'"

Example for image caption:

"Descriptive caption that provides context for the image. Keep it concise (10-15 words) and complement the surrounding content without repeating it."

Example for blog post body (rich text):

"Well-structured content with clear headings, short paragraphs (3-4 sentences), and natural transitions. Write in an informative yet engaging tone. Use subheadings to break up sections. Include relevant examples and actionable takeaways."

Example for author bio field:

"2-3 sentence professional biography focusing on relevant expertise and credentials. Written in third person."

Best practices#

General principles#

Follow these principles to create effective AI guidance:

• Be outcome-focused: Describe what the content should achieve, not just how to write it
• Start minimal and add incrementally: Begin with essential instructions and refine based on actual results
• Layer your guidance: Keep project-level broad, component-level contextual, field-level specific
• Provide context over prescription: Explain the "why" and let AI determine the "how"
• Avoid redundancy: Don't repeat guidance that's already captured at higher levels
• Use consistent terminology: Maintain the same language across all guidance
• Make it actionable: Use clear, implementable instructions
• Balance completeness with brevity: Provide enough detail without overwhelming
• Work with editorial teams: Collaborate to define what guidance should be applied

Using examples strategically#

Examples in your guidance can be powerful but should be used thoughtfully:

• Use examples when the expected value is inflexible (specific formats, strict requirements)
• Avoid examples when more flexibility is needed
• Avoid including examples in project-level guidance
• Remember: examples constrain AI output, so use them strategically

For instance, if you need a page title in a specific format, such as "Our services | MyBrand", providing this example helps. But if you want creative, varied headlines, avoid examples that might limit the AI's creativity.

Limitations and considerations#

Be aware of these limitations when implementing AI guidance:

• Chat availability: Guidance is only available during content edits, not in Scout chats
• Effectiveness: Too much guidance can reduce AI effectiveness by over-constraining the output
• Caution with existing content: AI may unintentionally modify pasted or uploaded content based on applied guidance. Use prompts like "Keep the existing content as is" to prevent unwanted changes
• Credit usage: Guidance increases AI credit usage for each action where it's applied

Working with guidance#

Iterative refinement#

Treat guidance as an evolving part of your content model. Start with minimal guidance, test it with real content creation, and refine based on results. Monitor how often AI-generated content needs revision and adjust your guidance accordingly.

Using MCP server for bulk updates#

For projects with many components or content types, use the MCP server to:

• Set guidance programmatically across multiple definitions
• Update guidance consistently across related components
• Test different guidance approaches efficiently
• Manage guidance as code alongside your content model