tilemap_manage

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

With no annotations provided, the description fully carries the burden of disclosing behavioral traits. It reveals that all write ops are undoable, explains the critical source-ID remapping caveat for specialized .tres files, details the canonical call shape and flat-parameter alias, and lists return values for each op. This is exceptionally transparent and goes beyond what annotations would typically provide.

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

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

The description is well-organized: a one-line summary, a brief scope statement, an important warning box, and a bulleted list of operations with parameters and returns. Despite being long, every section earns its place with critical information, and the structure makes it easy to scan. No fluff or repetition.

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 (four operations, a tricky source-ID remapping rule, and an alias call shape), the description is complete. It explains all operations, parameters, returns, and edge cases. The existence of an output schema does not make the description redundant because the description also details each operation's specific return structure, which is more granular than a generic schema.

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

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

The input schema is minimal: only op, params (free-form object), and session_id with 0% parameter description coverage. The description compensates comprehensively by defining each operation's parameters (path, source_id, atlas_col, atlas_row, map_x, map_y) and their meanings, plus return shapes. It adds substantial semantic value beyond 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 opens with a specific verb and resource: 'TileMap / TileMapLayer authoring (set tiles, fill rects, clear, read cells).' It clearly distinguishes itself from siblings like tileset_manage by targeting TileMapLayer nodes and enumerates four concrete operations. This is unambiguous and fully differentiates the tool's purpose.

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

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

The description provides clear context: operations target TileMapLayer nodes in the currently edited scene by scene-relative path, and all write ops are undoable via EditorUndoRedoManager. It implicitly tells when to use the tool (for authoring tilemaps) but does not explicitly name alternatives or exclusion conditions, so it falls short of a 5.

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