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

With no annotations, the description carries the full burden of disclosing behavioral traits. It does not state whether the tool is read-only, requires authentication, or has any side effects. The only behavior described is running checks and returning results.

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 that conveys the core purpose without waste. However, it could be slightly more structured by stating the output format or mentioning the parameter.

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 the output schema exists but is not provided, the description is incomplete. It does not explain what 'every check' entails, the structure of the report summary, or how to interpret findings. The presence of 12 sibling tools suggests the need for clearer context.

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 input schema has 0% description coverage, and the description does not mention the only parameter, name_regex. The description adds no meaning 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 clearly states the tool runs every check and returns the report summary plus all findings. This distinguishes it from sibling tools like check_dpt, which are individual checks.

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 on when to use this tool versus alternatives. The description does not explain scenarios where running all checks is appropriate, nor does it mention that individual sibling checks exist for specific 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?

With no annotations provided, the description carries the full burden. It clearly states the tool is read-only, does not touch ETS/bus, reads directly from the .knxproj part, and cannot handle password-protected projects. It also explains the grouping logic and output categories. It does not disclose potential performance characteristics or failure modes beyond the password limitation, but the core behavioral traits are well covered.

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 dense but well-structured: it opens with the core purpose, then explains the data source, grouping logic, output categories, and constraints. Every sentence adds value, though the final sentence about password protection could be integrated more tightly. It is longer than the ideal but earns its length by covering multiple behavioral aspects.

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 the tool's complexity (grouping, outlier detection, two output categories) and the absence of annotations, the description is quite complete. It explains the input requirements, the read-only nature, the output structure, and a key limitation. It does not explicitly document the 'min_group' parameter or edge cases like what happens when no outliers are found, but the output schema likely covers return values. Overall, an agent has enough to invoke it correctly.

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 0%, so the description must compensate. It explains the 'path' parameter implicitly by requiring a real .knxproj path and noting password-protected projects cannot be read. It does not explicitly explain 'password' or 'min_group' semantics, but the description's mention of 'strong majority' and 'balanced 2+ variants' hints at grouping thresholds. The output schema likely clarifies the return structure, and the description adds meaningful context about what the tool does with the path.

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 ('Find'), a precise resource (device parameter settings in a .knxproj project), and a clear outcome (identifying the odd device among identical siblings). It also distinguishes itself from siblings by focusing on parameter settings rather than naming, topology, or security, and it names the two output categories (clear_outliers, split_configs).

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 explicitly says when to use this tool: to find devices whose ETS parameter settings differ from identical siblings. It also gives exclusions: a password-protected/encrypted project cannot be read, and it is read-only with no ETS/bus involvement. This is strong guidance for an agent deciding between this and sibling tools like check_naming or check_topology.

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 full burden. It only states the detection function but does not disclose whether the tool has side effects, requires authentication, or is read-only. The term 'detect' implies read-only, but this is not 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 description is a single sentence, front-loaded with the verb 'Detect'. It is concise, though it could include more context without becoming verbose.

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 no parameters and an output schema, the description is minimal. It does not explain what DPTs are or in what context the tool operates (e.g., a loaded project). An agent may need to infer the scope from sibling tool names.

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 has zero parameters, so the input schema is fully covered. Description adds no parameter info, but none is needed.

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 tool detects missing, inconsistent, or mismatched DPTs, which is a specific verb and resource. It distinguishes from sibling tools like check_missing_status and check_naming, but 'DPTs' is not explicitly defined, mildly affecting clarity.

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 provided on when to use this tool versus alternatives such as check_missing_status or check_naming. The agent has no context for selection.

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 provided, so the description must disclose behavioral traits. It mentions 'check' and 'suggest', implying a read-only operation, but does not explicitly state it does not modify data, require permissions, or have side effects. The description is adequate but lacks full transparency.

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 a single, well-structured sentence of about 20 words. It front-loads the action and domain immediately, includes specific DPTs and components, and contains no redundant or unnecessary words.

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 the tool's simplicity (0 parameters, output schema exists), the description is fairly complete. It explains what the tool does and what it suggests. However, it does not mention prerequisites (e.g., a loaded project) or the output format, though the latter is presumably covered by the output 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?

The tool has zero parameters, so the description does not need to explain parameter behavior. With 100% schema coverage (none), the baseline is 4. The description adds no parameter info, which is appropriate given the lack of 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 clearly states the tool's action: 'check the metering/energy domain' and 'suggest a per-circuit / PV / battery / EVSE structure for the HA energy dashboard.' It specifies the energy DPTs (13.x / 14.056) and distinguishes itself from sibling tools like check_dpt and check_matter by focusing on energy dashboard structure.

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?

