translate_entity

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

With no annotations provided, the description carries the full burden of disclosing behavioral traits. It does well by revealing that the file is written, TrenchBroom-HL reloads automatically, and that unsaved edits trigger a confirmation which defaults to keeping the editor version. It also mentions the Valve-format texture-locking nuance. It stops short of stating irreversibility, whether both brush geometry and origin move together or only one, or units for the delta, but it discloses more than most mutation tools.

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?

Two sentences, both information-dense with zero filler. The core action is front-loaded, and the second sentence covers important side effects and editor behavior without redundancy. Everything included earns its place.

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 description covers file-writing and editor-reload behavior, which is essential for a mutating tool with no output schema. But it misses critical context: what 'index' refers to, whether the delta applies to brushes, origin, or both by default, and what happens after the confirmation when unsaved edits exist. These gaps could lead an agent to call the tool with incomplete understanding.

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 already documents delta as an offset and map_path as an absolute path, covering 67% of parameters. The description adds meaning to delta by explaining its effect on brush geometry and origin, and implies that map_path is the file being modified. However, the 'index' parameter is left entirely undocumented in both schema and description, which is a meaningful gap for an agent trying to invoke the tool correctly.

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: 'Move an entity by a delta'. It further clarifies scope by stating both what is affected (brush geometry and/or origin property) and a notable implementation detail (textures locked in Valve format). This clearly distinguishes it from siblings like delete_entity, set_entity_properties, or add_entity.

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 intended use is implied by the action verb and the delta parameter. However, there is no explicit when-to-use vs alternatives, such as saying 'use this instead of set_entity_properties when you need spatial translation', nor any exclusions. The context is clear enough for an agent to infer the basic use case, but guidance is not explicitly provided.

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