nickol-knx-mcp
Server Quality Checklist
Latest release: v0.8.0
- Disambiguation5/5
Each tool has a clear, distinct purpose. The check_* tools cover different checks (DPT, energy, matter, etc.), generate_* tools produce different outputs, and tools like decompose_device vs parse_devices_from_project are complementary without overlap. No ambiguity.
Naming Consistency5/5All tools consistently use snake_case with a verb_noun pattern (e.g., check_dpt, generate_ha_package, list_group_addresses). No mixing of conventions or inconsistent naming styles.
Tool Count4/5With 25 tools, the set is slightly large but well-scoped for the KNX project domain. Each tool serves a specific function in the workflow (loading, analysis, generation), and no tools feel redundant or unnecessary.
Completeness5/5The tool surface covers the full project lifecycle: loading, parsing, listing, various checks, generating multiple output formats (ETS, HA, handover, test protocol, IoT), diffing, suggestions, and grading. No obvious gaps for the stated purpose.
Average 3.6/5 across 25 of 25 tools scored. Lowest: 2.4/5.
See the Tool Scores section below for per-tool breakdowns.
- 0 of 1 community issues answered or closed in the last 6 months
- 78 commits in the last 12 weeks
- Last stable release on
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
This repository includes a glama.json configuration file.
This server has been verified by its author.
Add related servers to improve discoverability.
How to sync the server with GitHub?
Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.
To manually sync the server, click the "Sync Server" button in the MCP server admin interface.
How is the quality score calculated?
The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).
Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.
Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).
Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.
Tool Scores
- Behavior2/5
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.
Conciseness3/5Is 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.
Completeness2/5Given 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.
Parameters1/5Does 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.
Purpose4/5Does 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.
Usage Guidelines2/5Does 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.
- Behavior2/5
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.
Conciseness3/5Is 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.
Completeness2/5Given 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.
Parameters1/5Does 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.
Purpose4/5Does 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.
Usage Guidelines2/5Does 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.
- Behavior2/5
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.
Conciseness4/5Is 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.
Completeness2/5Given 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.
Parameters1/5Does 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.
Purpose5/5Does 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.
Usage Guidelines2/5Does 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.
- Behavior2/5
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.
Conciseness4/5Is 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.
Completeness3/5Given 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.
Parameters4/5Does 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.
Purpose4/5Does 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.
Usage Guidelines2/5Does 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.
- Behavior2/5
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.
Conciseness4/5Is 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.
Completeness3/5Given 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.
Parameters1/5Does 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.
Purpose5/5Does 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.
Usage Guidelines3/5Does 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.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description should disclose behavioral traits like read-only nature, but it only states listing without mentioning side effects, permissions, or response format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences with no wasted words; however, the second sentence is a list that could be more structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers basic purpose and filter options but omits details like default limit (500), pagination, or output format, leaving gaps despite an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, requiring the description to compensate. It lists possible category values but does not explain other parameters like 'kind' or 'missing_dpt_only', adding minimal meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('list') and resource ('parsed group addresses with classification'), clearly distinguishing from sibling tools like 'analyze_all' or 'check_dpt'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions filters but provides no guidance on when to use this tool versus alternatives, nor any prerequisites or constraints.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
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.
Conciseness5/5Is 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.
Completeness3/5Given 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.
Parameters3/5Does 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.
Purpose4/5Does 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.
Usage Guidelines2/5Does 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.
- Behavior2/5
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.
Conciseness5/5Is 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.
Completeness3/5Given 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.
Parameters4/5Does 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.
Purpose4/5Does 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.
Usage Guidelines2/5Does 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.
- Behavior2/5
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.
Conciseness5/5Is 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.
Completeness4/5Given 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.
Parameters4/5Does 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.
Purpose4/5Does 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.
Usage Guidelines2/5Does 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.
- Behavior2/5
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.
Conciseness5/5Is 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.
Completeness3/5Given 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.
Parameters4/5Does 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.
Purpose4/5Does 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.
Usage Guidelines3/5Does 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.
- Behavior2/5
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.
Conciseness4/5Is 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.
Completeness3/5Given 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.
Parameters4/5Does 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.
Purpose5/5Does 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.
Usage Guidelines2/5Does 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.
- Behavior2/5
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.
Conciseness4/5Is 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.
Completeness4/5Given 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.
Parameters4/5Does 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.
Purpose5/5Does 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.
Usage Guidelines2/5Does 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.
- Behavior2/5
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.
Conciseness5/5Is 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.
Completeness4/5Given 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.
Parameters4/5Does 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.
Purpose5/5Does 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.
Usage Guidelines2/5Does 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.
- Behavior3/5
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.
Conciseness5/5Is 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.
Completeness4/5Given 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.
Parameters2/5Does 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.
Purpose5/5Does 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.
Usage Guidelines3/5Does 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.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description bears full burden. It describes the output fields but does not disclose any additional behavioral traits (e.g., scoping, sorting, permissions). For a parameterless list tool, this is adequate but lacks depth.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence is concise and front-loaded. However, it could be structured slightly better (e.g., listing fields more explicitly). No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters and presence of output schema, describing the returned fields is sufficient. Missing context on whether this returns all devices or scope within a project, but overall complete for a simple list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist; schema coverage is 100%. With 0 parameters, baseline is 4. Description adds no param info, but none is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'List devices' with specific fields (address, name, order number, manufacturer). This verb+resource structure distinguishes it from siblings like get_topology or 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.
Usage Guidelines2/5Does 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. Does not mention prerequisites, comparisons, or when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
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.
Conciseness5/5Is 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.
Completeness4/5Given 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.
Parameters4/5Does 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.
Purpose5/5Does 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.
Usage Guidelines3/5Does 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.
- Behavior4/5
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.
Conciseness4/5Is 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.
Completeness4/5Given 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.
Parameters4/5Does 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.
Purpose5/5Does 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.
Usage Guidelines3/5Does 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.
- Behavior3/5
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.
Conciseness5/5Is 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.
Completeness4/5Given 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.
Parameters4/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior4/5
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.
Conciseness5/5Is 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.
Completeness4/5Given 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.
Parameters4/5Does 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.
Purpose5/5Does 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.
Usage Guidelines3/5Does 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.
- Behavior3/5
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.
Conciseness5/5Is 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.
Completeness4/5Given 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.
Parameters4/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior4/5
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.
Conciseness5/5Is 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.
Completeness5/5Given 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.
Parameters4/5Does 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.
Purpose5/5Does 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.
Usage Guidelines3/5Does 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.
- Behavior4/5
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.
Conciseness5/5Is 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.
Completeness5/5Given 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.
Parameters4/5Does 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.
Purpose5/5Does 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.
Usage Guidelines3/5Does 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.
- Behavior4/5
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.
Conciseness5/5Is 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.
Completeness4/5Given 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.
Parameters5/5Does 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.
Purpose5/5Does 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.
Usage Guidelines3/5Does 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.
- Behavior4/5
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.
Conciseness5/5Is 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.
Completeness4/5Given 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.
Parameters4/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior5/5
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.
Conciseness4/5Is 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.
Completeness4/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines5/5Does 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.
GitHub Badge
Glama performs regular codebase and documentation scans to:
- Confirm that the MCP server is working as expected.
- Confirm that there are no obvious security issues.
- Evaluate tool definition quality.
Our badge communicates server capabilities, safety, and installation instructions.
Card Badge
Copy to your README.md:
Score Badge
Copy to your README.md:
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/NickoScope/nickol-knx-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server