While the purpose implies the tool is for energy dashboard setup, there is no explicit guidance on when to use it versus alternatives or when not to use it. Users can infer its applicability from the domain focus, but clearer exclusions or prerequisites would improve this dimension.

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?

Without annotations, the description should disclose behavioral traits. It describes the tool as a 'lint', implying a read-only analysis, but does not specify whether it modifies state, requires specific permissions, or how results are presented. The existence of an output schema helps but the description itself lacks behavioral context.

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 a single, well-crafted sentence that conveys the core purpose efficiently. Every word earns its place; no redundancy or fluff.

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 no parameters and an output schema present, the description is mostly complete, but it does not explain what the output represents or provide any examples of checks performed. For a lint tool with zero parameters, it could be more thorough in describing what 'Matter-readiness' entails.

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?

There are no parameters, so the input schema trivially covers everything. The description does not need to add parameter information, and the baseline score of 4 is appropriate.

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 clearly states the tool performs a lint check for Matter-readiness, specifying it checks which controllable functions round-trip to a Matter cluster. This distinguishes it from sibling tools like check_dpt or check_energy, though it could be more explicit about what 'controllable functions' refers to.

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 implies usage when assessing Matter compatibility but provides no explicit guidance on when to use this tool versus alternatives like check_dpt or check_naming. No exclusions or alternative references are given.

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 must disclose behavioral traits, but it only states what the tool detects. It does not mention whether the tool is read-only, whether it has side effects, or what the output format looks like (though an output schema exists). The description is insufficiently transparent.

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 a single concise sentence that conveys the core purpose without unnecessary words. It is well front-loaded and efficient.

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 the lack of annotations and a simple input schema, the description provides a basic understanding. However, it does not explain domain-specific terms ('GA', 'controllable', 'status/feedback counterpart'), and with an output schema present, more detail on the return value would improve completeness.

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 input schema has zero parameters, and schema description coverage is 100% (vacuous). The description adds meaning by specifying the detection criterion (controllable GAs missing status/feedback), which helps understand the tool's purpose without needing parameter details.

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 clearly states the tool detects controllable GAs lacking a status/feedback counterpart. The verb 'detect' and the resource 'controllable GAs' are specific. However, it does not explain what 'GA' stands for, which may reduce clarity for agents unfamiliar with the domain.

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 provided on when to use this tool versus alternatives like 'analyze_all' or 'check_naming'. There are no preconditions, examples, or notes on when to use or avoid this tool.

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 full burden for behavioral disclosure. It indicates a read-only validation, but does not explicitly state that the tool does not modify state, nor does it disclose any side effects, permissions needed, or output format. The minimal description fails to provide transparency beyond the implied non-destructive nature.

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 a single sentence, which is concise, but it lacks structure and does not front-load critical information. It earns its place but could be expanded with minimal additional sentences to improve clarity without sacrificing 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?

Given the existence of an output schema and one optional parameter, the description is insufficient. It does not explain return values, error conditions, or typical use cases. The sibling tools suggest a validation domain, but the description does not leverage that context to make the tool's role clearer.

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 0%, and the description does not explain the sole parameter 'name_regex'. The agent has no clue what regex pattern to provide, its purpose, or format. This missing semantic information severely hampers correct usage.

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 specifies a verb ('Validate') and objects ('naming conventions and 3-level structure'), making the tool's purpose clear. However, it lacks specificity about what constitutes naming conventions and 3-level structure, and does not distinguish it from sibling validation tools like check_dpt.

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 provided on when to use this tool versus alternatives. Sibling tools exist (e.g., check_dpt, check_missing_status) but the description does not mention any context, prerequisites, or exclusions, leaving the agent without decision criteria.

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. It explicitly states 'Report-only', which is a critical behavioral trait. It also discloses what gets flagged (GAs with domain mismatches, naming mismatches) and how the example profile is seeded (only mains that exist in the project are written). This covers the key side effects and constraints well, though it doesn't detail return format (but output schema 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?

The description is moderately long but every sentence carries meaningful information. It front-loads the core purpose and then details parameters and side effects. It could be slightly more concise, but the structure is logical and the emphasis on key constraints (report-only, seeding) is effective.

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 the tool has an output schema and two optional parameters, the description covers the essential behavior: what it validates, how to customize via profile_path, and how to generate an example. It explains the seeding nuance and the report-only nature. It doesn't elaborate on error handling or performance, but these are minor given the output schema and the tool's relative simplicity.

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 0%, so the description must fully explain parameters. It does: profile_path is described as a YAML profile path with an omission behavior (infer from project), and write_example_to is described as dropping a commented example profile seeded from the project's main groups. This adds substantial meaning beyond the bare 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?

