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

With no annotations, the description carries the full burden and does most of it well: it discloses that the server only returns text and never connects to a device (no side effects), that generated code performs real writes with documented function codes, and that conditional steps sit behind default-off flags. The residual gap is the exact return shape (a single code string?), which is not stated.

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 purpose, then escalates to the safety warning and the no-connection guarantee — good ordering. The opening sentence is long and the library enumeration is slightly verbose, but each element (preconditions, write sequence, confirmation reads, keep-alive) contributes to the agent's mental model.

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 code-generation tool with no output schema and 5 fully documented parameters, the description covers everything an agent needs: what is generated, in which languages, what the template does at runtime, the default-off behavior of optional steps, and the absence of server-side device contact. Only the literal response envelope is unstated, which 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 host, unit_id, language, recipe_id, and transport are already fully documented in the schema, including the TCP-only const and the recipe_id example. The description's library mapping per language adds only marginal value beyond the enum. Baseline 3 applies when the schema does the heavy lifting.

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 deliverable: generate a client program template for a recipe, naming the exact libraries produced per target language. It is clearly distinct from the read/discovery siblings (list_recipes, get_recipe, validate_write) that surround it. An agent knows immediately what comes back and in what form.

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 code writes to a live inverter when run: review it first' gives a concrete condition for handling the output cautiously, and the recipe_id constraint (from list_recipes) is stated in the schema. It stops short of explicitly routing against siblings such as validate_write or get_recipe, so the alternative-choice guidance is inferred rather than stated.

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?

With no annotations, the description carries the burden and does reasonable work: it declares the read-only, documentation-only nature and discloses a non-obvious fallback behavior (returning the heading list when the heading is not found). It does not mention permissions or error behavior, which keeps it below 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?

Three short sentences, zero filler, with the return format and extraction boundary stated first and the fallback and scope notes following. Every sentence carries information an agent needs.

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 two-parameter read tool with no output schema, the description covers the return format (Markdown), the extraction boundary, the failure fallback, and the read-only scope. What remains unstated, such as the exact shape of the returned heading list or whether matching is case-insensitive, 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 description coverage is 100%, with enum values and the section-matching hint already documented, so the baseline is 3. The description's boundary definition ('heading to the next heading of the same level') adds a little meaning to how 'section' is interpreted but does not clarify the parameters themselves.

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 (return one documentation section as Markdown) and defines the exact extraction boundary: from the heading to the next heading of the same level. That precision, plus the 'documentation only' scoping, separates it cleanly from the register/SunSpec sibling tools.

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 establishes the usage context clearly by flagging 'Documentation only; never touches a device', which routes the agent away from device-facing siblings, and it documents the fallback path of returning the heading list when a section is not found. It does not name a specific alternative tool, so it stops short of a 5.

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?

With no annotations, the description does real work by declaring 'Documentation only; never touches a device' and by explaining that values are raw register values with negatives as 16-bit two's complement — both genuinely useful behavioral facts. It stops short of stating what happens when the task string matches nothing (fuzzy match? error?) or whether lookups are case-sensitive, which matters given the free-text parameter.

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?

It is a single dense sentence fragment with no leading verb, front-loaded with the returned structure rather than the action. Every clause is informative — nothing is padding — but the list-of-fields format is harder to scan than a short lead sentence followed by detail.

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 one parameter and no output schema, the description must stand in for the return shape, and it does so thoroughly: preconditions, steps with op/address/function code/value/check, confirmation reads, failure/recovery, notes, and provenance. Only the free-text matching behavior of the task parameter is left unexplained.

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 the schema already gives both examples ('native.ems_session_start' and 'forced charge sunspec'), so the description adds nothing parameter-specific. Baseline 3 applies since the schema carries the 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 enumerates what a recipe contains (preconditions, ordered steps, confirmation reads, failure/recovery, doc sections), so an agent knows exactly what resource it gets back, and the closing clause clarifies it is documentation, not device interaction. It never states a verb or explicitly contrasts with list_recipes, so the read-vs-browse distinction must be inferred from the name alone.

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: the schema shows it accepts an id or a natural-language task description, which suggests 'look up the procedure you need.' There is no explicit when-to-use guidance, no mention of list_recipes for browsing, and no pointer to validate_write or get_register for the follow-up actions the recipe describes.

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?

