PlanElec Calculators

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint and openWorldHint, so the safety profile needs no restating; the description instead adds real behavioural context: the outputs are planning values rather than a manufacturer guarantee, several physical/safety checks are explicitly not performed, and the response contains a shareable link opening the calculation on planelec.be. The remaining gap is that it doesn't describe accuracy tolerances or what happens when explicit fields conflict with a preset (the schema, not the description, carries the override rule).

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 purpose and the required inputs are front-loaded, followed by the optional parameter list and then the scope caveats, which is a sensible order and wastes little. The middle sentence is a dense enumeration that partially restates the schema, so it is slightly longer than strictly necessary, but 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 14-parameter calculation tool with an output schema present, the description covers the essential contract: inputs and alternatives (preset vs. datasheet), optional planning parameters, the limits of the advice, and the fact that a shareable result link is returned. Nothing an agent needs in order to call it correctly is 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%, so the baseline is 3, but the description adds genuine framing by grouping the inputs into a required core (length, preset-or-datasheet values) and an optional planning tier (cut unit, max length per feed, feeds, reserve, cable length/material/cross-section, voltage-drop limit), which helps an agent decide which fields matter. It adds no numeric defaults or units beyond what the schema states.

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 opens with a precise verb plus an enumeration of outputs (power, current total and per channel, feed points, PSU size, feed cable) for a well-defined resource: analogue LED strips at 5/12/24/48 V DC across the listed colour modes. This is unmistakably distinct from siblings such as size_cable_arei or check_inverter_c10_26, so an agent can route to it without opening the schema.

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 states the minimum invocation contract clearly (length in metres plus either a preset or datasheet values) and flags which inputs are optional, which is the practical when-to-use guidance for this tool. It does not name an alternative tool or explicitly say when not to use it, but it does bound the use case by declaring that current-carrying capacity, heat and AREI/RGIE rules are out of scope.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare the operation as read-only, idempotent and open-world, so the safety profile is covered. The description adds useful behavioral detail: the outcome values, matching device data, alternatives, and importantly the caveat that the separate datasheet object is not checked by Synergrid and is not part of the approval.

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 front-loaded with the core purpose and then layers in return behavior, a caveat, and an example. It is generally well structured and avoids obvious waste, though it includes return-value detail that the output schema already covers.

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 four-parameter lookup tool with an output schema and read-only annotations, the description supplies the key context an agent needs: what is checked, what is returned, and the important datasheet limitation. Its main omission is explicit routing guidance against sibling 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 100%, so the input schema already documents all four parameters. The description adds a useful example of the required query format, but it does not meaningfully expand on the semantics of locale, phases or smaxVa beyond what the schema provides.

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: checking whether a PV inverter, battery inverter or PGU is on the Synergrid C10/26 homologation list. It is very clear what the tool does, but it does not explicitly differentiate itself from siblings such as suggest_inverter_c10_26 or get_inverter_datasheet.

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 gives an implied usage context and a concrete search example ("Huawei SUN2000-10KTL"), which helps an agent call it correctly. However, it does not state when to use this tool versus siblings like suggest_inverter_c10_26, nor does it give explicit exclusions or prerequisites.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover safety and idempotency, and the description adds genuinely new behavioral context: the values are manufacturer statements, not Synergrid approval, and each value carries a status (verified vs. secondary) plus provenance (source URL and page, date last verified). That caveat is exactly the kind of trust/interpretation guidance annotations cannot convey; only the output format is left implicit, which the output schema covers.

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?

Purpose and the critical approval caveat are front-loaded, which is good, but the long middle enumeration of return fields is partly redundant with the existing output schema and dilutes the two sentences that actually matter. It reads as a single dense block rather than a structured note.

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 lookup with an output schema and full schema coverage, the description supplies the missing interpretation layer: data provenance, verification status, and the boundary against the approval tool. What remains unstated — behavior with no lookup key given the zero required parameters — is minor.

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%, so brand, model, reference and locale are all documented in the schema, including the "alternative to brand and model" relationship. The description's lookup sentence largely restates that, and it adds nothing about locale behavior or what happens when neither lookup mode is supplied (zero required parameters).

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 opens with a specific verb and resource ("Returns manufacturer datasheet data for an inverter") and names the exact source (Synergrid C10/26 list), then enumerates the concrete fields returned. An agent can distinguish this immediately from the approval-checking 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?