The description clearly states a specific verb ('Validate') and resource ('loaded project against a Project Policy Profile'), and explicitly distinguishes it from a generic standard by emphasizing 'your agreed rules'. It also names the exact checks performed (main-group taxonomy, naming regex, exemptions), making it distinct from siblings like check_naming and check_secure.

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 clear context on when to use the tool: when you have an agreed policy profile. It explains the optional profile_path behavior (omit to infer from project) and the write_example_to use case. It doesn't explicitly name alternative tools, but the purpose is specific enough that an agent can infer when not to use it. It lacks explicit 'use X instead' guidance, so not 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 clearly states the tool is report-only and never touches key material, providing key behavioral transparency. However, it does not disclose other traits like performance or 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?

The description is three sentences with no wasted words, front-loaded with the main purpose, and efficiently covers the tool's actions and safety.

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 zero parameters and an output schema (implied by 'report-only'), the description sufficiently describes the output: counts, flags, and checklist. No 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?

There are zero parameters and 100% schema coverage, so the description need not add parameter info. Baseline is 4, and no additional detail is necessary.

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 uses a specific verb ('summarise') and resource ('KNX Data Secure posture') and clearly distinguishes from sibling tools like analyze_all or check_dpt by focusing on security posture and keyring workflow.

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 explains what the tool does but does not explicitly state when to use it versus alternatives or provide exclusions. Usage is implied for security assessments.

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 provided, the description carries the full burden of behavioral disclosure. It describes what it checks and flags (line limits, addresses, couplers), which is informative. However, it does not explicitly state whether the tool is read-only, whether it modifies the project, or what the output structure looks like. Since an output schema exists, the return format is covered, but the side-effect profile is not disclosed. The description adds value beyond the schema by detailing the specific validity checks, but stops short of full transparency.

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 two sentences: the first states the tool's purpose and reference to the KNX Handbook, the second lists the specific checks performed. It is front-loaded with the core action and resource, and every sentence adds essential information. There is no redundancy or padding.

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 check tool with an output schema, the description is complete. It clearly states what the tool does and what conditions it flags, which is all an agent needs to decide when to invoke it. The presence of an output schema covers return-value details. No prerequisites or additional context appear necessary, given the sibling tools like load_project imply a project is already loaded.

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 input schema is an empty object with zero parameters, so there is nothing to explain. The baseline for zero parameters is 4, and the description appropriately does not attempt to describe non-existent parameters. The tool takes no arguments, so parameter semantics are trivially satisfied.

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 uses a specific verb 'Check' with a clear resource: 'topology capacity and individual-address validity'. It enumerates exactly what it flags (line limits, invalid/duplicate addresses, missing coupler), which distinguishes it from sibling check tools like check_naming or check_secure. The purpose is unambiguous and action-oriented.

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 implies its use case: validating topology constraints on a project. It provides clear context on what it covers, but does not explicitly name alternatives or state when not to use it. Since the tool name and description align with the 'check' family, the usage context is clear enough for an agent to select it appropriately, but lacks explicit exclusionary guidance.

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 full burden. It discloses the dry-run default, that setting dry_run=false with output_dir writes files, the re-read validation step, linter execution, and outputs (manifest, GA XML/CSV, BOM). It also states 'Never touches a bus' for safety. This is comprehensive.

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 structured with the purpose up front, followed by parameter details and then the pipeline and constraints. It is longer than a one-liner but every sentence adds useful context. The front-loading of the core action aids quick comprehension.

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 entire workflow: input structure, processing pipeline, outputs, and R1/R2 limitations. It includes the dry-run default and file writing conditions. Given the output schema exists, the lack of a detailed return format is not a gap. No essential information for correct invocation 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 0%, so the description must explain parameters. It thoroughly details the 'rooms' structure (template, preset, slot_presets, params, label) and explains dry_run and output_dir semantics. It does not explicitly describe 'language' or 'project_name', but these have sensible defaults and are self-explanatory; the description compensates for the critical 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 first sentence states a specific verb ('Compose') and resource ('new KNX project from a list of room templates'), clearly identifying the tool as a constructor. It distinguishes itself from siblings like check_naming or suggest_repairs by emphasizing 'new' projects, and the pipeline description further clarifies its unique role.

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 states 'R1 builds NEW projects only' and notes 'Docking into an existing project and exact device selection are R2', giving clear when-not-to-use guidance. It also explains the dry-run default and the conditions for writing files, so an agent knows exactly when to invoke it.

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 provided, so the description must disclose behavioral traits. It explains that the tool returns objects per channel and total GA count, but does not mention side effects, prerequisites, or whether it is read-only. This is adequate but not comprehensive.

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 concise (4 sentences), front-loaded with the main purpose, and each sentence adds value. No redundant 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?

