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."

Asset guidance#

Asset guidance lets you define instructions that influence how the AI generates titles, descriptions, and labels when you upload image assets.

Location: Settings > AI Guidance > Assets

Purpose: Provide instructions for how the AI generates titles, descriptions, and labels when images are uploaded.

Character limit: 1,000 characters per field

• Guidance applies when uploading images to a composition, entry, pattern, or the Asset Library.
• Guidance helps ensure that AI-generated metadata follows your team's conventions and standards.

AI guidance page for assets

Title#

The title field lets you instruct the AI on how to generate asset titles during upload.

• The title represents the primary name or identifier of the asset.
• It helps users understand what the asset contains at a glance.
• When no guidance is provided, the AI uses the file name or image content to generate a title.
• With guidance, you can influence formatting, casing, or naming conventions.

Example guidance:

"Use sentence case. If the file name contains a brand or product name, use it as the title. Otherwise, generate a short descriptive title from the image content."

Description#

The description field lets you define how the AI should generate asset descriptions.

• Descriptions provide context about what the asset shows or represents.
• They are generated in an alt-text style suitable for external audiences.
• Use guidance to specify tone, length, or the type of information to include.

Example guidance:

"Write a concise description of 1-2 sentences. Focus on what is visually depicted in the image. Avoid subjective language."

Labels#

The labels field lets you guide how the AI assigns labels to uploaded images.

• Labels help classify and categorize assets for easier discovery and filtering.
• The AI evaluates the image content against labels defined in the project and suggests matching ones.
• Only existing project labels can be assigned. The AI does not create new labels.
• Guidance can instruct the AI on which label categories to prioritize or how to choose between similar labels.

Example guidance:

"Assign labels based on the subject of the image. Prefer specific labels over general ones. Always apply a region label if the image shows a recognizable location."

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.

For asset guidance#

• Write clear, specific title guidance. Describe the naming conventions your team uses, including casing and formatting preferences.
• Add useful description guidance. Specify the tone, audience, and level of detail you expect in asset descriptions.
• Use consistent labeling instructions. Reference the label categories in your project and explain how the AI should choose between them.

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