It explicitly routes approval questions to check_inverter_c10_26 and states the two lookup modes (Synergrid reference vs. brand+model). It does not mention the other inverter sibling suggest_inverter_c10_26, so the routing picture is clear but not exhaustive.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly, idempotent and closed-world, so the description only needs to add context. It does: it discloses what is returned (edition, change notices of amending decrees, sub-article titles, PlanElec link) and the non-obvious language fallback where English resolves to the German text. It says nothing about behavior for a missing or invalid article number, which keeps it from a 5.

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?

Front-loaded with the core action, then two short follow-up sentences on citation and sibling routing. The opening sentence is dense but each clause (scope, formats, language, returned fields) carries information an agent would otherwise have to guess; no filler.

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?

Given an output schema, full annotation coverage and 100% schema description coverage, the description supplies everything else an agent needs: scope limitation to Book 1, supported languages and fallback, edition behavior, and the discovery path via search_regelwerk.

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%, so the schema carries the baseline. The description still adds meaning beyond it: accepted article-number shapes including a prefixed form like "AREI 7.1.4.3", and the language-resolution rule that English falls back to German text, which the locale enum alone does not convey.

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: returns the text of one article of Book 1 of the Belgian AREI/RGIE, identified by its number. It gives concrete number formats and names the sibling search tool, so an agent can distinguish it from search_regelwerk immediately.

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?

Explicitly routes discovery to the alternative: "Use search_regelwerk to find the number." It also gives a downstream usage rule — cite the article number and edition when passing content on — which is exactly the when/how guidance an agent needs.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The annotations already cover the safety profile (readOnly, idempotent, openWorld), and the description adds genuinely new behavioral facts: results are capped at five, each hit carries title/summary/category/link, and the full article body is deliberately not returned. That last point is exactly the kind of boundary an agent needs in order to escalate to a follow-up 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?

Two dense sentences, front-loaded with what is searched and backed immediately by the return contract and its limitation. Nothing is redundant with the title or the schema, and the closing clause about article text is well placed.

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, full annotation coverage and 100% schema descriptions, the description only needs to supply scope and boundaries — which it does, including the five-result cap and the absence of article text. Minor gaps remain: no empty-result behavior and no pointer to which sibling retrieves the full article.

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%, so baseline is 3; the description does add meaning by tying results to the visitor's current language, which explains why locale matters and how titles/links are localized. It still leaves the query/locale interplay (e.g. does a locale override translate keyword matching?) to the schema, and the description's 'visitor's current language' is slightly looser than the schema's 'defaults to the server setting'.

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 and resource (searches PlanElec help-center guides) and enumerates the covered topics — getting started, automatic planning, exports, AREI self-check, floor plan import, symbols and circuits — which makes the content domain unambiguous. It stops short of naming a sibling, so an agent must infer on its own how this differs from search_regelwerk or get_regelwerk_article.

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?

