The server defines 2 tools with complete input schemas and reasonable descriptions. Tool names follow verb_noun convention (get_electricity_consumption, get_gas_consumption). Descriptions explain what the tools do and mention parameter sources (environment variables). However, several quality issues prevent a higher score: (1) Parameter descriptions are present but minimal, many lack detail about constraints, ranges, or expected formats. (2) No output schema is documented, LLMs cannot predict the structure of returned data or plan downstream operations. (3) Error handling is generic ('Error: {message}') with no recovery guidance. (4) No tool annotations (readOnlyHint, idempotentHint) despite both tools being read-only. (5) Parameters like 'group_by' have enums but other params (period_from, period_to, page_size, order_by) lack detailed constraints in descriptions.
Get electricity consumption data from Octopus Energy. Returns consumption in kWh with 0.045 kWh precision. MPAN and serial number can be provided as parameters or will use values from ELECTRICITY_MPAN and ELECTRICITY_SERIAL_NUMBER environment variables.
Get gas consumption data from Octopus Energy. Returns consumption in kWh for SMETS1 meters or cubic meters for SMETS2 meters. MPRN and serial number can be provided as parameters or will use values from GAS_MPRN and GAS_SERIAL_NUMBER environment variables.
No output schema documented. LLMs cannot predict response structure, field types, or what data is available for downstream tool calls or context planning.
Parameter descriptions lack detail on ranges and constraints. 'page_size' says 'default: 100, max: 25000' in description but no mention of minimum or validation. 'period_from' and 'period_to' mention ISO 8601 format but do not state if they are required or optional when group_by is used.
No tool annotations present. Both tools are read-only operations; marking them with readOnlyHint would help agents understand they are safe to retry and do not modify state.
Add explicit output schema documentation in the Tool definitions or in handlers.ts. Specify fields like consumption_value (number), unit (string: 'kWh' or 'm³'), period_from (ISO 8601 string), period_to (ISO 8601 string), meter_type (string), and pagination fields (total_count, next_cursor). Example: 'Returns an object with keys: data (array of {interval_start, interval_end, consumption, unit}), total_count (int), next_cursor (string or null).'
Enhance parameter descriptions with explicit ranges and constraints. For example: 'page_size: Number of results per page (default: 100, min: 1, max: 25000, larger values may timeout).' For 'period_from' and 'period_to': 'ISO 8601 datetime with UTC (e.g., 2024-01-01T00:00:00Z). If omitted, defaults to last 30 days.'
Add tool annotations in the schema. Update getToolDefinitions() to include readOnlyHint: true in both tool definitions since these are read-only queries. This signals to LLMs that they are safe to retry on transient failures.
Improve error handling in CallToolRequest handler. Categorize errors: (1) Missing required params: 'Missing required parameter: mpan or ELECTRICITY_MPAN env var. Set ELECTRICITY_MPAN in .env or pass mpan as parameter.' (2) Invalid format: 'Invalid period_from format. Expected ISO 8601 UTC (e.g., 2024-01-01T00:00:00Z), got: {value}.' (3) API errors: 'Octopus API error: {status_code}, {message}. Try again or check your API key.' (4) Rate limit: 'Rate limited by Octopus API. Wait 60 seconds and retry.'
Clarify conditional parameter logic. Update descriptions: 'mpan: The MPAN for the electricity meter (required unless ELECTRICITY_MPAN environment variable is set). If both are missing, the tool will fail with a clear error message.' Apply same to all optional env-backed parameters.
Score history
Overall score trend
↑ 49 points across a rubric change (v1 → v2)
49/100
Scored
Grade
Overall
Spec posture
Rubric
2026-09-22
F
49
2026-07-28+
v2
2026-03-09
F
0
-
v1
Error handling is minimal and non-actionable. CallToolRequest handler catches errors and returns generic 'Error: {message}' with no recovery guidance, retryability classification, or suggested next steps for LLMs.
Parameter descriptions do not clearly document conditional dependencies. The description says 'Optional if ELECTRICITY_MPAN is set in .env' but does not state whether mpan is REQUIRED if the env var is not set, or what happens if neither is provided.
get_electricity_consumptionget_gas_consumption
Document pagination behavior explicitly. E.g., 'Returns up to page_size results. Use the next_cursor field (if present) in subsequent calls to fetch the next page. total_count indicates the total number of records available for the given period.'
Add an example response snippet in the server README or as a comment in handlers.ts so LLMs and developers understand the structure. E.g., { data: [{interval_start: '2024-01-01T00:00:00Z', interval_end: '2024-01-01T01:00:00Z', consumption: 0.5, unit: 'kWh'}], total_count: 100, next_cursor: 'abc123' }
Consider adding a helper discovery tool (e.g., 'get_account_info') to return available MPANs and MPRNs so agents can self-discover meter identifiers instead of relying on environment variables.