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

The description is minimal and does not disclose any behavioral traits beyond what the schema provides. With no annotations provided, the description carries the full burden. It doesn't mention whether the generation is one-shot, whether it validates inputs, what happens if the platform doesn't match parameters (e.g., providing 'dimmable' with platform=cover - probably ignored), or whether it overrides existing configs. The schema has rich default values and parameter descriptions, but the overall behavior of the tool (e.g., whether it returns errors on invalid combinations) is not disclosed.

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 to the point. It front-loads the purpose with 'Generate' and specifies the output type. It doesn't waste any words. However, it could expand slightly on usage without becoming bloated, but for a tool description that relies on schema, this is 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 tool's complexity (13 parameters, 7 platform types) and the rich schema with per-parameter descriptions and defaults, the description is adequate for an agent to understand the tool's scope. The output schema likely details the generated YAML structure, so the description doesn't need to explain return values. The main gap is usage guidance, but with the schema's parameter descriptions, an agent can infer how to use 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?

The schema description coverage is 100%, meaning each parameter has a description in the schema. The tool description adds no additional meaning beyond the schema. For example, the description doesn't explain the relationship between 'who' and 'platform' beyond what's in the schema. Given the high coverage, a baseline of 3 is appropriate; the description does not add extra semantic value.

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 purpose: 'Generate production-ready Home Assistant YAML configuration for any MyHOME entity.' It specifies the exact resource (Home Assistant YAML configuration) and the domain (MyHOME entities). It also suggests the output is ready-to-use, which is helpful for the agent. It doesn't explicitly name a sibling tool to differentiate from, but given the sibling list contains related tools like 'draft_own_frame' and 'get_ha_guide', the purpose is specific enough that an agent won't confuse it with the others.

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 you need a Home Assistant YAML config for a MyHOME entity. It does not explicitly state when not to use it or mention alternative tools like 'lookup_frame_syntax' or 'get_ha_guide'. The context suggests it could be used alongside 'get_ha_guide' for guidance, but this is not explicitly stated. The tool is self-described as the way to generate configs, but no exclusions 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?

No annotations are provided, so the description must carry the full behavioral disclosure. It mentions 'construct and validate' but does not explain what happens on invalid input, whether it throws errors, or any side effects. It lacks details about how validation works or what constitutes a valid frame beyond syntactic correctness.

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, succinct sentence with no filler or repetition. It front-loads the core action and is appropriately concise for the tool's purpose, avoiding any unnecessary elaboration.

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 6 parameters and no annotations, the description is too sparse to be complete. It does not explain when to use this tool over siblings, what the output frame looks like (though an output schema exists, which mitigates that), or how validation behaves. The description leaves significant gaps for an agent deciding whether 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?

