Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@PLENTICORE MCP Show today's solar yield and current battery charge"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
English · Deutsch
An MCP server for KOSTAL PLENTICORE inverters. Read power, energy counters and events, inspect settings, and change settings available to the plant owner. The server connects to the inverter's local REST API using pykoplenti and the official MCP Python SDK.
Tested with a PLENTICORE plus 8.5 running firmware 01.30.12092, API 0.2.0.
Other models and firmware versions have not been tested. Available measurements
and settings are discovered from the connected device.
Install uv and Python 3.11 or newer, then clone the repository:
git clone https://github.com/NemoN/plenticore-mcp.git
cd plenticore-mcp
uv sync --frozen
cp .env.example .env
chmod 600 .envEdit .env with your inverter's address and the plant owner password from its
local web interface:
PLENTICORE_URL=http://plenticore.example
PLENTICORE_PASSWORD=replace-locally
PLENTICORE_TIMEOUT=20
PLENTICORE_VERIFY_SSL=true
PLENTICORE_READ_ONLY=trueUse the base URL without /api/v1. The example starts in read-only mode. Set
PLENTICORE_READ_ONLY=false when you want to apply settings changes. If omitted,
the code default is false; update calls still preview by default.
Check the login and current readings:
uv run --frozen plenticore-mcp --checkThe check reads status and measurements without changing device settings.
Exit code 0 means success; 1 indicates a connection or API error; 2 indicates
invalid configuration. Starting without --check waits for an MCP client.
Related MCP server: tesla-powerwall
For clients using mcpServers JSON, replace the two absolute paths:
{
"mcpServers": {
"plenticore": {
"command": "uv",
"args": [
"run", "--frozen", "--directory", "/absolute/path/plenticore-mcp",
"plenticore-mcp", "--env-file", "/absolute/path/plenticore.env"
]
}
}
}The env file can be the checkout's .env or a separate private file. If the
client cannot find uv, use its full executable path. The client starts the
stdio process when needed. Standard output is reserved for the MCP protocol.
examples/ contains JSON and Codex TOML configurations. See configuration for environment variables, HTTPS and remote connections.
uv run --frozen plenticore-mcp --transport streamable-http --port 8001Connect to http://127.0.0.1:8001/mcp. The listener binds to loopback and has no
MCP authentication. Use an SSH tunnel for access from another machine.
All names start with plenticore_. The tool reference lists
their arguments and defaults.
Tool, without prefix | Purpose |
| API and firmware versions, session status, read-only mode |
| Modules offered by the inverter |
| Search measurement IDs, with pagination |
| Read selected measurements |
| Power flow, AC, PV strings, battery and grid meter, where available |
| Battery-related readings, where available |
| Energy statistics for |
| Recent events in German or English |
| Setting IDs, types, units, access rights and bounds |
| Read selected current settings |
| Preview changes, or write and read them back |
Example requests for a connected assistant:
Show today's yield, this month's yield and the current AC output.
List the battery settings and their current values. Prepare a preview of the change I request before applying it.
Values and signs are returned as supplied by the inverter. Some firmware sends
an empty unit; an empty unit does not mean that the value is dimensionless.
Dc_P can include battery power. Use the individual PV string measurements when
you need solar input power.
Energy periods follow the inverter clock. The server has no historical database
or arbitrary date-range query. Missing measurements appear under missing;
non-finite numeric values become JSON null. A battery-related data point does
not establish that a physical battery is installed.
Read list_settings and read_settings before changing a value. Pass setting
values as strings in the inverter's native units. update_settings defaults to
dry_run=true and returns the current and proposed values. Set dry_run=false
to submit the change and read it back.
The server checks advertised access rights, supported data types and numeric bounds. It rejects unknown IDs, unsupported types and write-only settings. Password and token settings recognized by their IDs are excluded. The inverter enforces the plant owner's permissions; installer access is not implemented.
Writes are not atomic. A failed request may leave some changes applied. Read
the current settings before retrying. The result reports verification as
matched, mismatch or unavailable; it does not perform an automatic rollback.
PLENTICORE_READ_ONLY=true blocks writes while allowing previews.
See SECURITY.md for access and reporting details.
docker build -t plenticore-mcp .
docker run --rm -i --env-file .env plenticore-mcpUse -i without -t for stdio. The inverter must be reachable from the
container. The image runs as an unprivileged user and installs hashed runtime
dependencies from requirements.lock. No prebuilt container image is published.
uv sync --frozen
uv run --frozen pytest -q
uv run --frozen ruff check src tests scripts
uv run --frozen ruff format --check src tests scripts
uv run --frozen python scripts/generate_tool_reference.py --check
uv build
uv run --frozen python scripts/check_artifacts.py dist/*.whl dist/*.tar.gzTests use a local inverter emulator, including the login handshake, and real MCP stdio and HTTP connections. They do not require a physical inverter. Live validation covered all eleven tools; the update tool was tested as a preview. Actual writes and readback failures have been tested against the emulator only.
See CONTRIBUTING.md and CHANGELOG.md.
MIT licensed. Independent project, not affiliated with KOSTAL Solar Electric. Report reproducible problems through GitHub Issues. Remove credentials and identifying device details from reports and logs.
Read available battery measurements, including SoC and power.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=true, so the safety profile is fully covered. The word 'available' adds a small hint that some measurements may be absent, but nothing is said about freshness, units, or polling behavior, which matters for live measurements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with the verb first and the payload examples second; no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return structure needn't be explained, and the zero-parameter surface keeps things simple. However, for a live-measurement tool there is no mention of data freshness, units, or how it differs from plenticore_energy, leaving agent-visible gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so there is no parameter semantics to explain; baseline 4 applies. The description correctly implies the call needs no inputs.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
A specific verb+resource (read battery measurements) with example data points (SoC, power) that make the content concrete. It distinguishes itself from siblings like plenticore_overview or plenticore_status by scoping to battery, though it doesn't explicitly state the boundary versus plenticore_energy.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied: an agent infers to call it when battery state-of-charge or power readings are needed. There is no explicit when/when-not guidance and no reference to which sibling to use for energy or status instead.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read inverter-native energy counters for Day, Month, Year or Total. Preserve units.
| Name | Required | Description | Default |
|---|---|---|---|
| period | No | Day |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare this a read-only, idempotent, non-destructive call, so the safety profile is covered. The description adds two genuinely useful behavioral notes beyond that: values are 'inverter-native' (unprocessed, not normalized) and units must be preserved. It does not say whether counters are cumulative, their resolution, or how units are labeled.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two terse sentences with no filler; the scope statement comes first and the units caveat second. Every clause carries information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter read tool with an output schema, the description plus annotations are close to sufficient; return values need not be explained. The gaps are minor but real: unit conventions and the meaning of the aggregate periods are left implicit.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries the burden, but it mostly restates the enum values already visible in the schema. It does not explain the semantics of 'Total' vs 'Year' or mention the 'Day' default, leaving real ambiguity unaddressed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Read inverter-native energy counters') and binds it to the four period values, which distinguishes it from siblings like plenticore_battery or plenticore_status. It does not explicitly name any sibling, so differentiation is inferred rather than stated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this versus related siblings (e.g. plenticore_list_process_data or plenticore_overview), and no prerequisites or exclusions. The period list implies context but gives the agent nothing to decide with.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read the latest 1–100 inverter events; active events may have end_time=null.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| language | No | de-de |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so safety behavior is well covered. The description adds useful data semantics beyond annotations by noting the 1–100 limit and that active events may have end_time=null. It does not cover auth or rate limits, but that is a minor gap given the annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single front-loaded sentence with no filler. Every phrase, including the 1–100 range and the end_time=null nuance, adds useful information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a low-complexity, read-only tool with only two parameters, rich annotations, and an output schema, the description covers the main purpose and an important event-state nuance. It is nearly complete, though it omits the language parameter's role and does not explain when to prefer this tool over sibling status or overview tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for two undocumented parameters. It partially explains the limit behavior via 'latest 1–100' but does not name the limit parameter or mention its default. The language parameter and its enum values are not addressed at all.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Read' + 'inverter events'. It also adds scope with 'latest 1–100' and notes active events may have end_time=null. It does not explicitly differentiate from siblings such as status or overview, but the resource is clear enough to distinguish it in practice.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'Read the latest... events' implies the tool is used to retrieve recent event data. However, it gives no explicit when-to-use guidance, no exclusions, and does not mention alternatives such as plenticore_status or plenticore_overview. Usage is therefore implied rather than fully stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Discover the modules actually offered by this inverter and current user.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive and open-world, so the safety profile is covered. The description adds genuine context beyond them: the returned module set is scoped to the specific inverter AND the current user, meaning results are permission-dependent and not universal. It does not, however, say whether the call can fail on auth or whether modules gate the other tools.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single eleven-word sentence with the action and the scoping qualifier front-loaded and zero filler. Nothing could be removed without losing meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With zero params, full annotation coverage and an output schema that documents the return shape, the description only needs to convey what the call yields and under what scoping. It does that, though it omits the practical implication that module presence determines which sibling tools are usable — the one piece of context an agent would most benefit from.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. Schema coverage is 100% with an empty properties object, consistent with the description implying no arguments are needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The verb 'Discover' plus the resource 'modules actually offered by this inverter and current user' states a specific capability-enumeration operation, clearly distinct from the data-reading siblings (battery, energy, status, settings). It is clear but does not explicitly frame the result as a feature/capability manifest, which is what an agent would need to differentiate it from, say, plenticore_overview.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description contains no when-to-use or when-not-to-use guidance and never mentions any sibling tool. The phrase 'actually offered ... and current user' hints at a permission-dependent capability check, but the agent is left to infer that this is the discovery step to run before calling the other plenticore tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Discover measurement IDs. Search module/ID; follow next_offset for more.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | No | ||
| offset | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, idempotent, non-destructive, open-world behavior, so the description needs only supplementary context. It adds pagination behavior via 'next_offset', but does not clarify result shape, rate limits, or how the returned IDs connect to read_process_data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and front-loaded, with no wasted words. It is almost too terse, but it remains structurally efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need not be explained in detail, and annotations cover safety. However, with 0% schema description coverage and three undocumented parameters, the description leaves important invocation details unclear, especially the meaning of limit and offset.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must carry the burden for all three parameters. It mentions searching by module/ID and following next_offset, but does not explain limit or offset clearly, and it refers to 'next_offset' even though the schema parameter is 'offset'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific purpose: discovering measurement IDs, which is a clear resource for an agent. It implies a list/discovery operation rather than reading actual process data, though it does not explicitly name the sibling read_process_data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives implied usage: search by module/ID and follow next_offset for more results. However, it does not explicitly say when to use this tool versus read_process_data or how the search should be structured.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Discover setting types, units, access rights and min/max. Secrets are omitted.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | No | ||
| offset | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered. The description adds one genuinely useful behavioral fact beyond that: secrets are omitted from results, which tells the agent results are redacted and not authoritative for sensitive values. It says nothing about pagination behavior or result volume, so the extra value is real but narrow.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, front-loaded with the primary capability and followed by the redaction caveat. No filler. It is arguably over-terse given the missing usage and parameter context, but nothing in it is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return-value structure needn't be documented. But for a paginated, filterable discovery tool with three undocumented parameters and an adjacent read_settings sibling, the description leaves an agent without enough to call it correctly or choose it confidently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Three parameters (limit, query, offset) with 0% schema description coverage and no enum constraints. The description offers no semantics for any of them - no explanation of what query matches against, or how limit/offset interact. The names and defaults hint at pagination, but the description does not compensate for the coverage gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific outcome: discovering setting types with units, access rights and min/max bounds. That is clearly metadata discovery rather than value retrieval, which implicitly distinguishes it from plenticore_read_settings. However, it never names the sibling or says 'this does not return values', so the differentiation is left to inference.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No when-to-use or when-not-to-use guidance, and no prerequisites. The nearest sibling, plenticore_read_settings, is an obvious confusion point that the description does nothing to disambiguate (e.g. 'call this first to find valid setting keys').
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read power flow, AC, PV strings, battery and meter measurements that exist.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive and open-world, so safety is covered. The phrase 'that exist' adds a useful hint that not every measurement category is guaranteed present, but nothing is said about polling cost, freshness, or behavior on unreachable devices. Modest added value over the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence fragment with no filler; the resource list is delivered immediately. It is slightly clipped, reading more like a field list than a sentence, but every word carries information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need not be described, and there are no parameters to explain. What remains missing is positioning relative to the ten sibling tools, several of which read overlapping data, leaving the selection decision partly unresolved.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters and the schema is empty at 100% coverage, so there is nothing for the description to disambiguate. Baseline 4 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (Read) and enumerates the resource set: power flow, AC, PV strings, battery and meter measurements. An agent can see this is an aggregate snapshot tool, though the overlap with siblings such as plenticore_battery and plenticore_energy is not addressed.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No when-to-use guidance, no preconditions, and no routing to alternatives. The agent is left to infer whether this is a 'read everything at once' shortcut or a preferred entry point over the more granular sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read explicit {moduleid: [IDs]} (max 200), returning native values and units.
| Name | Required | Description | Default |
|---|---|---|---|
| selection | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive, and open-world behavior. The description adds useful context: a 200-selection cap and that values are returned in native units, but it does not discuss auth, rate limits, or error behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with no filler. The verb, selection shape, cap, and return semantics are all packed compactly into one statement.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return details need not be expanded. However, for a tool whose only parameter is a nested ID map, the description omits how an agent should obtain valid module IDs, likely via plenticore_list_process_data or plenticore_list_modules.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must explain the sole nested 'selection' parameter. It does clarify the expected {moduleid: [IDs]} shape and the 200-item max, but it does not explain where valid module IDs come from or any ID format constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: read process data for explicit module-ID selections, with a max of 200 and native values/units returned. It distinguishes itself from a generic list by specifying an explicit selection map, though it does not name the sibling list_process_data directly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The word 'explicit' implies this is for known module IDs rather than discovery, but the description never states when to use it versus plenticore_list_process_data or other siblings. Usage is implied rather than explicitly guided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read explicit {moduleid: [setting IDs]}. Discover IDs first; secrets are excluded.
| Name | Required | Description | Default |
|---|---|---|---|
| selection | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive and openWorld behavior, so the safety profile is covered. The description adds a genuinely useful behavior not in the annotations — 'secrets are excluded' — telling the agent why some settings may be absent from results. It stops short of describing behavior for unknown IDs or missing entries.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no filler, and the operation is front-loaded before the prerequisite. The brace shorthand is dense enough that it takes a moment to parse, which slightly undercuts readability, but nothing is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return-value documentation isn't required, and the annotations plus the secrets-exclusion note cover behavior for a read-only tool. The remaining gap is routing: it never names the specific discovery tool to call first, which matters in a ten-tool sibling set with both list_modules and list_settings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the single parameter is an unlabeled nested object with additionalProperties, so the schema alone is opaque. The notation {moduleid: [setting IDs]} compensates well by explaining that keys are module IDs and values are arrays of setting ID strings — the core semantics the schema omits. It doesn't say where module IDs come from (though 'discover IDs first' hints at it) or whether IDs are case-sensitive.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The verb 'Read' plus 'settings' and the payload form {moduleid: [setting IDs]} gives a concrete operation: fetch specified settings by ID. The word 'explicit' implicitly contrasts with the sibling plenticore_list_settings, though the sibling is never named, so an agent must infer the distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Discover IDs first' is a real workflow prerequisite that steers the agent toward the list tools before calling this one. However, it never names plenticore_list_settings or plenticore_list_modules, and gives no when-not-to-use guidance (e.g., use the list tool when you don't have IDs at all).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read API/firmware version and plant owner session status.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is fully covered. The description contributes only the content scope (version + session status) and says nothing about what a 'session status' value means or whether failures indicate auth problems. Adequate but thin given the annotations already carry the behavioral load.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence naming both returned items with no filler. Nothing could be removed without losing information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, zero parameters, and full annotation coverage, the description only needs to state purpose — which it does. The one gap is that 'plant owner session status' is left undefined, but the output schema likely resolves the return shape.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. Schema coverage is 100% and the empty object confirms no arguments are needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description gives a specific verb ('Read') and concrete resources (API/firmware version, plant owner session status), which distinguishes it from data-oriented siblings like plenticore_overview or plenticore_energy. It stops short of naming which sibling to use when version or session info overlaps with an overview call.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to invoke this versus plenticore_overview or the list_* tools, and no stated preconditions (e.g., whether a session must already exist). The use case is only inferable from the resource names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Preview settings changes; dry_run=false writes and reads back. Values are strings.
Uses actual owner-accessible IDs, types and min/max. No installer login. Read list_settings and the current values first. Multi-setting writes are not atomic; no automatic rollback. A connection error after submission can leave a change applied: read back before retrying.
| Name | Required | Description | Default |
|---|---|---|---|
| values | Yes | ||
| dry_run | No | ||
| moduleid | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the destructiveHint/non-idempotent annotations by disclosing that multi-setting writes are non-atomic, there is no automatic rollback, and a connection error after submission can leave a change applied. The 'read back before retrying' instruction is precisely the behavioral context an agent needs to avoid duplicate writes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four short sentences, front-loaded with the dry-run default, with no filler. A couple of phrases ('Uses actual owner-accessible IDs, types and min/max', 'No installer login') are terse to the point of being slightly opaque without surrounding context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers the full risk profile for a destructive, non-atomic mutation: prerequisite reads, failure/recovery semantics, and the string typing of values, while the output schema handles return shape and annotations cover open-world behavior. An agent can call this safely without further reference.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage the description carries the burden, and it does: dry_run's preview-vs-write meaning is spelled out, 'Values are strings' documents the nested map's value type, and 'Uses actual owner-accessible IDs' constrains moduleid. It never explains what the min/max or type constraints mean for a rejected value, so it is strong but not complete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (update settings) plus the crucial scope qualifier that the default is a preview and only dry_run=false writes. That distinguishes it cleanly from the read_settings/list_settings siblings in the same family, and naming the read-back behavior makes the tool's role unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives an explicit prerequisite: 'Read list_settings and the current values first', which is the key sequencing rule for a settings mutation. It does not spell out when to prefer this over a read-only sibling or when a preview is mandatory, so it stops short of fully explicit when/when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0plenticore_batteryplenticore_energyplenticore_eventsplenticore_list_modulesplenticore_list_process_dataplenticore_list_settingsplenticore_overviewplenticore_read_process_dataplenticore_read_settingsplenticore_statusplenticore_update_settingsScored across 11 tools
The list_* discovery tools are clearly separated from the read_* tools by description (discover IDs vs read explicit IDs), and battery/energy/events/status each target distinct data. The only soft overlap is plenticore_overview, which aggregates battery, PV, meter and AC readings that plenticore_battery and plenticore_energy also expose, so an agent may occasionally choose overview redundantly.
All names use a consistent plenticore_ prefix with snake_case, and the list_/read_/update_ verb pattern is applied predictably to processes and settings. The single-word resource reads (battery, energy, events, overview, status) deviate from the verb_noun pattern but remain unambiguous.
Eleven tools is well within the ideal range for an inverter integration and each earns its place: discovery, targeted reads, an aggregate overview, and a single guarded write path. Nothing appears padded or redundant enough to be dropped.
The surface covers discovery, reads of measurements/energy/events/status, and settings read plus a dry-run-first write, which is a full lifecycle for this domain. Minor gaps exist: no process-data write, no setting pagination noted, and no explicit way to acknowledge or clear events, though these may be limitations of the inverter API.
Home energy for AI assistants: live Power flow, Energy history, solar forecast, and device control.
Control a Loxone Miniserver smart home: lights, blinds, climate, scenes and energy.
Read-only access to authorized SolarSENS solar plants, performance, devices, and alarms.
Unofficial integration! ## ✨ Key Features ### 💰 Financial Intelligence - **Smart Charging Cost An…
