tag_elements

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

Despite no annotations, the description discloses key behaviors: tags are placed on elements, auto-detects tag type if omitted, uses default active view, and explains parameters like offset in mm. It does not mention potential side effects or prerequisites (e.g., elements must exist in the view), but overall provides sufficient transparency for a non-destructive annotation 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 concise and well-structured: a one-line purpose, a brief behavioral summary, then a clear list of parameters. Every sentence adds value, and the key information is front-loaded. The inclusion of 'ctx' is minor but acceptable.

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 most aspects for a tool of this complexity: it explains all 6 parameters, works with common categories, and auto-detects tag types. However, it does not mention potential errors (e.g., invalid element_ids) or what the tool returns (no output schema). Slight gaps remain, but overall adequate.

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 has 0% description coverage, but the tool's description fully compensates by detailing each parameter in the 'Args' section, including types, defaults, and units (e.g., offset as '{"x": float, "y": float} in mm'). This adds substantial meaning beyond the schema's 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 tool's purpose: 'Tag elements with annotation symbols in a view.' It specifies that it places tags displaying element properties like type name, mark, or room name/number, and works with specific categories (walls, doors, windows, rooms). This distinguishes it from the sibling 'tag_walls' tool, which presumably targets only walls.

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 usage context by listing compatible element categories ('walls, doors, windows, rooms, and other taggable categories'), but it does not explicitly state when not to use this tool or mention alternatives like 'tag_walls'. Without such guidance, the agent may not know to choose the more specific tool when appropriate.

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