Given the tool's complexity and the presence of an output schema, the description covers input, output, and usage context. It could be improved by mentioning error handling or behavior when the order_number is not found.

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?

With 0% schema description coverage, the description adds significant meaning by explaining that 'order_number' can be a type or alias and that 'channels' defaults to 1. This compensates for the lack of schema-level documentation.

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 clearly states the tool expands a device into its group-address decomposition recipe, with specific verbs and resource. It provides examples of inputs and output, and the purpose is distinct from 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?

The description provides clear context for when to use the tool (turning a spec device list into a group-address structure), but does not explicitly mention when not to use it or provide alternative tools.

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 full burden. It discloses that the tool is read-only and performs a diff of specified aspects. However, it does not describe behavior like error handling, password usage, or performance implications. Still, it provides a good overview of what the tool does.

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 a single, well-structured sentence that immediately conveys the tool's purpose. It is front-loaded with the key concept ('Semantic diff') and lists specifics concisely. No unnecessary words.

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 the presence of an output schema (not shown), the description does not need to detail return values. It adequately explains the tool's role within the set of sibling tools. A brief mention of output type or the meaning of 'diff' could enhance completeness.

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 description adds meaning for path_a and path_b by clarifying their roles as base/old and new, which the schema does not specify. However, password_a and password_b are not explained, though they are optional and likely self-explanatory. Given 0% schema coverage, the description partially compensates.

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 clearly states it performs a semantic diff between two .knxproj files, specifying the exact aspects compared (added/removed GAs, DPT changes, renames, security-flag changes). This differentiates it from sibling tools like analyze_all or check_* tools, which have different scopes.

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 implies usage context (comparing two project files) but does not explicitly state when to use this tool versus alternatives. There is no mention of when it should not be used or any exclusions. The 'Read-only' hint is useful but not a usage guideline.

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 succeeds. It discloses that the tool is read-only, replays classification, outputs per-decision signals with confidence tiers, and flags conflicts. It also explains the confidence ordering (authoritative > structural > heuristic). No contradictions.

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 a compact paragraph of about five sentences, front-loaded with the core purpose ('Provenance for one group address'). It then details the replay mechanism, confidence tiers, conflict flagging, and usage context. Every sentence adds value with no fluff.

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?

Despite the tool's moderate complexity (replaying classification logic), the description covers the purpose, output structure (decisions, signals, confidence tiers), conflict behavior, and usage guidance. An output schema exists (though not shown), so return format is presumably defined there. The description is sufficient for an agent to decide when and how to call it.

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 0% and the description is the only source. It clarifies that the 'address' parameter is a group address ('one group address'), which is essential context. While it doesn't specify format examples, the singular required parameter's meaning is well conveyed by the description.

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: 'Provenance for one group address — why the tool classified it the way it did.' It clearly explains the function (replaying classification and showing signals with confidence tiers) and distinguishes it from siblings like check_naming or suggest_repairs by focusing on explanation rather than checking or fixing.

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 explicit when-to-use guidance: 'use before trusting a category or generating an entity.' It also implies a single-address scope and mentions conflict detection as a hotspot for misclassification. However, it does not name alternative tools or state when NOT to use it, so it lacks explicit exclusions.

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?

Without annotations, the description fails to disclose critical behavioral traits such as whether the tool modifies any state, requires specific prerequisites (e.g., loaded project), or what happens if output_path already exists (overwrite? error?). It only mentions file creation obliquely.

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 extremely concise, front-loading the primary function in the first sentence, and then listing the arguments with brief explanations. Every sentence adds value without redundancy.

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 tool with two simple parameters and an existing output schema, the description is largely complete. However, it omits prerequisites (e.g., project must be loaded) and does not clarify the workspace concept, which is necessary for 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?

