ass_transform_drawing

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

With no annotations present, the description carries the full burden and does well: it discloses that in_place=True writes back after a workspace.snapshot (an implicit undo checkpoint) and that otherwise no document is touched. It also explains the coordinate space and integer serialization of results. It stops short of stating auth/permission or rate-limit behavior, but for a local document tool that gap is minor.

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?

Front-loads the one-sentence purpose, then uses a clean action-to-parameter mapping that is scannable despite the length. Length is justified by 12 actions and 12 parameters, though the return-shape sentence and the ``centre`` duplication note add some low-value bulk.

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 12-parameter tool with no annotations, the description covers the operation set, coordinate space, serialization, in-place write semantics, and even return fields (redundant with the output schema). The main missing piece is how the source drawing (``text``/``doc_id`` vs current selection) is supplied, which an agent still has to guess.

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 0% across 12 parameters, so the description must compensate, and it largely does by tying dx, dy, factor, origin_x/origin_y, axis, angle_deg, index, and in_place to concrete behaviors (e.g. factor default 1.0 for simplify/round, origin defaulting to bbox centre). It leaves ``text`` and ``doc_id`` unexplained, so the input-source mechanism for the drawing itself remains unclear.

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?

States a specific verb and resource ('Transform a drawing') and then enumerates every supported operation (translate, scale, rotate, mirror, reverse, flatten, simplify, round, etc.), so an agent can determine exactly what the tool is capable of. The general-purpose transform role is distinguishable from narrower siblings like ass_scale_drawing or ass_drawing_bbox.

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?

Provides strong per-action context by mapping each ``action`` value to the parameters it consumes, which tells the agent how to drive the tool. It does not, however, name alternatives or state when a sibling such as ass_scale_drawing or ass_set_drawing should be preferred, so routing between overlapping tools is left to inference.

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