Static source inference · medium confidence · detected: Logging
Deprecated protocol patterns detected
Summary
Victron-tcp provides 31 tools for reading Victron Energy device metrics via Modbus TCP and MQTT. All tools have descriptions and enumerated transport parameters. However, critical gaps undermine quality: (1) output schemas are completely undocumented, no response structure is visible in source code for ANY tool; (2) most parameter descriptions are minimal (5-15 chars) and lack format/range guidance; (3) no error handling guidance is visible, tools do not specify what errors they return or how to recover; (4) tool names are generic and overlapping (victron_*_status repeated 20+ times with no clear distinction in naming); (5) composition is poor, 31 tools read different metric categories but provide no unified discovery or chaining mechanism. The codebase structure (src/tools/*.ts) suggests modular implementation, but parameter descriptions are trivial (e.g., 'modbus TCP port' instead of 'Modbus TCP port (502 default, range 1-65535)') and output documentation is entirely absent. This is a domain-specific tool suite, not a general-purpose SDK, and the descriptions reflect that lack of polish.
Tools (31)
victron_acload_statusread only43/100
Read AC load status and metrics from Victron GX device
victron_alternator_statusread only43/100
Read alternator status and metrics from Victron GX device
Output schemas completely undocumented. No tool in the codebase shows return type schema or response field documentation. LLMs cannot plan downstream calls or extract required fields (e.g., device IDs for chaining).
Document output schemas for all 31 tools. Add 'Returns' sections to tool descriptions or create a companion schema document. Specify field names, types, and whether they are IDs suitable for chaining. Example: 'Returns: {host: string, port: number, unitId: number, status: {voltage: number, current: number, power: number}, connectedSince: ISO8601string}'.
Enhance parameter descriptions with explicit constraints. Change 'modbus TCP port' to 'Modbus TCP port (default 502, range 1-65535)'. Change 'connection timeout in milliseconds' to 'Connection timeout in milliseconds (min 100, max 30000, default 5000)'. Change 'device instance for MQTT' to 'Device instance identifier (alphanumeric, e.g., "battery0", max 32 chars)'.
Rename status tools for clarity. Instead of victron_*_status, use get_victron_*_metrics or read_victron_* (e.g., get_victron_battery_metrics, read_victron_solar_charger). Reserve 'status' for simple true/false online/offline checks. Reduces collision and clarifies intent.
Add error handling guidance to discovery and setup tools. Document failure modes: e.g., 'victron_discover may timeout if hosts are unreachable (timeout > 30s). If no devices found, check subnet CIDR, firewall rules, and Modbus port availability. Retry with a larger timeout if network latency is high.'
Create a tool composition map. Document which tools should be called in sequence (e.g., victron_discover → victron_setup_modbus → victron_system_status). Add 'Depends on' and 'Feeds into' sections to tool descriptions. Enable agents to plan multi-step queries.
Spec posture evidence
Inferred effective spec: 2025-06-18+.
Relies on Logging (deprecated) - log to stderr or use OpenTelemetry
Score history
Overall score trend
↓ 13 points across a rubric change (v1 → v2)
44/100
Scored
Grade
Overall
Spec posture
Rubric
2026-09-22
F
44
2025-06-18+
v2
2026-03-09
D
57
-
v1
victron_discover
read only50/100
Discover Victron devices on the network via Modbus TCP
victron_evcs_statusread only43/100
Read EV charger status and metrics from Victron EVCS device
victron_generator_statusread only43/100
Read generator status and metrics from Victron GX device
victron_genset_statusread only43/100
Read genset status and metrics from Victron GX device
victron_get_docsread only41/100
Get documentation about Victron registers and data types
victron_gps_statusread only43/100
Read GPS status and location data from Victron GX device
victron_grid_statusread only43/100
Read grid status and metrics from Victron GX device
victron_gx_inforead only43/100
Read general GX device information and system metrics
victron_inverter_statusread only43/100
Read inverter status and metrics from Victron GX device
victron_list_registersread only42/100
List available registers for a Victron device category
victron_meteo_statusread only43/100
Read meteorological sensor status from Victron GX device
victron_mqtt_discoverread only50/100
Discover Victron devices via MQTT
victron_multi_statusread only43/100
Read Multi charger/inverter status and metrics from Victron GX device
victron_network_scanread only47/100
Scan network for Victron Modbus TCP devices
victron_pvinverter_statusread only43/100
Read PV inverter status and metrics from Victron GX device
victron_read_rawread only44/100
Read raw Modbus registers from Victron device
victron_setup_modbusread only42/100
Configure and test Modbus TCP connection to Victron device
victron_setup_mqttread only42/100
Configure and test MQTT connection to Victron device
victron_solar_statusread only43/100
Read solar charger status and metrics from Victron GX device
victron_system_statusread only43/100
Read system status and metrics from Victron GX device
victron_tanks_statusread only43/100
Read tank sensor status and metrics from Victron GX device
victron_temperature_statusread only43/100
Read temperature sensor status and metrics from Victron GX device
victron_vebus_statusread only43/100
Read VE.Bus device status and metrics from Victron GX device
Parameter descriptions are minimal and lack actionable constraints. Examples: 'modbus TCP port' (no default, no range), 'device instance for MQTT' (no format), 'connection timeout in milliseconds' (no min/max bounds). LLMs cannot validate inputs or understand constraints.
Naming collision and poor distinction. 20+ tools named 'victron_*_status' with identical suffixes. LLMs struggle to select the correct tool when names are so similar. No clear naming convention distinguishes between read operations, discovery, and setup tools.
No error handling guidance. Tools do not document what errors they return, when to retry, or how to recover. Example: victron_discover could fail due to network timeouts, unreachable hosts, or invalid CIDR notation, but the description and code do not indicate what to do on failure.
No tool composition or chaining metadata. 31 tools exist but no documentation of which outputs feed into which inputs. For example, victron_discover returns device IPs, but it is unclear if those IPs can be passed directly to victron_system_status or if additional setup is required.
Parameter names lack type suffixes or clarification. 'host' could be hostname, IP, or FQDN. 'port' appears without context (is it Modbus 502 or MQTT 1883?). 'unitId' has no format guidance (1-247 range for Modbus, but undocumented). LLMs cannot disambiguate without explicit type hints.
Add 'when to use' clauses to overlapping tools. Distinguish victron_system_status (general metrics), victron_battery_status (battery-specific), and victron_gx_info (GX device info). Example: 'Use victron_system_status for aggregate system health. Use victron_battery_status for detailed battery SOC, voltage, and current. Use victron_gx_info for device model and firmware version.'
Implement per-item error reporting. If victron_network_scan scans 10 IPs and 3 are unreachable, return {successful: [...], failed: [{ip, reason, retryable}]} instead of a blanket error. Enables partial progress.
Add examples to the companion docs tool (victron_get_docs). Document expected response shapes, typical parameter values, and common error scenarios. Make docs queryable and LLM-discoverable.
Consider batch tools. If agents frequently call victron_read_raw in loops (e.g., reading 10 registers), offer a victron_read_raw_batch tool accepting an array of addresses. Reduces token overhead and latency.
Validate inputs early and return actionable errors. Example: 'Invalid unitId: 300. Modbus unit IDs must be 1-247.' instead of a generic 'Invalid input' error.