Given 0% schema description coverage, the description compensates well by explaining the two parameters: fmt (with values and recommendation), output_path (optional file). This adds meaning that the schema alone does not provide. However, it could further clarify the workspace context and file overwrite behavior.

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 clearly states it generates an ETS-importable Group Address export, specifying the two output formats (xml and csv), which distinguishes it from sibling tools like list_group_addresses and generate_ha_package.

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 provided on when to use this tool versus alternatives such as list_group_addresses or generate_ha_package. The description only mentions fmt options without contextualizing the tool's role.

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 fully shoulders behavioral disclosure. It explains conditional behavior based on 'output_dir' and lists generated files. However, it omits details like permission requirements or potential side effects, which would elevate it to 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 description is a single paragraph that front-loads the purpose and uses efficient phrasing. It is concise but not overly terse; it could be slightly shorter by removing redundant phrases while retaining clarity.

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 the tool has one simple parameter and an output schema exists, the description covers the core behavior adequately. It explains both modes of output and lists all produced files, meeting completeness needs for this simple 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?

Despite 0% schema description coverage, the description thoroughly explains the lone parameter 'output_dir', including its effect on output routing. This compensates well for the schema gap, though it doesn't specify exact path format.

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 clearly states it generates a project handover pack, listing specific deliverables (handover.md, topology.svg, etc.). It uses the verb 'Generate' and specifies the resource, distinguishing it from sibling tools like 'generate_ets_group_addresses' which focus on single artifacts.

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 implies usage for project completion via 'as-built deliverable for commissioning', but does not explicitly state when to use this tool over alternatives or when not to use it. No exclusions or comparisons to sibling tools are provided.

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?

Describes two modes (file write vs inline return) but lacks details on file overwrite behavior or potential side effects. No annotations to contradict.

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 clear, front-loaded sentences with no wasted words. Efficiently communicates purpose and conditional behavior.

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?

Covers main functionality for a simple tool with one optional param and output schema. Lacks mention of error handling or file overwrite policy, but remains adequate.

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?

Only one parameter (output_path). Schema has no description, but the description adds crucial behavioral context: if provided, write to workspace; otherwise inline. This compensates for schema coverage of 0%.

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?

Description clearly states it generates a Home Assistant KNX package YAML, with two modes based on output_path. This distinguishes it from siblings like analyze_all or get_topology.

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 describes when to use each mode (with/without output_path). Does not mention alternatives or when not to use, but the context is sufficient for selection.

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 provided, so the description carries full behavioral disclosure burden. It only states the output format and purpose (skeleton for review), but does not disclose whether the operation is read-only, requires authentication, or has other behavioral traits.

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 a single sentence, concise and front-loaded with the action. However, it could be structured to better separate purpose, usage, and parameter details.

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 the presence of an output schema, return values need not be explained. However, the description lacks context about what 'functional datapoints' are and how the output relates to other tools, making it minimally adequate for a simple export 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 0%, yet the description does not explain the only parameter (output_path) beyond what the schema provides. It neither describes its effect nor suggests typical values, leaving an agent with no semantic guidance.

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 clearly states the tool exports a KNX IoT semantic view in Turtle/RDF format for review. It specifies the verb 'Export', the resource 'functional datapoints', and the output format, distinguishing it from sibling export tools like generate_ets_group_addresses.

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 implies usage for review purposes ('for review') but provides no explicit guidance on when to use this tool versus alternatives like generate_ets_group_addresses or generate_handover_pack. No exclusions or prerequisites are mentioned.

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 full burden. It correctly states the tool only drafts and doesn't execute, but fails to mention side effects like file creation or whether output_path saves the file. Behavior is partially transparent but lacks detail.

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 efficiently convey the tool's purpose, format, and execution context without extraneous information. Every word adds value.

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 tool with 1 optional parameter and an output schema, the description covers the core function and boundary. The missing parameter documentation is the only gap, so it's mostly 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?

The sole parameter output_path has 0% schema description coverage and no explanation in the description. The agent cannot infer what this parameter does (e.g., output file path) from the description alone.

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 clearly states the tool drafts a functional acceptance protocol in Markdown format, specifying the structure (command → expected status, pass/fail/sign-off). It distinguishes itself from sibling tools like generate_handover_pack by focusing on test protocols.

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 notes execution is manual/on-site and this tool only drafts the protocol, implying it's for planning not execution. However, it doesn't explicitly compare to alternatives or state when to use this over other tools.

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. It discloses the sorting order (numerical by individual address), the paging contract (next_cursor/total_matched/returned), and the returned fields. This is valuable behavioral context beyond the schema, though it does not mention read-only nature explicitly or authentication/rate-limit details.

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 tight sentences with no filler. The purpose is front-loaded, followed by sort order and paging contract. Every sentence carries substantive 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?

