create_detail_line

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

Without annotations, the description explains that detail lines are view-specific and 2D, and requires a valid view type. However, it does not disclose potential side effects, error conditions (e.g., invalid view name), or authorization requirements, leaving gaps in transparency for a creation 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 starts with a clear one-line purpose, followed by contextual prose, then a structured Args list. It is informative and well-organized, but could be slightly more concise by merging some redundant statements. Still effective and front-loaded.

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 4 parameters (2 required) and no output schema, the description covers parameter meaning, view restrictions, and the distinction from model lines. It does not document return values or error behavior, but for a straightforward creation tool, it provides sufficient context for an AI agent to use it correctly.

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 has 0% coverage, so the description fully carries the burden. It explains each parameter's role, format (including coordinate component keys and units in mm), and defaults (view_name defaults to active view, line_style uses default style if omitted), adding substantial 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 specifically identifies the tool as creating a detail line for annotation in Revit, clarifying it is view-specific and 2D, distinguishing it from model lines. It also specifies valid view types (plan, section, detail), leaving no ambiguity about 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 states that lines appear only in the view where created and must be in a plan, section, or detail view, providing clear context. While it contrasts with model lines, it does not explicitly name alternative tools like create_line_based_element or provide when-not-to-use guidance, slightly reducing completeness.

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