Best practices and examples

This article provides example prompts for the AI-Ready PV Demo Project. The examples show how AI agents can use the N3uron MCP Server, custom prompts, and custom tools to investigate PV plant status, performance, downtime, alarms, maintenance priorities, and configuration quality.

The project is domain-specific: it is designed for PV plant operations. However, the custom tool inputs are explicit enough to support different PV tag models, including single-plant nodes and centralized multi-site nodes where each plant may use a different tag hierarchy.

Beyond this PV example, the same design approach can be adapted to other use cases, contexts, and industrial sectors. The key idea is to combine domain-specific tools with flexible input schemas so AI agents can deliver reliable results without being limited to a single fixed tag structure.

Generalist vs. domain-specific prompt design

The main design trade-off in this project is how general or specific the custom prompts and custom tools should be. More general prompts are flexible and easier to reuse across different PV tag models, but they require the AI agent to perform an exploratory phase first. In that phase, the agent should use the built-in MCP tools to browse the tag model, inspect tag metadata, identify relevant groups and paths, and determine which input values are needed before invoking the custom tools.

More specific prompts and tools are usually more reliable because they reduce ambiguity and give the AI agent clearer operational intent. However, they may be harder to reuse when the tag hierarchy, naming convention, or site structure changes between nodes.

For the AI-Ready PV Demo, the selected approach is domain-specific but configurable. The custom tools understand PV concepts such as inverters, stations, active energy, active power, irradiance, performance ratio, downtime, alarm bursts, and expected yield. At the same time, the tool schemas expose the necessary input parameters so the same logic can be applied to different PV tag hierarchies after the AI agent has resolved the correct paths, groups, tags, and discovery patterns.

Recommendation:

Keep the custom tools specific enough to perform reliable PV analytics, but expose inputs such as path, plant_kpi_group, weather_group, active_energy_tag, active_power_tag, station_group_regex, inverter_group_regex, and pv_model_json so the same tools can adapt to different PV tag models.

Agentic workflow boundaries

In this project, the AI agent is not used as a replacement for deterministic analytics. The recommended architecture separates responsibilities: custom tools and scripts provide the validated calculation layer, while the AI agent provides the orchestration, context management, interpretation, and explanation layer.

This boundary should not be understood as rigid. The AI agent can help reason over results, compare evidence, propose hypotheses, and perform lightweight checks. However, when accuracy, repeatability, or deterministic business logic is required, the core calculation should normally be implemented in custom tools or scripts. The AI agent can then use those results as grounded evidence, combine them with additional context, and produce a clear explanation or recommendation.

This is especially useful in PV operations because issues rarely arrive as fixed workflows. A production drop may be related to underperformance, irradiance, downtime, repeated alarms, missing historical data, bad tag quality, or configuration problems. The AI agent helps decide what to inspect first and which tools should be combined to produce a useful operational answer.

Note:    

LLMs are powerful reasoning systems, but they are probabilistic rather than deterministic execution engines. For critical calculations, validated thresholds, or repeatable business rules, use custom tools or scripts for the calculation layer and let the AI agent focus on orchestration, interpretation, and explanation.    

Prompt and context design best practices

The prompt examples in this article focus on Q&A-style interactions between an operator and an AI agent. However, in production AI systems, the prompt is only one part of the workflow. The quality of the answer also depends on the context available to the model when it reasons, selects tools, and generates the final response.

For the AI-Ready PV Demo, context includes the operator question, plant path, time window, tag metadata, built-in MCP tool results, custom tool schemas, pv_model_json, custom tool outputs, retrieved documentation, and any previous conversation that is still relevant to the task.

Tip:        

Prompt descriptions and tool input schema descriptions are exposed as metadata to the AI model. Clear metadata improves tool selection, parameter filling, and final response quality.    

From prompt engineering to context engineering

Modern AI-agentic systems require more than well-written prompts. The broader practice is known as context engineering; deciding which instructions, retrieved documents, tool outputs, structured data, metadata, and conversation history are provided to the model at inference time.

In this project, context engineering means giving the AI agent enough information to select the right workflow and explain the result, while keeping deterministic calculations inside the custom tools. The agent should receive compact, relevant context, not the full tag tree, large historian exports, or unrelated documentation.

