Getting Started with the Modeler Agent: Prompting Playbook

The Modeler Agent is at its best when you provide context, a clear goal, and a defined output format. When you nail the prompt, it doesn’t just save time - it gives you the confidence that you model is built on Pigment best practices.

1. State the business goal, not just the task

• Instead of saying “create a metric called Opex,” try: “I want budget owners to plan Opex by cost center and month.” Giving the Agent the “why” helps it choose the right dimensions.

2. Mention concrete objects when you can

• Use exact block names if known, using the @ feature, for example: metric @Revenue, list @Product

3. Ask for a Plan before execution

• Treat the Agent like a human modeler and ask to review the plans: “Propose a plan to implement this, then wait for my approval. Ask me any clarifying questions t you need to get started”
• You’ll get a structured Plan with specs and TODOs that you can review.

4. Define your risk tolerance

• Be explicit about what is off limits.
• “Only create new metrics/lists, don’t modify or delete existing ones.”
• “You may refactor formulas but don’t change access rights.”

5. Ask for explanation level

• Help the Agent understand how you want it to interact with you.
• “Keep explanations short, I just need the formulas.”
• “Explain step‑by‑step so I can learn the modeling pattern.”

6. Iterate and refine instead of restarting

• If the result isn’t perfect, don’t delete and start over. Give the Modeler feedback and direction.
• “Adjust the plan so this metric uses [dimension] instead of [other dimension].”
• “Keep the structure but change the aggregation logic as follows…”

7. Use examples and edge cases

• Agents love context. The more information you can provide, the better.
• “Here are 3 example records. Show how your transaction list and formulas would handle them.”

This guide is a quick set of prompt categories that tend to work really well, organized by topic. Think of these as your stater kit.

You can copy-paste them directly or tweak them for your specific model. Pro tip: If you’re ever unsure, just ask the Modeler directly: “What is the best way to prompt you?” - it’s surprisingly self-aware. 🙂

• General Capabilities:
  • What skills do you have? What skills don't you have? what are the limitations to what you can help me with?

• Application Context:
  • Explain what you can do for me in this application. Focus on: modeling, formulas, performance, and access rights.

• The Grand Tour:
  • Scan my application structure and summarize the key lists, metrics, and boards you see, in business language.

• Use Cases:
  • Show me example use cases where you’re most helpful for [insert your use case, i.e. FP&A] in Pigment.

• The Rewrite:
  • Rewrite the formula of [metric name] to: [business requirement]. Explain what changed and why.

• The Architect:
  • I need a metric that calculates [business logic] by [dimensions]. Help me design the metric and write the formula.

• The Debugger:
  • I’m getting a formula error in [metric name]. Help me debug it step by step.

• The Audit:
  • Help me identify duplicate metrics and test metrics that could be removed. Confirm that there are:
    • No dependencies
    • No usages in boards
    • No usages in views
    • The block isn’t shared in other libraries 

• Knowledge Check:
  • What do you know about access rights? Can you look at access rights in just this application, or can you look throughout the workspace?

• Permission Guardrails:
  • What can you help me with, with access rights? what can't you help me with?

• Security Audit:
  • What access rights are governing this application?

• Best Practices:
  • Do you have a link to the current best practices or trainings on setting up security and user roles (or access to specific list dimensions)?

• Provide the “Unwritten Rules”
  • The agent doesn’t know your specific company policies, unless you tell it.
  • Strategy: Briefly describe your business logic (e.g. “Headcount excludes contractors”, “FX rates are monthly averages”).

• Be mindful of application visibility
  • If blocks are ambiguously named or lack documentation, the Agent’s suggestions may be less precise.
  • Strategy: mention exact objects and give short descriptions when relevant.

• Speak the Pigment formula language
  • The Agent is an expert in Pigment’s proprietary syntax, not Excel or SQL. If you are moving logic over from an old system, don't just paste it and hope for the best.
  • Strategy: Ask the Agent directly: “Translate this Excel logic into a Pigment formula.”

• Respect Your User Permissions
  • The Agent is an extension of you. If you don't have the rights to edit a specific block or dimension, the Agent won't be able to change it either.
  • Strategy: If a change fails, ask the Agent to explain the error. It can often suggest exactly what an Admin needs to do to unblock you.

• Validation is a Shared Responsibility
  • The Agent is a builder, not a data oracle. It can’t intuitively know if your source data is "correct" from a business perspective.
  • Strategy: Ask it to propose validation checks, reconciliation metrics, and exception reports so you can verify the outputs yourself.

• Internal Focus (No External Web Browsing)
  • T​​​​he Agent cannot directly query your company’s external systems (like your ERP, HRIS, or CRM) unless that data is already integrated and exposed within Pigment.
    Strategy: Summarize the external logic or attach a small example extract, then ask for modeling guidance based on that data.

The Modeler Agent works in two complementary modes to ensure you always have the final say:

• Plan Mode (Specifications & TODOs)
  • The agent drafts Specifications (what to build: lists, metrics, formulas, relationships).
  • It also maintains a TODO list (how to execute: ordered steps).
  • You can review this entire plan in the dedicated UI panel. The Agent will not touch your data until you give the green light.

• Build / Execution Mode
  • After you approve the plan, the agent starts executing: creating/editing lists, metrics, formulas, views, boards, etc.
  • Progress is tracked against the TODO list so you can see what has been done.
  • If something looks wrong during execution:
    • Steer in real-time: Ask the Agent: “Stop and revise the plan to [new requirement].”
    • Make manual adjustments: You can manually adjust a block, then tell the Agent: "Take into account the changes I just made and continue.”

• How to use the Agent effectively
  • Start with: “Create a plan to [goal]. Don’t execute until I approve.”
  • Review the plan in the Plan panel.
  • Approve when you’re comfortable, or ask for a revision: “Revise the plan so that [constraint or preference].”
  • Once building starts, use cat to stay in control: “Pause after creating lists, I want to review before you add formulas.”​​​​​​​​​

Think of the Modeler Agent as part of your team: give it a clear goal, check its plan before it starts building, and then let it build safely in your Pigment application to help you scale faster than ever.