Given an output schema exists, the description adequately covers the listing behavior, returned fields, and paging. It is sufficient to call the tool correctly, though it assumes familiarity with list_group_addresses for full cursor semantics. Minor gaps around read-only confirmation and potential limits do not prevent correct use.

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 0%, so the description must compensate. It explains that limit/cursor follow the same paging contract as list_group_addresses, giving context that cursor is a pagination token and limit controls page size. However, it does not explicitly define each parameter, relying on the sibling tool's 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 states a specific verb ('List') and resource ('devices'), enumerates the returned fields, and specifies the sort order. It also references a sibling tool for the paging contract, which helps an agent distinguish it from related tools like list_group_addresses.

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 purpose implies when to use this tool (when a list of devices is needed), but there is no explicit guidance on when not to use it or which alternative to prefer. The reference to list_group_addresses is about paging behavior, not tool selection, so usage context is only implied.

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 provided, so the description carries full burden. It does not disclose any behavioral traits such as read-only nature, performance considerations, or side effects, only stating the return action.

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 a single sentence of 6 words, highly concise. However, it could be slightly more informative while remaining concise, but it earns 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?

Given no parameters and an output schema exists, the description is minimally adequate. However, it does not clarify what 'topology tree' entails or how to interpret results, leaving gaps for a new user.

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?

There are zero parameters, so baseline 4 applies. The description correctly implies no parameters are needed, and schema coverage is 100%, so no additional clarification is required.

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 uses the specific verb 'Return' and identifies the resource as 'area/line/device topology tree', clearly stating what the tool does. It distinguishes from sibling tools like 'analyze_all' or 'get_devices' which have different purposes.

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 use this tool versus alternatives, nor any exclusions or prerequisites. The description lacks context for appropriate usage.

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 provided, so the description carries the full burden. It mentions grading logic and criteria but does not disclose if the tool is read-only, has side effects, or requires specific permissions. The output schema exists but the description does not hint at output structure.

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 a single sentence that clearly states the purpose and criteria. It could be slightly more structured (e.g., bullet list of patterns) but it is efficient and front-loads the verb and resource.

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 parameters and an output schema exists, so the description need not detail return values. It explains the grading criteria adequately, though it could mention the scale better. Given the context, it is reasonably 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?

There are zero parameters, so baseline is 4 per rubric. The description adds no parameter info, which is acceptable since no parameters exist.

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 uses a specific verb ('Grade') and resource ('project') with a clear scale ('bare functional skeleton vs as-built grade') and lists the professional patterns used as criteria. This distinguishes it from sibling tools like 'analyze_all' or 'check_*' which focus on different aspects.

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 does not specify when to use this tool versus the many siblings (e.g., when to use 'grade_completeness' vs 'analyze_all' or 'project_report'). No when-not-to-use or alternative guidance is provided.

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 description clearly indicates a read-only listing operation with no side effects. However, since no annotations are provided, the description carries the full burden; it could additionally state idempotency or that it does not mutate state, but the current description is transparent enough.

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 a single sentence with no superfluous words. It is front-loaded and efficient, earning its place without any padding.

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 the tool has no parameters, an output schema exists (though not described), and the operation is simple listing, the description is complete. It provides all necessary information for an agent to understand the tool's purpose.

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 has zero parameters, so the schema coverage is 100% trivially. The description does not need to add parameter details. Baseline score of 4 is appropriate as it fully covers the semantic gap.

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 clearly states the verb 'list', the resource 'device decomposition recipes', and the scope 'built-in device library'. This specifically distinguishes from sibling tools like 'decompose_device' (which applies a recipe) and 'get_devices' (which lists devices).

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 implies usage as a simple listing operation, but it does not provide any explicit guidance on when to use it, when not to use it, or mention alternatives. For a straightforward tool, this is adequate but not fully instructive.

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?

There are no annotations, so the description carries the full behavioral burden. It goes well beyond the minimum by disclosing stable ordering rules, exact sort behavior per address type, cursor handling, the meaning of next_cursor and total_matched, and the fact that truncation is never silent. This is rich, concrete, and directly useful for correct invocation and result interpretation.

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 well organized: a one-line purpose, a compact filter list, and a focused paging paragraph. Every sentence carries useful information, and the most important differentiation (stable order) is front-loaded. The length is justified by the behavioral details provided.

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 filtered-list tool with an output schema and no annotations, the description is complete: it explains filtering, ordering, paging, cursor lifecycle, and non-silent truncation. Nothing necessary for an agent to call or interpret the tool 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?

