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., "@iec-mcp how much was my last electricity bill?"
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.
Read your own Israel Electric Corporation (IEC, חברת החשמל) account from an AI assistant over MCP: bills, invoice PDFs, meter readings and smart-meter consumption.
Unofficial. Not affiliated with IEC. It uses the same customer API as IEC's own website and app, which can change without notice.
Everything runs on your machine. You sign in through your own browser, the session is saved only on your computer, and this project has no hosted backend and collects nothing. Whatever your AI client requests is passed to that client and handled under its provider's privacy terms.
The IEC endpoints and sign-in flow follow the community py-iec-api project (MIT), which documents them for Home Assistant.
Own account only.
Read-only. No payments, no changes to the account, no requests to IEC.
The session file is secret. It holds a refresh token, is saved with mode 0600 under ~/.config/iec-mcp/, and must never be committed or pasted.
Related MCP server: huashu-chrome
git clone https://github.com/tadnir/iec-mcp.git
cd iec-mcp
npm install
npm test{
"mcpServers": {
"iec": {
"command": "npx",
"args": ["tsx", "src/main.ts"],
"cwd": "/absolute/path/to/iec-mcp"
}
}
}For Claude Desktop, use absolute paths: "command": "/absolute/path/to/node" with "args": ["/absolute/path/to/iec-mcp/node_modules/.bin/tsx", "/absolute/path/to/iec-mcp/src/main.ts"].
Ask your assistant something, for example "how much was my last electricity bill?".
While nobody is signed in, the tools answer with a link to a sign-in page this server serves on http://localhost:8766/. iec_login returns the same link.
Open it, enter your ID number and pick how long to stay signed in (1 hour to 30 days). IEC sends a one-time code by SMS or email; enter it on the page.
Ask again.
Your ID number and the code are only ever typed on that page and sent to IEC. The assistant only ever sees the link.
IEC's sign-in gives a refresh token, so the session doesn't depend on activity: the server refreshes the tokens shortly before they expire, saves them, and signs out at the end of the length you picked. A restart picks the saved session back up.
Tool | What it reads |
| The account holder: BP number, accounts, contact details |
| Contracts (one per address) with debt and due date |
| The current bill summary |
| Invoices with amounts, periods and consumption; one invoice as a PDF |
| Meters on a contract and their last readings |
| Smart-meter kWh: one day in 15-minute steps, or a week or month of daily totals |
| The sign-in link, whether a session is live and until when, and sign-out |
bpNumber and contractId default to the signed-in customer and their first contract, and the meter to the contract's first meter.
Variable | Default | Meaning |
|
| Where the session is saved |
|
| Address the sign-in page listens on |
|
| Its port; a free one is used if another copy holds it |
|
| The link handed out, when the page sits behind a reverse proxy. When set, the page starts with the server. |
To share one session between several clients, run a single copy on an always-on machine and put a stdio-to-HTTP MCP proxy in front of it, such as TBXark/mcp-proxy, with a bearer token per client. Keep it on your own network or a private VPN, never on the internet. Put the sign-in page behind your own authentication and set IEC_LOGIN_URL to its address (and IEC_LOGIN_HOST=0.0.0.0 inside a container). Its links and forms are relative, so it can sit at the root of a host or under a path whose prefix the reverse proxy strips (IEC_LOGIN_URL=https://mcp.example.com/iec/login/, with the trailing slash).
Every token holder reads the account that signed in on the page; the proxy's tokens and the IEC session are unrelated. For a second person, run a second copy with its own IEC_CONFIG_DIR, tokens and sign-in page.
The Dockerfile builds an image of the stdio server, published as ghcr.io/tadnir/iec-mcp from master, with the session in /data and the page on port 8766. Run it with docker run -i, or use it as a base for an image that adds your MCP proxy.
The sign-in page answers only to localhost, 127.0.0.1 and the host in IEC_LOGIN_URL, and each form carries a per-process token. Anyone who can open the page can sign in or out, so keep it on loopback or behind your own authentication.
Smart-meter consumption (kWh): one day in 15-minute steps, or a week / month of daily totals.
| Name | Required | Description | Default |
|---|---|---|---|
| date | Yes | First day, yyyy-MM-dd. | |
| bpNumber | No | Business partner number; defaults to the signed-in customer's. | |
| meterCode | No | deviceCode from list_meters. | |
| contractId | No | Contract number; defaults to the first contract. | |
| resolution | No | day: that day in 15-minute steps; week / month: daily totals from that day. | |
| meterSerial | No | deviceNumber from list_meters; defaults to the first meter. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It usefully discloses the unit (kWh) and the output granularity per resolution, but says nothing about authentication requirements, defaulting behavior, coverage limits, or error conditions for an unannotated data-fetch tool.
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 well-formed sentence with the resource and the key variable (resolution) front-loaded. No padding, though for a 6-parameter tool it borders on under-specification rather than pure conciseness.
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 6-parameter read tool with no annotations and no output schema, the one-line description is the minimum viable: it conveys the resource and granularity but omits output shape, defaults, and any relationship to sibling tools like list_meters or get_last_meter_reading.
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 100% and the resolution enum is fully documented in the schema, so the description's restatement of 'day = 15-minute steps, week/month = daily totals' adds no meaning beyond it. All other parameters (bpNumber, meterCode, contractId, meterSerial) are left entirely to the schema.
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 resource (smart-meter consumption in kWh) and enumerates the three temporal granularities, which is more than a restatement of the name. It implies a historical time-series read, distinguishing it from get_last_meter_reading, though it never names that sibling.
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 explicit when-to-use guidance, no mention of prerequisites (auth, contract/meter selection) and no routing to alternatives such as get_last_meter_reading or list_meters. The agent must infer all of this from the schema.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The signed-in IEC customer: BP number, accounts, name and contact details.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden, yet it only hints at session context via 'signed-in'. It says nothing about required authentication state, what happens if the session is absent or expired (relevant given iec_login/iec_session_status siblings), or whether any data is cached or mutated. The safety profile is effectively undeclared.
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 compact sentence with no filler, and the key scoping qualifier ('signed-in') is front-loaded before the returned fields. Nothing can 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 no output schema, the description partially compensates by enumerating the returned fields (BP number, accounts, name, contact details). Its remaining gap is behavioral: no statement about the required signed-in session or failure behavior when unauthenticated. For a zero-arg read tool this is close to sufficient.
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 per the rubric the baseline is 4. Schema description coverage is 100%, and there is nothing for the description to clarify beyond confirming the tool is argument-free and scoped implicitly to the caller.
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 names the specific resource (the signed-in IEC customer) and enumerates its content (BP number, accounts, name, contact details), so an agent knows this is a profile lookup rather than a contract/invoice/meter lookup. The verb is only implied by the name 'get_customer', and it never explicitly says 'returns' or 'reads'. It is clear but does not explicitly contrast itself with siblings.
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 statement of when to use this tool versus list_contracts, list_meters, or the session tools. 'Signed-in' weakly implies a session prerequisite, but no precondition, alternative, or exclusion is stated. The agent must infer usage entirely from the tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The current bill summary of a contract.
| Name | Required | Description | Default |
|---|---|---|---|
| bpNumber | No | Business partner number; defaults to the signed-in customer's. | |
| contractId | No | Contract number; defaults to the first contract. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry behavioral disclosure, yet it does not mention read-only status, authentication requirements, error behavior, or what happens when no contract is available.
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 sentence with no filler; the resource is front-loaded. It is appropriately brief for a simple two-parameter tool, though it is arguably too terse to earn more than a 4.
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?
The tool has no output schema or annotations, so the description should clarify return format and sibling distinctions; instead it only restates the resource, leaving key selection context missing.
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 coverage is 100% and both parameters are optional with defaults documented in the schema; the description adds no format or selection semantics beyond the phrase 'of a contract'.
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 identifies the resource as a current bill summary scoped to a contract, but it omits a retrieval verb and does not differentiate from siblings like list_invoices or get_invoice_pdf.
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 guidance is given on when to use this tool versus list_invoices, get_invoice_pdf, or get_consumption; the agent must infer usage entirely from the tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Download one invoice as a PDF (base64).
| Name | Required | Description | Default |
|---|---|---|---|
| bpNumber | No | Business partner number; defaults to the signed-in customer's. | |
| contractId | No | Contract number; defaults to the first contract. | |
| invoiceNumber | Yes | documentID from list_invoices. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations, so the description carries the full burden. It does disclose the payload form (PDF, base64-encoded), which is genuinely useful since there is no output schema. It says nothing about auth requirements, error/failure behavior, or rate limits.
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. Efficient, though for a tool with no annotations and no output schema a touch more detail would have earned its place.
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?
The description covers the key return-format detail (base64 PDF) that the absent output schema would otherwise leave unknown. It is still thin on outcome/error behavior and on how the required invoiceNumber should be obtained, which matters given the sibling list tool.
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 100%, so all three parameters (including defaults for bpNumber and contractId, and the list_invoices provenance of invoiceNumber) are already documented. The description adds only the singular/invoice-scoping nuance, so baseline 3 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+resource+artifact: download one invoice as a PDF. Singular scope ('one invoice') is clear. It does not, however, distinguish itself from siblings like list_invoices (which the schema references but the prose does not), so no sibling differentiation.
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 prerequisites, and no mention of the natural alternative (list_invoices, which produces the invoiceNumber this tool needs). The agent must infer that it needs an already-known invoice identifier.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The last reading of each meter on a contract.
| Name | Required | Description | Default |
|---|---|---|---|
| bpNumber | No | Business partner number; defaults to the signed-in customer's. | |
| contractId | No | Contract number; defaults to the first contract. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It only describes the returned data and omits read-only nature, authentication needs, error behavior, and rate limits, leaving the agent to infer safety from the tool name.
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 wasted words. Appropriately terse for a simple read tool.
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?
The tool is simple and the schema documents its parameters well, but with no annotations and no output schema the description should at least state read-only behavior or usage context. It leaves the agent to infer when to call it versus siblings.
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 100% and both optional parameters are documented with defaults. The description adds no parameter details, so the baseline of 3 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?
The description states the resource and scope ('last reading of each meter on a contract') clearly, but uses a noun phrase with no verb and does not differentiate from siblings like list_meters or get_consumption.
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, alternatives, or prerequisites are given. Nothing tells the agent when to choose this tool over list_meters or get_consumption.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the link where the user signs in to IEC (ID number and one-time code are typed on that page, never in the chat). Returns the status when already signed in.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does real work: it discloses the security model (credentials typed on the page, never in chat) and the already-signed-in return behavior. It stops short of stating auth/permission requirements or whether calling it has side effects on an existing session.
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 tightly written sentences, front-loaded with the primary purpose and followed by the security constraint and edge-case behavior. No filler, though the parenthetical is dense.
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 zero-parameter tool with no output schema, the description covers purpose, the security-relevant interaction model, and the already-signed-in case. The main gap is not stating how the sign-in link should be presented to the user or its validity window.
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. The baseline of 4 applies, and the description appropriately avoids inventing parameter semantics.
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 ('Get the link where the user signs in to IEC') and clarifies the mechanics (ID and one-time code entered on that page, not in chat). It is clearly distinct from a plain 'log in' action, though it does not explicitly name siblings like iec_session_status.
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 implied: call this to obtain a sign-in link when the user is not authenticated, and it notes it 'Returns the status when already signed in.' However, it never explicitly routes between this tool, iec_session_status, and iec_logout, so the agent must infer the boundary.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Sign out of IEC here: forget the saved session.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It does disclose one meaningful trait — the saved session is forgotten, i.e. persisted state is cleared — but says nothing about idempotency, server-side vs local logout, or failure behavior when no session exists.
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 short sentence with the action front-loaded; nothing is wasted. The colon-mid-sentence phrasing ("here: forget the saved session") is slightly awkward but the key information lands first.
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 zero-parameter, no-return-value session-teardown tool, the description covers what an agent needs to select and call it. The remaining gap — whether logout is local-only or invalidates the server session — is minor for a tool of this complexity.
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 the baseline is 4. There is no argument surface for the description to explain, and it correctly avoids inventing one.
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+resource ("Sign out of IEC") that is unambiguous and naturally distinguished from the iec_login and iec_session_status siblings. It stops short of explicitly naming those siblings or the session boundary it operates on, so it clears the bar without full sibling differentiation.
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 when-to-use or when-not-to-use guidance, and no alternative is named. An agent can infer it should be called to terminate a session, but nothing in the text states prerequisites (e.g. whether an active session is required) or consequences of calling it twice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Whether this server is signed in to IEC, since when, until when, and the sign-in link when it is not.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations and no output schema, the description carries the full burden, and it does disclose the condition-dependent return content (the sign-in link only appears when the session is not active). The interrogative framing also makes the read-only nature evident. It stops short of stating explicitly that there are no side effects or whether the link expires.
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 that covers all four reported facts with no filler or repetition. 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?
For a zero-parameter status query with no output schema, the description supplies the return fields an agent needs (state, since, until, sign-in link). A brief pointer to iec_login for actually signing in would close the remaining gap.
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 for a parameterless tool.
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 names a specific resource (this server's IEC session) and enumerates exactly what is reported: signed-in state, start time, expiry, and the sign-in link when inactive. That is enough to tell it apart from the mutating siblings iec_login and iec_logout, though it never names an alternative explicitly.
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 when-to-use guidance, no prerequisites, and no named alternative. An agent must infer on its own that this should be called before iec_login to decide whether authentication is needed; the description neither states that flow nor excludes any case.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The customer's electricity contracts (one per address) with debt and due date.
| Name | Required | Description | Default |
|---|---|---|---|
| bpNumber | No | Business partner number; defaults to the signed-in customer's. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It does disclose a useful structural trait — 'one per address' — but says nothing about permissions, pagination, or whether an empty result is possible. For an unannotated read tool this leaves meaningful gaps.
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 tight sentence with the resource and its distinguishing scope front-loaded, and no filler. It is appropriately sized for a one-parameter list tool.
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 simple list tool with no output schema and no annotations, the description covers what the tool returns (contracts with debt and due date), which is the core need. It is adequate but omits usage context and behavioral constraints, so it is minimum-viable rather than complete.
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 100%, so bpNumber's meaning and its default to the signed-in customer are already documented in the schema. The description adds no parameter detail, so the baseline 3 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?
The description names the resource (electricity contracts), its scope (the customer's, one per address), and the key data it carries (debt, due date). This lets an agent distinguish it from list_invoices or list_meters. It stops short of an explicit verb like 'retrieve/list', but the noun phrase plus the tool name make the purpose unambiguous.
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 call this tool versus alternatives such as get_customer, list_invoices, or get_electric_bill, and no prerequisites or context of use are stated. The agent must infer usage entirely from the name and the returned fields.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
A contract's invoices: amounts, paid status, billing periods and consumption.
| Name | Required | Description | Default |
|---|---|---|---|
| bpNumber | No | Business partner number; defaults to the signed-in customer's. | |
| onlyOpen | No | Only unpaid invoices. | |
| contractId | No | Contract number; defaults to the first contract. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are supplied, so the description carries the full disclosure burden, yet it only enumerates returned data fields. It says nothing about whether this is a safe read, authorization requirements, pagination, result limits, or what happens when no contract exists beyond the schema's 'defaults to the first contract' note.
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 compact sentence with no filler, front-loaded on the resource. It is efficient, though the terseness shades into under-specification rather than being deliberately economical.
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 read-only list tool with no output schema, the description usefully enumerates the returned fields, which partially covers the missing return documentation. It still omits usage context, auth expectations, and result-size behavior, and with no annotations there is nothing else to fill those 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?
Schema description coverage is 100%, so all three parameters (bpNumber, onlyOpen, contractId) are already documented with defaults and meaning. The description adds no parameter-level detail beyond the schema, which is the expected baseline when the schema does the work.
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 names the resource and its payload (a contract's invoices with amounts, paid status, billing periods, consumption), so the agent can guess this is a listing/retrieval tool. However, it is a bare noun phrase with no verb and no explicit scope such as 'lists all invoices for a contract', and it does not distinguish itself from siblings like get_invoice_pdf or get_electric_bill beyond the field list.
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 when-to-use guidance, no mention of prerequisites (e.g., needing a signed-in customer or contract), and no routing to alternatives. The sibling get_invoice_pdf and get_electric_bill are never referenced, leaving the agent to infer which tool to pick.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The meters on a contract, with deviceNumber and deviceCode.
| Name | Required | Description | Default |
|---|---|---|---|
| contractId | No | Contract number; defaults to the first contract. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden, and it says nothing about permissions, result ordering, or whether the call is a safe read. The only behavioral scrap is that results carry deviceNumber and deviceCode, which is thin for a tool with zero 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?
A single short, front-loaded sentence with no waste. It is a noun phrase rather than a complete statement of action, which slightly weakens it but not enough to penalize heavily.
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 one-parameter read tool whose parameter is fully documented, this is minimally adequate. However, with no annotations and no output schema, the description should say more about what a meter record contains and how results are ordered or bounded; naming two fields alone leaves 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?
Schema description coverage is 100% and the single contractId parameter is fully documented in the schema, including its default. The description adds no syntax or format detail beyond that, so the baseline of 3 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 the resource ('the meters') and its scope ('on a contract'), plus the two identifying fields returned. The verb 'list' is only implied by the name, and nothing distinguishes it from siblings like get_last_meter_reading or get_consumption, so it falls short of a 5.
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 when-to-use guidance at all. With siblings such as get_last_meter_reading and get_consumption that also concern meters, an agent has no signal telling it when this enumeration tool is the right pick.
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.0get_consumptionget_customerget_electric_billget_invoice_pdfget_last_meter_readingiec_loginiec_logoutiec_session_statuslist_contractslist_invoiceslist_metersScored across 11 tools
Each tool targets a distinct resource or session action: auth trio (iec_login/iec_session_status/iec_logout), customer, contracts, bills, invoices, PDF, meters, readings, and consumption are clearly separated. The only mild proximity is get_electric_bill vs list_invoices, but the descriptions frame one as a current summary and the other as a per-period invoice list, which is enough to choose correctly.
The dominant pattern is a consistent verb_noun snake_case (get_customer, list_contracts, get_invoice_pdf, etc.), which reads predictably. The deviation is the iec_ prefix reserved for the three session/auth tools, a minor but noticeable inconsistency rather than a readability problem.
Eleven tools is well within the ideal range and each one maps to a concrete self-service need (auth, account lookup, contracts, billing, invoices, metering, consumption). Nothing feels redundant or padded; the surface is scoped to a single utility-customer domain.
Coverage spans the full read lifecycle of an electricity account plus session management and an invoice download, so common agent workflows have no dead ends. Minor gaps remain around write/action operations (payments, contract or tariff detail beyond the summary) that an agent might expect for a customer portal.
Browser MCP for logged-in tasks. Uses your Chrome — credentials stay local. Zero-token replay.
Remote streamable-HTTP MCP server running on a single Cloudflare Worker. Your assistant gets live Airbnb, Amazon, Booking.com, Google Flights, Maps and Reddit data, social search on X, Instagram and TikTok, the Meta Ad Library, and image/video generation without any keys. Connect your own accounts to let it send WhatsApp or Telegram messages, work an IMAP inbox, manage Meta Ads campaigns and publish to X and LinkedIn. OAuth 2.1 with PKCE; stored credentials are AES-256-GCM encrypted.
Let Claude or ChatGPT search, read and send your WhatsApp messages over MCP. OAuth sign-in.
Brazilian Open Finance MCP — 30+ banks (Itaú, Nubank, etc.) to Claude/Cursor. Read-only.