This is especially important in centralized multi-site deployments. Instead of loading the full site hierarchy into the model, the AI agent should identify the relevant plant first, resolve the required inputs, call the appropriate custom tools, and then use the compact tool results as the main evidence for the final answer.

Note:    

Treat the context window as a limited working area. For PV troubleshooting, include the operator question, plant path, time window, resolved tag mappings, selected tool results, and only the external documents needed to explain the issue. Remove duplicated, outdated, or low-relevance information before asking the model to reason over the case.    

For broader background, see IBM’s article on Context Engineering, the official Model Context Protocol introduction, and Anthropic’s article on Context windows.

Reusable PV model context

For the packaged AI-Ready PV Demo, the following context can be reused in prompt arguments or in pv_model_json. In customer deployments, replace these values with the corresponding paths and naming conventions for each PV plant.

{
  "path": "/PVSIM/BLUELAKE/PVG001",
  "plant_kpi_group": "KPI_VG",
  "weather_group": "WST",
  "station_group_regex": "^PST_\\d+$",
  "inverter_group_regex": "^INV\\d+$",
  "active_energy_tag": "ACTIVE_ENERGY",
  "active_power_tag": "ACTIVE_POWER",
  "active_energy_day_tag": "ACTIVE_ENERGY_DAY",
  "active_power_total_tag": "ACTIVE_POWER_TOTAL",
  "performance_ratio_tag": "PERFORMANCE_RATIO",
  "capacity_factor_tag": "CAPACITY_FACTOR",
  "nominal_power_tag": "NOMINAL_POWER",
  "poa_irradiance_tag": "POA_IRRADIANCE",
  "irradiance_path": "/PVSIM/BLUELAKE/PVG001/WST/POA_IRRADIANCE"
}

Prompt examples

The following examples are based on the custom prompt configuration included in the project. Each example includes the prompt intent, the arguments exposed to the MCP client, and the prompt body that guides the AI agent.

Prompt example 1: Check plant status

Use this prompt when the operator needs a quick operational overview of the PV plant. It is normally backed by the ops_summary_daily custom tool.

Get a quick status update for the solar plant.

Use path=<<path>> and include_forecast=<<include_forecast>>.

Status: healthy / warning / critical. Summarize alarms, production, forecast, and top next actions. Plain language.

Prompt example 2: Find worst-performing assets

Use this prompt when the operator wants to identify underperforming stations or inverters. It is normally backed by the ops_performance_scan_fleet custom tool.

Find the worst-performing assets at the solar plant.

Use path=<<path>>, threshold_pct=<<threshold_pct>>, and lookback_days=<<lookback_days>>.

Report worst assets first, plain language. Note if isolated or plant-wide. End with next checks for the field team.

Analyze fleet performance for the BLUELAKE solar plant and produce an operator-ready HTML report.

Use the following inputs:
- path: <<path>>
- threshold_pct: <<threshold_pct>>
- lookback_days: <<lookback_days>>

If the custom tool is unavailable, compute the same analysis from built-in MCP tag/history calls using ACTIVE_ENERGY deltas over the same lookback_days window.

Report requirements:
1. Rank the worst-performing assets first.
2. Show inverter-level and station-level results separately.
3. Clearly state whether the issue is isolated, station-local, or plant-wide.
4. Compare each flagged inverter against:
   - fleet average
   - healthy peer average
   - paired inverter in the same station
5. Explain the operational meaning in plain language, not just percentages.
6. Distinguish real underperformance from likely data-quality or counter issues.
7. Include alarm context if active or recent alarms may explain the result.
8. End with prioritized next checks for the field team.

HTML artifact requirements:
- Create a standalone HTML report.
- Include KPI summary cards.
- Include a ranked bar chart of inverter energy production.
- Include a station map showing which inverter is affected.
- Include a station-level comparison table.
- Use clear status colors: red for flagged, amber for watchlist, green for normal.
- Add a short methodology note explaining data source, time window, threshold, and fallback logic.
- Keep the writing concise and suitable for operations staff.

Tone:
- Plain language.
- Worst assets first.
- No vague recommendations.
- Every conclusion should be tied to observed data.

