hlod_assign_layer

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states that it 'assigns' an HLOD layer, implying a mutation, but it does not disclose whether the assignment modifies the actors' properties, what happens if the HLOD layer doesn't exist, how the selection fallback works, or whether there are side effects. It also does not mention any error behavior or reversibility. The example demonstrates a valid call but does not reveal behavioral traits beyond the basic operation. This is a significant gap for a mutation tool without annotations.

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

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

The description is concise, consisting of a single sentence followed by a KB reference and an example. It is front-loaded with the purpose and avoids unnecessary fluff. However, it could be more informative without becoming verbose, such as explaining the parameter precedence or selection fallback. It is appropriately sized but could be improved with a brief note on parameter usage. Overall, it is concise and well-structured for its length.

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

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

Given the tool's complexity—two actor-related parameters, a selection fallback, and a required HLOD layer—the description is incomplete. It does not explain how the selection is used if no actors are provided, whether 'actor' and 'actors' are mutually exclusive, or what happens if both are given. It also does not mention any validation or error cases. While an output schema exists (not shown), the description does not address the operational context needed for correct invocation. The KB reference is helpful but is not part of the description itself. For a tool with these nuances, the description should provide more guidance.

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 has 0% description coverage, so the description must explain the parameters. It mentions 'named actors' and 'current editor selection', which maps to the 'actor' and 'actors' parameters, and provides an example using 'actors'. However, it does not clarify the difference between the singular 'actor' and plural 'actors', how they relate to the selection fallback, or what happens if both are provided. It also does not mention that 'hlod_layer' is required. The example only shows the 'actors' parameter, leaving the 'actor' parameter's purpose ambiguous. The description adds minimal semantic value beyond the schema, which itself only provides types and titles.

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: assign an HLOD Layer asset to named actors or the current editor selection. The verb 'assign' and the resource 'HLOD Layer asset' are specific, and the target (named actors or selection) is explicit. It distinguishes from other HLOD tools like hlod_generate by focusing on assignment, but it doesn't explicitly differentiate itself from other tools that might assign layers. Overall, the purpose is clear and specific.

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: you assign an HLOD layer to actors or selection. It mentions two modes (named actors or current selection), which gives some context. However, it does not explicitly state when to use this tool versus alternatives, nor does it provide exclusions or conditions (e.g., 'use this when you have a specific HLOD layer and actors to assign'). The KB reference is given but not elaborated in the description itself, so the guidance is implicit rather than explicit.

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