The input schema has 0% description coverage, so the description must compensate. It explicitly enumerates accepted values for category and kind, explains cursor semantics via next_cursor, and clarifies missing_dpt_only as a filter. The meaning of limit is not elaborated, but its default and the paging context make it adequately inferable. This is strong compensation, though not exhaustive.

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 uses a specific verb and resource: 'List parsed group addresses with classification'. It immediately conveys the main output and the stable-order guarantee, which clearly distinguishes this tool from siblings like generate_ets_group_addresses or get_devices. The purpose is unambiguous and actionable.

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 clearly establishes when to use this tool: to list group addresses with filtering by category, kind, or missing DPT, and to page through results. It does not explicitly name alternatives or say when not to use it, but the filter and paging context is clear enough for an agent to select it appropriately.

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 provided, the description carries the full burden and meets it: it discloses the state-changing side effect ('the result replaces the loaded project for every other tool'), the data that is extracted, the absence of devices/functions/topology, and the name-only pairing limitation. These are exactly the behavioral traits an agent must know before calling a load 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?

The description is long, but it is cleanly organized into purpose, usage trigger, data content, effect, tool-compatibility matrix, and caveat paragraphs, with the core purpose front-loaded. The tool-name lists are bulky but carry real routing value for an agent deciding which tool to pair with this loader.

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 loader with an output schema, nothing essential is missing: the return contract is left to the output schema, while the description covers purpose, side effects, compatibility, and limitations. The only conceivable addition would be explicitly naming load_project as the alternative, but the contrast is already clear from 'instead of a full .knxproj.'

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 single parameter has zero schema description coverage, so the description must compensate. The Args section states 'path: Path to the exported .xml file,' which together with the main description's 'ga-export/01 XML' context conveys the file type and purpose. It is adequate but adds little beyond that basic meaning.

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 sentence states a specific verb and resource: 'Load an ETS group-address export (ga-export/01 XML) instead of a full .knxproj.' It signals that this is the GA-only counterpart to the full-project load, distinguishing it from the sibling load_project, and enumerates exactly what is read (names, addresses, DPTs, descriptions, security flag, range tree).

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?

Gives the explicit trigger condition ('For when you only have the GA list') and names the exact accepted file types (ETS 'Export Group Addresses' file, TapPlan-like planning imports). It goes further than most definitions by enumerating which downstream tools work after loading and which have 'nothing to read,' plus the pairing-relies-on-names caveat.

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 provided, but description discloses read-only nature, caching behavior, and optional password/language parameters. Does not detail error handling or file format expectations.

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?

Single-line purpose followed by concise Args list. No redundant or missing 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?

Given output schema exists, description covers main function, caching, and parameter details. Could mention that tool should be called before others, but implied by sibling names.

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?

With 0% schema description coverage, description fully explains all three parameters: path, password (with conditional), and language (with examples). Adds value beyond schema types.

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?

Description clearly states verb 'parse' and resource '.knxproj file', with read-only and session caching scope. Distinguishes from sibling tools which operate on loaded data.

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?

Implicitly foundational for other project tools, but no explicit when-to-use, when-not-to-use, or alternatives beyond sibling 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, the description fully discloses behavior: read-only, PII-safe, reads only vendor data, never client project. It explains what 'unverified' DPT means and that the return value is a summary not full object lists. No contradictions.

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?

Single paragraph is efficient and front-loaded with purpose, but somewhat lengthy. Every sentence adds value, though could be structured with bullet points for readability.

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 3 parameters, no annotations, and output schema exists, the description covers purpose, usage, return value summary, and limitations. Lacks details on error cases or prerequisites but is largely 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 0%, so description must compensate. It indirectly explains path (file type) and output_path (catalog writing), but password parameter is not explained. Adds value beyond schema but could be more complete.

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 clearly states it extracts exact device object models from .knxproj/.knxprod files, specifying the resource (vendor application programs) and action (extract). It distinguishes from siblings by contrasting with 'generic recipe' and noting it reads only vendor catalog data, not client projects.

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 states when to use: to build the local device catalog for decompose_device, and mentions setting NICKOL_KNX_CATALOG. Also explains behavior with output_path and the return value format, providing clear context for usage.

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 full burden. It only mentions 'produce' (implying read-only) but lacks details on side effects, required inputs, or response behavior. The output schema exists but is not referenced.

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 that is concise and front-loaded with purpose. However, it omits important information about parameters and usage, reducing its effectiveness.

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?