The input schema has 100% description coverage, with each parameter explained (who, what, where, values, dimension, command_type). The description adds no additional meaning beyond the schema, so it meets the baseline for high coverage. It does not clarify how parameters interact or provide examples beyond the schema's simple descriptions.

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 clear verb ('Construct and validate') and resource ('OpenWebNet frame'), making the purpose obvious. It does not explicitly differentiate from the sibling parse_and_validate_frame, but the action is distinct enough that an agent can infer it is for creating frames rather than parsing existing ones.

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 like parse_and_validate_frame or lookup_frame_syntax. The description gives no context about typical use cases, prerequisites, or when the tool should be avoided.

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 burden. It discloses the tool inspects AST signatures, public methods, and docstrings, which is a read-only behavior. However, it doesn't mention whether the tool requires a specific environment, whether it can fail on missing symbols, or what the output structure looks like. The output schema exists, so return values are partially covered, but behavioral details like error handling are absent.

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 front-loads the action and resource, then names the two source locations. It is concise and efficient, with no wasted words. It could be slightly more structured by separating the locations, but it's well within acceptable limits.

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 single-parameter inspection tool with an output schema, the description is mostly complete. It names the source locations and what is inspected. However, it doesn't clarify how the tool handles symbols that exist in both locations, whether it searches both, or what happens if the symbol is not found. These are minor gaps given the tool's 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 description coverage is 100%, so the schema already documents the 'symbol' parameter with examples. The description adds the context that the symbol is a class or module name and ties it to the two source locations, but it doesn't add significant meaning beyond the schema's examples. Baseline 3 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 states a specific verb ('Inspect') and resource ('Python AST signatures, public methods, and docstrings') from two locations. It is clear about what the tool does, though it doesn't explicitly distinguish itself from siblings like get_who_spec or search_documentation.

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 by naming the source locations (custom_components/myhome or OWNd), which tells the agent when this tool is relevant. However, it doesn't explicitly state when to use this tool over alternatives like get_who_spec or search_documentation, nor does it mention 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It only states 'Fetch complete markdown guide,' implying a read operation, but doesn't disclose any side effects, permission requirements, or error behavior. This is minimal and leaves the agent to infer most 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, concise sentence that immediately states the action and resource. There is no filler or redundancy, and it is front-loaded with the key information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with a single well-documented parameter and an output schema, the description is largely complete. It clearly states what the tool does, and the schema covers the required input. The only gap is the lack of usage guidance, but that is covered under a different dimension. An agent can correctly invoke this tool based on the description and schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with the parameter 'topic' clearly documented including example values. The description adds no additional parameter semantics beyond what the schema provides, so the baseline score of 3 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 states a specific verb ('Fetch'), a clear resource ('complete markdown guide'), and the domain ('Home Assistant entities'). It clearly distinguishes from siblings like 'search_documentation' by indicating it retrieves a full guide rather than searching. The purpose is unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives. It doesn't mention that this is for retrieving a specific guide by topic, while search_documentation might be for broader searches. There are no exclusions or alternative recommendations.

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 whatsoever, the description bears full weight for behavioral disclosure. 'Retrieve' indicates a read-only operation, but it does not mention potential error cases, rate limits, or whether the response could be large. It adds basic context (return contents) but leaves more on the table.

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 concise single sentence that front-loads the action and the object, with no filler words. It packs relevant content (specification, commands, dimensions) exactly as needed, without bloating.

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, the return format is covered, and the single parameter is fully documented. However, the description does not address potential usage boundaries among the sibling tools, and the absence of annotations leaves a small discoverability gap for agents.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, and the schema itself explains the 'who' parameter with practical examples. The description does not add extra semantic detail beyond restating the scope, so a baseline 3 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 uses a specific verb ('Retrieve') and names a concrete resource ('full technical specification, WHAT commands, and DIMENSIONS') scoped to an OpenWebNet WHO family. It is clear, but it does not explicitly differentiate itself from sibling tools like list_who_catalog or lookup_frame_syntax, so the agent must infer the distinction.

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 it should be used when a complete technical specification is needed, but it gives no explicit when-not or alternative selection. Sibling tools are not mentioned, so an agent may need to introspect other definitions to choose the right 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 the full burden. It transparently discloses that the tool returns a complete inventory table including archive status and HA platform. This is a read-only operation, but the description doesn't explicitly state that; however, the act of 'returning' implies no mutation. The behavior is clear enough for a simple listing tool, so a 4 is appropriate.

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, front-loaded sentence that efficiently conveys the core action and output. There is no fluff, and every word adds value. It is perfectly concise for the tool's simplicity.

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, the description fully covers what the tool does. It specifies the content of the return (complete inventory, archive status, HA platform), which is all an agent needs to decide and invoke it correctly. No missing information is apparent.

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 there is nothing for the description to explain beyond what the schema shows. Per the baseline for 0 params, a score of 4 is given. The description doesn't add param details (not needed), and the schema is empty, so no additional semantics are 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 states a specific verb ('Return') and a clear resource ('complete inventory table of all 20+ OpenWebNet WHO families'). It also details what is included ('archive status and HA platform'), which distinguishes it from sibling tools like get_who_spec that likely focus on single families. The purpose is unambiguous and not a tautology.

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 implies when to use this tool: when a complete inventory of WHO families is needed. It does not explicitly name alternatives or state exclusions, but the context of sibling tools (e.g., get_who_spec, search_documentation) makes the use case obvious. It provides clear context without formal exclusion guidance, fitting a score of 4.

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. It does not mention whether the operation is read-only, what output it returns, any limitations (e.g., only statically defined syntax), or any dependencies. The term 'look up' implies read-only, but no explicit disclosure is given.

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, direct sentence with no wasted words. It is appropriately concise and front-loaded with the core 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?

