gaea_set_input_heightmap

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

No annotations are provided, so the description must carry the full burden of behavioral disclosure. It reveals that the tool mutates a File node's FileName, but it does not mention the dryRun default, whether the graph is saved or modified on disk, or any side effects. This is a significant transparency gap for a mutation tool.

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

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

The description is a single, focused sentence that leads with the action and names both the target and the value. No wasted words and no redundancy with the tool name.

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 no annotations and no output schema, the description should cover the full calling context. It leaves key operational details unresolved: what graph represents, how dryRun behaves, and whether any graph files are modified. The description is enough to guess the intent but not enough to invoke the tool confidently without additional investigation.

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

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

With only 25% schema description coverage, the description needs to compensate. It adds some meaning by tying heightmap to a File node's FileName, but graph and dryRun are left unexplained. The description does not clarify what format graph expects or what dryRun actually does, so it falls short of compensating for the weak schema coverage.

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 ('Set'), a precise target ('Gaea File node's FileName'), and the value ('a new heightmap path'). This clearly distinguishes it from sibling tools like gaea_set_build_output or gaea_set_variable, since it names both the node type and the property being modified.

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

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

Usage is implied: use this when you want to change which heightmap a Gaea File node points to. However, there is no explicit guidance about when not to use it or which sibling alternative might be more appropriate, so this is only minimally viable.

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