Despite having an output schema, the description fails to cover parameter behavior, usage context, or behavioral traits. Two parameters remain unexplained, and the tool's role among siblings is unclear.

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 0%, and the description does not mention either parameter (name_regex, output_path). No guidance on their purpose or usage, leaving the agent uninformed.

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 clearly states it produces a human-readable Markdown report, with a specific hint about reviewing before import. However, it does not explicitly differentiate from sibling tools like analyze_all or check_*, which may also generate reports.

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 explicit guidance on when to use this tool versus siblings. The phrase 'review before any import' implies a specific context but does not outline alternatives or exclusion criteria.

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 provided, so description bears full burden. It does not disclose whether the tool is read-only, requires authorization, or has side effects. The description only states purpose, not behavior.

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?

Single sentence with clear parenthetical example. No wasted words; front-loaded with purpose.

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?

Tool has no parameters and has an output schema, so description need not detail returns. However, more context about what kind of suggestions or output format would improve completeness. Adequate but minimal.

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% with zero parameters, so baseline is 3. Description adds no parameter-specific info because there are none, but also no omission.

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 clearly states the tool provides naming hygiene suggestions for empty names and status GAs missing a status keyword. The verb 'suggest' and specific resources are identified, distinguishing it from sibling tools like check_naming or grade_completeness.

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 on when to use this tool versus alternatives. The description does not mention prerequisites, typical use cases, or when not to use it.

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 description discloses key behavioral traits: 'The server never writes to ETS or the bus,' ensuring agents know this is a non-destructive suggestion tool. It also clarifies that suggestions are reviewable, not automatic. Without annotations, this level of disclosure is commendable.

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 concise and well-structured. The first sentence immediately conveys the core purpose. The second paragraph provides concrete examples and workflow context without unnecessary verbosity. Every sentence adds value.

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 the tool has no parameters and an output schema exists (though not detailed here), the description sufficiently covers behavior, workflow integration with generate_ets_group_addresses, and non-destructive nature. It could mention output format briefly, but the presence of an output schema mitigates this.

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 input schema has zero parameters, so the description does not need to elaborate on parameters. It adds value by explaining the tool's operation and what it accomplishes, compensating for the lack of parameter details. The schema coverage is 100%.

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 clearly states the tool's function: 'Propose concrete fixes for the project's findings — repair, don't just flag.' It provides specific examples of fixes (infer DPT, correct sub-DPT, etc.) and distinguishes itself from sibling tools by noting that suggestions feed into generate_ets_group_addresses and that the server never writes to ETS or the bus.

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 indicates when to use the tool (for concrete fixes based on project findings) and provides workflow context: 'Suggestions only — a human reviews them; accepted new GAs feed into generate_ets_group_addresses.' It does not explicitly list alternatives, but the context implies appropriate usage.

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 provided, the description carries the full burden of behavioral disclosure. It explicitly states report-only, that nothing is written, and that results are ok + findings. It also reveals the nuanced policy that area_m2 is a hint with provenance, not a normative fact.

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, then organizes parameter usage and validation details into a compact, readable list. Every sentence adds distinct value with no repetition or 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?

Even without annotations, the description covers purpose, parameter semantics, side-effect behavior, and return shape (ok + findings). Since an output schema exists, return details need not be spelled out further. The tool call can be understood and invoked correctly from this description alone.

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 0%, so the description must compensate fully. It does so by explaining both parameters: template is a built-in slot_id with examples like 'bedroom'/'kitchen', and path points to a custom template YAML. It also clarifies the or-relationship between them.

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: validate a Room Library template against the R1 schema. It also distinguishes itself from sibling check_* tools by declaring report-only behavior and focusing on template contract checks.

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 clearly communicates the context of use: validating either a built-in template by slot_id or a custom YAML by path. It does not explicitly name alternatives or state when not to use the tool, but the narrow template-validation scope makes the intended usage plain.

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 full burden. It states the tool shows information, implying a read-only operation, but provides no details on outcome, side effects, or necessary permissions. Minimal disclosure beyond the basic action.

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 a single sentence of 9 words, with no redundant information. Every word serves a purpose, making it highly concise and front-loaded.

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 exists (presumably documenting return values), the description adequately covers the tool's function for a simple info tool. It could be slightly more explicit about what 'confined output workspace' means, but overall 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?

There are zero parameters, so the baseline is 4. The description does not need to add parameter meaning, and the schema coverage is 100% by default.

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 uses a specific verb 'Show' and identifies the resource ('confined output workspace' and 'safety guarantees'), which clearly indicates the tool's purpose. It is distinct from sibling tools that perform analysis or checks. However, the term 'confined' may be unclear to some users.

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 on when to use this tool versus alternatives. The description does not provide context or suggest scenarios, leaving the agent to infer usage from the name alone.

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