With no annotations present, the description carries the full load and does so well on the critical point: 'Documentation only; never touches a device' is an unambiguous no-side-effect guarantee. It also discloses the substance of the payload (write_function 0x06 vs 0x06/0x10, persistence classes, confirm_by registers), though it says nothing about behavior when an address is invalid or ambiguous.

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 purpose, then a dense but purposeful field inventory, closing with the safety constraint. The long middle clause is verbose but every listed field answers 'what will I get back' for a tool with no output schema, so little 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?

No output schema exists, so the description must describe returns — and it does so thoroughly, covering both plain registers and SunSpec addresses. The gaps are behavioral rather than informational: no guidance on invalid/unknown addresses or on routing to 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% and the address parameter already documents all three accepted forms (numeric, native name, SunSpec point), so the description adds nothing parameter-specific. Baseline 3 applies since 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?

States a specific verb and resource ('Full documentation of one register') and immediately enumerates the returned documentation fields, so an agent knows exactly what kind of payload to expect. It does not explicitly name search_registers or get_sunspec_point as the alternatives, so differentiation from siblings is only implied by the singular 'one register' framing.

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 closing line 'Documentation only; never touches a device' hints at when this is appropriate (pre-write inspection), but there is no explicit guidance on when to pick this over search_registers for lookup or get_sunspec_point for SunSpec details. Usage must be inferred entirely from the field enumeration.

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?

No annotations are supplied, so the description carries the full behavioral burden. It does well on the read-only point ('never touches a device') and discloses the returned attribute set, but says nothing about failure modes when a model/point combination is unsupported, whether 'implemented'/'writable' are device-derived or static, or where the 'device notes' come from — meaningful gaps for a no-annotation 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 dense sentence with the resource front-loaded and the read-only guarantee placed at the end as a qualifier. The long parenthetical field list earns its place because there is no output schema, though it reads as a run-on enumeration rather than a structured list.

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 must describe the payload, and it does so item by item, including nested sf_address/sf_value and the write_kind taxonomy. Missing only error/edge behavior and any pointer to which sibling supplies the surrounding model context (list_sunspec_models).

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%, with both 'model' and 'point' documented including the model enumeration and module[2].DCW syntax, so the schema already does this work. The description adds nothing about parameter behavior (e.g. what happens for an unsupported model or an ambiguous point name), leaving it at the baseline.

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?