Use is only implied: it is evidently the tool for help-center/how-to questions, and the topic list hints at its scope. There is no explicit when-to-use clause, no statement about when to prefer search_regelwerk or get_regelwerk_article, and no note on what to do when nothing matches.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover the safety profile (readOnly, idempotent, closed-world), so the bar is lower, yet the description still adds real behavioural context: results are capped at ten articles, each carries number, title, excerpt, the edition in force today, and a PlanElec reader link, and the full text is withheld. It does not explain ranking or what happens on zero results, which keeps it from a 5.

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 core purpose and the sibling routing are front-loaded, and each sentence carries information (language handling, return shape, alternative tool, query forms, disclaimer). The language clause is densely packed but not wasteful, so it reads efficiently despite its length.

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 four-parameter read-only search with full schema coverage and an output schema, an agent has everything needed: which corpus, which languages, result cap, what fields come back, where to go for full text, and the non-official status of results. Nothing required to invoke it correctly is 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%, which sets a baseline of 3, and the description goes beyond it by clarifying the query parameter accepts either keywords or a dotted article number and by disclosing that locale 'en' resolves to the German source text. It adds no guidance on limit or version semantics beyond what the schema descriptions already state.

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 (searches Book 1 of the Belgian AREI/RGIE electrical regulations) and constrains scope to a named corpus and language behaviour. It also distinguishes itself from the sibling get_regelwerk_article by noting the full article text is not returned, so an agent can pick the right tool without opening either schema.

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 explicitly names the alternative (get_regelwerk_article) and the condition that selects it (when the full article text is needed), and it explains the two query modes (keywords vs. article number such as 4.2.4.3). The added caveat that results are planning aids rather than an official inspection further frames appropriate use.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly/idempotent/openWorld, so the safety profile is covered. The description adds genuine value beyond them: it discloses that the response contains a shareable planelec.be link reproducing the calculation, and that unset fields silently assume socket-circuit defaults rather than erroring. No limits, failure modes, or jurisdiction caveats (beyond 'Belgian AREI/RGIE') are mentioned.

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. The first sentence front-loads what the tool computes and under which standard; the second tells the caller what to supply and what comes back. 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 13-parameter tool with zero required fields and an output schema, the description does the essential work: it tells the caller the minimal viable input and that an output link is returned. The gap is the undocumented 'check' mode branch, which changes what the tool returns and is only discoverable in the schema.

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%, so the baseline is 3, but the description adds practical meaning: it identifies the four inputs that actually drive a useful result and states that load may be expressed in A, W, kW or kVA, signalling that unit conversion is handled server-side. It does not clarify the mode/selectedCrossSectionMm2 interplay or the three-phase/3x-network constraint.

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?

Names a specific verb and resource ('Calculates the required copper or aluminium cable cross-section for a residential circuit under the Belgian AREI/RGIE') and enumerates the outputs (design current, voltage drop per cross-section, protection check, recommended cross-section). This is trivially distinguishable from the sibling tools (LED strip, inverter, regelwerk lookups).

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?

Conveys the operating context (residential circuit, Belgian AREI) and tells the caller the minimal input set (load, length, network, breaker rating) while other fields fall back to socket-circuit defaults. However, it never explains the 'check' vs 'plan' modes or when to supply selectedCrossSectionMm2 — the most consequential usage decision — leaving that entirely to the schema.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the safety profile is covered. The description adds non-obvious behavioral detail beyond that: the response changes shape depending on whether the input resolves to a brand (returns brands with device counts) or a recognized brand (returns its homologated models), which an agent could not infer from annotations alone.

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, front-loaded with the resource and the mode-switching behavior, followed by the routing advice. Every clause carries information; nothing is redundant.

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 and 100% parameter coverage, the description only needs to convey the tool's role and the dual response mode, which it does. The one small gap is not stating that matching is prefix/substring-based or how ambiguity with many brand matches should be handled, but this is minor for a typeahead.

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%, so both the 'query' partial-name semantics and the 'locale' enum are fully documented in the schema. The description reinforces the partial-name resolution concept but adds no format or syntax detail beyond what the schema already provides, making baseline 3 correct.

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 verb and resource ('Typeahead for the Synergrid C10/26 list') and spells out both return modes — matching brands with device counts, or a recognized brand's homologated models. That is enough to distinguish it from check_inverter_c10_26 without opening either schema.

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 an explicit precondition and ordering: 'Use this to resolve an ambiguous device name before calling check_inverter_c10_26,' naming the sibling it feeds into. It stops short of saying when not to use it (e.g., when the exact brand/model is already known), so it is clear context rather than full 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.