Prompt example 3: Explain recent downtime

Use this prompt when the operator wants to understand production stops during daylight conditions. It is normally backed by the ops_downtime_summarize custom tool.

Explain recent downtime at the solar plant.

Use path=<<path>>, granularity=<<granularity>>, and lookback_days=<<lookback_days>>.

Report: what stopped, when, which assets were affected, likely cause, and what to check next.

Suggested defaults:

Use granularity = station for plant-level triage and granularity = inverter for detailed troubleshooting. Typical downtime detection values are irradiance_threshold = 50 and zero_power_threshold_kw = 0.5.

Prompt example 4: Investigate an open-ended problem

Use this prompt when the operator asks a natural-language question and is not sure which diagnostic workflow to use. This is the most agentic prompt because the AI model must route the question to the appropriate diagnostic workflow.

Investigate: <<question>>

Use path=<<path>> and lookback_days=<<lookback_days>>. Choose the right diagnostic workflow:
- Downtime / stopped / offline → downtime summary
- Alarms / faults / trips → alarm pattern analysis
- Low output / underperformance → performance scan
- Current status / overview → plant summary

What seems to be happening: <diagnosis>
Why: <tool evidence only>
Confidence: High / Medium / Low
Best next action: <one action>

Prompt example 5: Create a maintenance plan

Use this prompt when the operator wants a prioritized maintenance plan based on recent performance and alarm evidence. It is normally backed by the ops_maintenance_recommend custom tool.

Build a maintenance plan for the solar plant.

Use path=<<path>> and lookback_days=<<lookback_days>>.

Format:
1. Asset / Problem / Why it matters / What to do

If no actionable result is found, say so directly.

Prompt example 6: Audit configuration quality

Use this prompt when the operator or integrator wants to validate tag quality, historian configuration, descriptions, engineering units, real-time quality, or backup age. It is normally backed by the system_audit_node custom tool.

Audit configuration quality at the solar plant.

Use path=<<path>> and max_backup_age_hours=<<max_backup_age_hours>>.

Start with overall health: healthy or not. List problems: missing history, missing descriptions, missing units, and bad realtime quality. For each issue, explain what is wrong, why it matters, and what to fix.

Direct natural-language examples

The following examples can be used directly in an MCP-compatible AI agent without selecting a custom prompt first. They validate whether the AI agent can select the correct custom tool from the operator’s wording.

Concrete vs. ambiguous prompts

Ambiguous prompts are useful for natural operator conversations, but they may require the AI model to ask clarifying questions or discover topology first. Concrete prompts are better for repeatable workflows because they provide the plant path, analysis window, thresholds, tag names, and expected output format.

Best practice:

Use ambiguous prompts for exploratory conversations and concrete prompts for repeatable workflows and predefined operator tasks.

Validation and extension tips

Tip:

1. Delete the description from one important tag and run a tag audit.

2. Delete the engineering unit from a power, energy, or irradiance tag and check whether the audit reports it.

3. Disable history on one relevant tag and verify that the audit identifies the missing Historian configuration.

4. Backfill historical data with normal production values and confirm that no false underperformance is reported.

5. Backfill historical data with one inverter or station clearly underperforming and verify that the agent ranks it correctly.

6. Create a daylight zero-power period while irradiance remains high and validate whether downtime is detected.

7. Add low-irradiance periods with low production and confirm that the agent does not report them as abnormal downtime.

8. Create repeated alarms for the same asset and check whether alarm pattern analysis groups them correctly.

9. Run the same prompt with different plant paths or site roots to confirm that the tool input schema works across different PV tag models.

10. Run the same question with ambiguous and concrete prompts to compare how much the provided context improves tool selection, parameter resolution, and final answer quality.

11. Add supporting knowledge sources to your AI agent, such as manufacturer datasheets, internal procedures, maintenance manuals, company policies, or RAG-based documentation. Then ask the agent to cross-reference the custom tool results with those sources to produce more contextual recommendations.

12. Connect additional MCP servers to extend the agent’s capabilities beyond analysis. For example, the agent could send notifications by SMS, email, or messaging services, create charts from the results, generate reports, or trigger follow-up workflows based on the detected issues.