Given the presence of an output schema and simple optional parameters, the description is adequate for a basic lookup tool. However, it lacks usage context such as when to prefer this over search_documentation or how results are structured. The existence of an output schema may cover return details, but the description does not clarify the tool's role among siblings.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema provides 100% coverage of both parameters with descriptions. The description adds a general mention of 'parameter formats' but does not elaborate on how the `who` or `frame_type` parameters interact. It adds minimal value over the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('look up') and the specific resource: OpenWebNet message grammar, regex templates, and parameter formats. This distinguishes it from sibling tools like get_who_spec (WHO-specific codes) and search_documentation (general documentation search).

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 search_documentation or get_who_spec. The description only states what it does, leaving the agent to infer the appropriate context.

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 discloses that the tool parses and performs semantic validation, which implies read-only analysis. But it does not describe failure modes (e.g., behavior on malformed frame strings), whether validation errors are returned in the response, or the exact scope of semantic validation. This is adequate but leaves a meaningful behavioral gap for an unhandled edge case.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

One sentence, no filler, and the action is front-loaded. It states the exact resource and operation in the first clause. Every word carries meaning; there is no wasted ink.

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 a very simple one-parameter tool with 100% schema coverage and an output schema, the description is nearly sufficient. What is missing is a note about expected behavior on invalid input or the exact semantic validation process, but the output schema covers return structure, so this is only a minor gap. It ranks slightly above baseline because the scope is simple and mostly covered by structured data.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the single parameter 'frame' has rich examples in the schema. The description adds an OpenWebNet frame string and the notion of validation, but does not add new parameter-level clarity beyond what the schema provides. Baseline 3 applies because the schema already does the job and the description does not extend it.

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 ('parse') and a concrete resource ('raw OpenWebNet frame string'), and adds 'semantic protocol validation'. This clearly distinguishes the negative: it is not a lookup or draft tool. It does not explicitly contrast against siblings, so it stops short of a 5, but the action is unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The usage context is implied: use it when you have a raw frame and need it parsed/validated. However, there is no explicit when-not-to-use guidance, no alternative naming (e.g., 'for syntax lookup use lookup_frame_syntax'), and no mention of prerequisite knowledge or context. It earns the implied-usage baseline but no more.

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 that the tool flushes caches and reloads multiple data sources, which is useful side-effect transparency. However, with no annotations and no stated consequences (e.g., whether this is disruptive, requires permissions, or how long it takes), the behavioral description is incomplete.

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, focused sentence with concrete technical terms and no filler. It front-loads the key verb phrase 'Flush caches and reload' and lists the exact resources affected.

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 parameterless refresh operation, the description covers what and how, but it does not say when to use it (e.g., after documentation source changes) or what side effects/return behavior to expect. The output schema could help but is not described. This leaves some operational ambiguity for an agent deciding whether 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?

The tool has no parameters decorating the schema, so there is no ambiguity about inputs. A baseline of no parameters means the description needs no additional parameter explanation, and it correctly omits any.

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 specific operation ('flush caches and reload all OpenWebNet specifications, markdown documents, and codebase AST models'). The verb is concrete and the resource scope is explicit, making the tool's purpose immediately distinguishable from the read-only siblings like search_documentation and get_who_spec.

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 this is a maintenance/refresh action rather than a query operation, but it never states when to invoke it, when not to, or how it relates to alternatives. Unlike examples such as 'use search_calls_extensive instead', there is no explicit routing 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 provided, the description carries the burden of behavioral disclosure. It does mention the fuzzy/keyword search behavior and the scope of documents, which adds some context beyond the schema. However, it does not disclose whether results are ranked, any limits, or the nature of the output beyond what the output schema implies. It is adequate but not exhaustive.

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, efficient sentence that front-loads the action and scope. Both the search type (fuzzy/keyword) and the target resources are included without any fluff or redundancy. There is no wasted wording.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is a simple search operation with two parameters (one required) and an output schema, so the description is largely sufficient. It clearly states what is being searched. It does not mention pagination or result details, but the output schema likely covers those. The low complexity and existing schema make this adequately complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so both parameters (query, category) are already documented in the schema. The description adds no additional meaning about parameter usage or semantics beyond what the schema provides, so the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action (search), the resource (OpenWebNet protocol specifications and Home Assistant MyHOME guides), and the nature (fuzzy and keyword). This is a specific verb+resource and is distinguishable from sibling tools like get_who_spec or list_who_catalog, which are targeted lookups rather than a general documentation search.

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 that this tool is for searching documentation, but it does not explicitly state when to use it versus the more specific sibling tools, nor does it provide exclusions or alternatives. The context is clear enough for an agent to infer usage, but no explicit guidance is given.

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