Specific verb implied (retrieve documentation for one SunSpec point) plus a precise resource, and the description enumerates exactly what comes back: layout fields plus device object fields (address, offset, implemented, writable, write_range, write_kind, sf_address/sf_value). It separates itself from device-reading siblings only indirectly via 'Documentation only; never touches a device' rather than naming get_register or search_registers.

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 'Documentation only; never touches a device' implies the use case (look up a point's spec/semantics before acting) and rules out live device reads, but there is no explicit when-to-use statement and no sibling named as an alternative, even though get_register and search_registers are obvious overlapping candidates.

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?

With no annotations, the description carries the full disclosure burden and does state the critical trait: it is read-only documentation that never touches a device. It does not address pagination or whether the enumeration is exhaustive, but the essential safety profile is explicit.

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 field list and the docs-only disclaimer are front-loaded and earn their place. However, roughly half the text enumerates twelve specific recipe names that the tool itself returns, duplicating output the agent will receive anyway.

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-output-schema listing tool, the description covers subject matter, return fields, and safety sufficiently. Minor gaps, such as result ordering or volume, are unlikely to affect a correct invocation.

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. The description correctly implies no input is required and instead spends its words on output shape, which is the right allocation here.

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 concrete verb+resource ("List the closed-loop control recipes") and names the returned fields (id, title, interface, summary), so an agent knows exactly what comes back. It never names get_recipe or explains the list-vs-single relationship, so sibling differentiation relies on the caller noticing the plural name.

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?

"Documentation only; never touches a device" gives useful context on when this is safe to call, but there is no explicit routing guidance such as "use this to discover recipe ids, then call get_recipe for details." The usage pattern must be inferred from the plural name and the field list.

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?

With no annotations present the description carries the full burden, and it does so well: it explicitly says the tool never touches a device (read-only, offline reference) and it discloses the content and conventions of the payload, including word order, scale factors and not-implemented value handling. It stops short of saying whether the chain is paginated or how the response is formatted.

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?

One dense sentence that front-loads what is listed and closes with the key safety fact. The middle enumeration of conventions is list-heavy but every item tells the agent something it would otherwise have to discover, so little 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?

No output schema and no annotations exist, so the description must stand alone, and it covers scope, contents and side-effect freedom. Remaining gaps are minor for a static reference tool: nothing on response shape or on how the chain is ordered/paginated.

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. The description correctly implies a single unfiltered dump of the model chain.

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 (list SunSpec models) and enumerates the content returned: base address 40000, model IDs, lengths, point counts, writable points, END marker and transport conventions. It does not explicitly contrast with near siblings such as get_sunspec_point or get_doc_section, so an agent must infer the boundary, but the object of the tool is 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?

There is no when-to-use or when-not-to-use guidance and no named alternative. 'Documentation only; never touches a device' describes the safety profile rather than telling the agent which situation selects this tool over get_sunspec_point or get_doc_section.

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?

With no annotations, the description carries the load and does well: it discloses the return shape at field level ('address, name or SunSpec point, type, unit/scale or sf, access') and explicitly states the tool never contacts a device, which is the key safety fact. It stops short of saying what happens with truncation/limit defaults or whether results are ranked, which is the remaining behavioral gap.

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?

Three short sentences, front-loaded with what is searched and followed immediately by the shape of the results and the escape hatch to get_register. No filler or restated title.

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 three-parameter search tool with no output schema and no annotations, the description supplies the result-entry fields, the documentation-only guarantee, and the escalation path to the detail tool. Only mild gaps remain (no mention of the default limit of 20 or result ordering), which are partially covered by 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; the description adds value by spelling out that 'native' means the EMS map and 'sunspec' the SunSpec map, clarifying the intent of the interface parameter beyond its bare enum. It says nothing extra about limit or query syntax, but the schema already covers those with examples.

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 ('search the documented registers') and names the exact scope ('native EMS map and SunSpec map' of the Wattsonic MATIC inverter). It also implicitly distinguishes itself from the sibling get_register by describing its results as 'compact entries', so an agent can tell search from fetch 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?

Explicitly routes: 'Use get_register for the full record (value list, range, write function, effective conditions, read-back registers, persistence)' — that is a named alternative plus the condition that selects it. 'Documentation only; never touches a device' further tells the agent this is off-device lookup, not a live read.

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?

With no annotations, the description carries the full burden and does so: it discloses that nothing is written, that no device connection occurs, the specific rule families applied (access, range, scale, single-register, SunSpec range, gates/vetoes, side effects, readback), and the three possible verdicts plus reasons. Reversibility and safety are fully implicit in the read-only framing.

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 critical fact (validation without writing) is front-loaded, and the closing sentences are tight. The middle sentence is a long parenthetical enumeration that is dense but each item adds distinct information, so little 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?

For a 4-parameter tool with full schema coverage, no annotations and no output schema, the description supplies the return contract (ok / ok_with_warnings / reject with reasons) and the behavioral guarantees an agent needs before calling it. Nothing material 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; the description adds real meaning on top by revealing that function-code choice is constrained per address range ('0x06 only for 11300-11303, 11320-11324, 11330, 11057, 11254') and that value scaling and side effects (e.g. 0x5A5A on 12026) are interpreted against the register, not applied blindly.

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 opening clause states a specific verb and resource ('Check a planned write against the documentation') and immediately scopes it with 'WITHOUT writing anything', which separates it from the sibling mutation/lookup tools. The enumerated checks that follow confirm exactly what class of validation is performed.

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 establishes the context of use clearly: a pre-write dry-run check, with the caveat 'Guidance only; this server never connects to a device and never writes registers', which tells an agent this is not a substitute for execution. It stops short of naming alternatives (e.g. get_register for plain lookup) or stating explicit when-not-to-use conditions.

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