--- title: "Mission instructions for the Analyst Agent" slug: "write-prompts-for-the-analyst-agent" description: "Craft clear, structured instructions for the Analyst Agent, specifying data, analysis steps, and output format for effective reporting and insights." updated: 2026-05-01T08:00:00Z published: 2026-05-01T08:00:00Z --- > ## Documentation Index > Fetch the complete documentation index at: https://kb.pigment.com/llms.txt > Use this file to discover all available pages before exploring further. # Mission instructions for the Analyst Agent Use this guidance when editing your instructions or chatting with the Agent. > [!WARNING] > ⚠️ Important > > The easiest way to generate effective instructions for the Analyst Agent is to [build your Report using chat](/v1/docs/configure-and-run-the-conversational-analyst-agent#how-to-work-with-the) in the AI Sidebar. Once you’re satisfied with the output, save it as a Mission. You can then [manually edit a Mission’s Instructions](/v1/docs/configure-and-run-the-conversational-analyst-agent#edit-a-mission) at any time to adjust future runs, using this article. ## Essential and optional instructions Your instructions must contain the following: - What data to analyze. - Which analysis steps to follow. Optionally: - Include examples of how the Report should look. - Specify a tone and style for the Report (e.g. concise, executive-friendly, bullet-pointed). - How the output should be structured. - Define a language for the Report. The instructions and Report can be in any of 50 widely-spoken languages. ## Instruction optimization 1. Be as explicit as possible: - When you know a specific Metric, Dimension or Application Variable is needed, use the **Object picker**: type @ to open a dropdown of eligible options. This way, even if the object names are updated at a later time, the Mission still runs. You can reference multiple objects in one instruction. To be eligible, Metrics must have AI data access turned on. For more information, see [Block settings for Metrics](/v1/docs/block-settings-for-metrics#ai-data-access). - To have no charts in your Report, specify “Don’t display charts in the Report.” - Metrics shared from other Applications are eligible. - Directly reference in plain text the Dimension Items you want to filter on. > [!NOTE] > ℹ️ Note > > Agents cannot see formulas. 1. To improve clarity, paste your instruction into an LLM such as ChatGPT, preceded by guidance such as: “What do the following instructions for a Report mean? Can you reformulate them for better readability?” ## Supported capabilities See examples below to replicate in your instructions. **Contribution analysis** **Identify Drivers of Revenue Underperformance** Unlock a clear view of quarterly revenue performance with this analysis example. It enables you to: - Compare actual revenue against forecasts for the last quarter - Pinpoint the top 3 underperforming country–retailer combinations - Drill down to SKU level to surface the main variance contributors - Summarize findings in a concise executive overview before detailing key drivers - Present results in a formal quarterly business review tone—with emojis for emphasis It’s built to deliver structured, insightful, and engaging revenue variance analysis. ```markdown Analysis Analyze @Revenue metric, compare @Version Actual vs Forecast for the @Last_Quarter Identify the top 3 @Countries - @Retailers that have underperformed. For each flagged combination, drill at @SKU level to identify the top 3 contributors of the variance. Use the notes in text metric @weekly_business_comments to add context / insights for any anomalous or unexpected revenue data. Formatting Start with a short executive summary (2-3 lines). Then list the key drivers of the variance using bullet points. Use a formal quarterly business review tone, with emojis. ``` **Variance analysis** **Explain OPEX Variance by General Ledger Account and Department** This generates a structured framework for analyzing operational expenses. It helps you: - Compare OPEX actuals vs. budget at a global level and spot top cost centers driving variances - Flag significant deviations by GL Account × Department where variances exceed ±5k - Drill down further by country and highlight both absolute (€/$) and percentage (%) differences - Present results consistently from run to run, using bullets for short lists or tables for longer ones - Add concise explanations to contextualize each variance for clarity It’s designed to ensure insightful and well-formatted financial analysis output. ```markdown Analysis Start by analyzing the @OPEX metric, compare @Version Actuals vs Budget at global level for the @Current_Month. Identify the top 3 @Cost_centers contributing to the total variance. Breakdown by @GL Account x @Department and flag only combinations where the absolute variance between @Versions Actuals – Budget exceeds ±5000 For each flagged combination: - Drill down further by @Country - Show variance in both Absolute terms (€) and Percentage (%) Formatting - Use bullet points to list key GLs and their associated variances. Add short explanations where possible. - If there are more than 5 items, use a table instead. Output Format Example - GL 60000 - Salaries: +€15.2k vs Budget (+18%) - Higher training expenses in Marketing (+€8.7k) - GL 62100 - Travel: –€11.3k vs Budget (–9%) - Fewer offsites held this quarter ``` **Variance + Multi-report** **Generate a Customized Multi-Report for Each Function to Explain Budget Variance** Get a structured view of functional performance versus budget. This analysis helps you: - Compare actuals vs. budget at a function level and surface the largest positive and negative variances - Drill down into key cost drivers within each function (GL, vendor, or initiative) - Flag only material deviations based on a defined threshold - Add short contextual explanations from prior commentary metrics - Produce a consistent variance summary formatted for monthly reviews It’s designed to deliver clear variance diagnostics function-by-function. ```markdown Analysis For @Function = @Current Item: Compare @Account actuals vs budget for @Current_Month. Rank @Account by absolute variance and flag the top 5 deviations. For each flagged @Account: - Break down variance by @Initiative (if available; otherwise by @GL_Account). - Show absolute and percentage variance. Include only rows where |Actual – Budget| > ±@Threshold. ``` **Trend detection** **Detect and Explain Attrition Trends** Uncover key attrition risks and workforce trends with this analysis framework. It allows you to: - Identify the top 3 roles with the highest attrition over the past year - Correlate attrition with performance, tenure, and location to surface deeper insights - Start with a concise executive summary on global attrition patterns - Present results in a structured table (Role | Attrition % | HC Lost | Trend 📈/📉) - Add focused bullet points under each role to explain the drivers behind attrition It’s designed to provide a clear, insight-rich view of attrition dynamics without relying on charts. ```markdown Analysis For the whole analysis filter on @CurrentYear 1. Identify the Top 3 @Employee_Role with the highest attrition using @Attrition metric 2. For each of these flagged roles, provide additional insights by correlating @Attrition to: @Attrition_Performance → check if high performers or low performers are leaving. @Attrition_Tenure → check if attrition is concentrated among junior or senior staff. @Attrition_Location → see if attrition is localized in specific geographies. Formatting Begin with an executive summary (1–2 sentences) on global attrition trend. Present the Top 3 Roles with attrition in a table: Role | Attrition % | HC Lost | Trend (📈/📉). Add bullet points under each role summarizing key insights Don't display charts ``` **Comparison** **A****nalyze staffing gaps** Gain clear visibility into organizational staffing gaps with this analysis approach. It guides you to: - Compare total headcount demand versus supply at a global level, highlighting absolute and percentage gaps - Identify the entity with the largest shortfalls and zoom into the top 3 cost centers driving them - Break down gaps further by job profile within each flagged cost center - Surface any additional critical shortages across the model where gaps exceed 30% - Present results in structured tables and pair findings with actionable recommendations (open positions, transfers, or scope adjustments) It’s built to deliver a precise and actionable view of workforce capacity gaps for the current month. ```markdown Analysis Compare @Headcount_Demand and @Headcount_Supply to identify the most critical staffing gaps across the organization for the month of @Current_Month. Global overview to compare total demand vs. supply (absolute and % gap). - Identify the main @Entity with the largest negative gaps (Demand > Supply). - Then for each @Entity, zoom into the top 3 @Cost_Center with the largest shortfalls. - Then, within each flagged @Cost_Center, list all the @Job_Profile with a negative gap. - Finally, scan the full model to flag additional critical gaps (Gap > 30%) not covered before. Output format Use structured tables with the following columns: Entity | Cost Center | Job Profile | Demand | Supply | Gap | Gap % Recommendations For largest gaps, suggest potential actions: open positions, internal transfers, or scope adjustments. ``` ## Limitations - Shared Scenarios are supported, but local Scenarios are not. - Member-based variables are not supported. - Variables with names containing special characters are not supported (for example, `[d]CurrentMonth`). - Certain advanced calculations are not supported: - Time series analysis - Correlations - You cannot reference Views in the Instructions. - Scenario Variables that reference a snapshotted Scenario are not yet supported, but referencing Snapshots directly is supported.