Custom Tools

The N3uron MCP Server exposes two categories of tools to AI agents: built-in tools and custom tools. Built-in tools are provided by the module itself and allow the AI agent to access general N3uron capabilities such as browsing the tag model, reading real-time values, querying historian data, reading alarms, and checking system information.

Custom tools extend this foundation with domain-specific logic. In the AI-Ready PV Demo Project, custom tools are implemented as JavaScript scripts executed by the Scripting module and exposed through the MCP Server as callable MCP tools.

The demo includes 10 custom tools: 8 operational tools under Operations and 2 diagnostic tools under System. These tools package common photovoltaic O&M analyses into reusable functions that return structured JSON results the AI model can interpret, summarize, and explain.

Important:

The current custom tool interface does not rely on hidden plant-specific defaults. Values such as the plant root path, KPI group, weather group, tag names, discovery patterns, thresholds, and analysis windows must be provided by the caller, by the custom prompt, or through the optional pv_model_json argument.

Built-in tools vs. Custom tools

Custom tools are application-specific. They allow developers to expose higher-level operations that combine several platform queries, calculations, and business rules into a single AI-callable function.

In the AI-Ready PV Demo, each custom tool receives validated inputs from the MCP Server, executes a linked Scripting script, uses the N3uron Scripting API to read data, and returns a structured result to the AI agent.

Custom tool configuration

In the MCP Server module, custom tools are set up under Tools, with each definition specifying the MCP interface tool and the scripting script that runs when the tool is triggered.

The Script instance field points to the Scripting module instance, and the Script name field points to the script path inside the Scripting action structure.

Tip:

Tool and input descriptions are part of the MCP metadata exposed to the AI agent. Clear descriptions improve tool selection and help the model supply the correct arguments.

Scripting structure

The custom tools are implemented in the Scripting module under the McpCustomTools action group. The action structure is divided into two subgroups that match the tool groups exposed by the MCP Server: Operations and System.

• McpCustomTools/Operations: contains the 8 operational O&M scripts.

• McpCustomTools/System: contains the 2 system diagnostic scripts.

Each script has a worker inactivity timeout configured as 10000 ms. The scripts are intentionally small and delegate the actual analytics to the shared McpToolsLib library.

Scripting library: McpToolsLib

The custom tools share a static library named McpToolsLib, configured under Scripting → Libraries. This library contains the reusable logic used by all custom tools.

The library centralizes request parsing, input validation, time-window resolution, historian queries, real-time tag reads, alarm history analysis, tag metadata inspection, PV model mapping, topology discovery, fleet performance calculation, yield comparison, trend detection, downtime detection, maintenance recommendation logic, and standardized response formatting.

This design keeps the individual scripts short. Fixes and improvements to the analytics logic are made once in McpToolsLib and are then reused by all linked custom tools.

Script wrapper pattern

Each custom tool script follows the same wrapper pattern: load McpToolsLib, call the matching library runner function, pass $.event and $.api, and return the result.

'use strict';

var lib = null;

try {
  lib = $.lib('McpToolsLib');
  return await lib.runOpsSummaryDaily($.event, $.api);
} catch (err) {
  if (lib && typeof lib.fail === 'function') {
    return lib.fail('ops_summary_daily', err, $.event || {}, null);
  }
  throw err;
}

Input strategy

The current tool interface is designed to be portable across different PV tag models. Instead of assuming one fixed plant structure, the tools accept explicit model context through arguments.

The caller can pass direct tag paths, group names and leaf tag names, explicit asset roots, discovery patterns, or a full model mapping through pv_model_json. This allows the same custom tools to work with different naming conventions and customer tag hierarchies.

Time-window strategy

Tools that query historical data support rolling and fixed time windows. Rolling windows use lookback_days. Fixed windows use period_start_utc and period_end_utc.

Tip:

The tools produce better results when the tag model includes clear tag names, descriptions, engineering units, history settings, and a consistent asset hierarchy. This metadata helps the AI agent discover the correct paths before invoking the custom tools.

pv_model_json example

The pv_model_json argument is useful when a custom prompt or client wants to provide all plant-specific mappings in one structured field.

{
  "plant_kpi_group": "KPI_VG",
  "weather_group": "WST",
  "station_group_regex": "^PST_\\d+$",
  "inverter_group_regex": "^INV\\d+$",
  "active_power_tag": "ACTIVE_POWER",
  "active_energy_tag": "ACTIVE_ENERGY",
  "performance_ratio_tag": "PERFORMANCE_RATIO",
  "poa_irradiance_tag": "POA_IRRADIANCE"
}

Available custom tools

The following custom tools are included in the AI-Ready PV Demo.

Tool input summary

The following table summarizes the main required inputs and the additional mapping inputs typically used by each custom tool.

Output schema

All custom tools return a consistent JSON envelope. This makes it easier for the AI model to reason over results from different tools using the same response structure.

The $.event parameter

When the MCP Server invokes a Scripting script on behalf of a custom tool call, it passes the tool arguments through the $.event object.

For example, a tool call that includes path, lookback_days, and threshold_pct makes those values available inside the script as $.event.path, $.event.lookback_days, and $.event.threshold_pct.

Inside McpToolsLib, request parsing is handled centrally. The library reads values from $.event, validates the required fields, applies numeric bounds, parses pv_model_json when provided, resolves paths, and builds a normalized request echo for the response metadata.

Tool-to-script mapping

Each MCP custom tool maps to one Scripting script, and each script calls one runner function from McpToolsLib.

Usage recommendations

• Start with context: Use ops_summary_daily to establish the current plant state before running deeper analysis.

• Provide explicit mappings: Pass direct paths, group names, tag names, regex patterns, or pv_model_json so the tools can resolve the correct tags reliably.

• Use fixed periods for incident reviews: Provide period_start_utc and period_end_utc when investigating a specific event window.

• Use rolling windows for routine checks: Use lookback_days for daily, weekly, or monthly checks relative to the current time.

• Keep tools read-only: The demo custom tools query and analyze data. They do not write tags or modify the node state.

• For AI-Ready PV Demo Project, use /PVSIM/BLUELAKE/PVG001 as the plant root path when testing the tools. This path is supplied as an input and is not assumed automatically by the scripts.

Tips:

Use controlled data and metadata changes to validate how the AI agent behaves. For example:

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 two inverters or stations clearly underperforming and verify that the agent ranks it correctly.

6. Create a daylight zero-power period while irradiance remains high and test 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. Test 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 minimal and explicit 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 email, or messaging services, create charts from the results, generate reports, or trigger follow-up workflows based on the detected issues.

Further details can be found in the MCP Server Tools.