Create line

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

Annotations already provide readOnlyHint=false and destructiveHint=false. The description adds context: risk class 'medium (reversible write-new)', mentions rendering and revert options, and explains that the original is untouched. This goes well beyond the annotations.

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-structured but slightly verbose. It front-loads purpose and usage, then details parameters, return shape, example, and risk. However, the return shape explanation is somewhat redundant given the output schema exists, and there is minor repetition (e.g., 'render and look before you trust'). Still clear and effective.

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 9 parameters, 5 required, 0% schema coverage, and the presence of an output schema, the description covers everything: purpose, usage, parameter details, return type with field explanations, example, risk classification, and post-usage actions. It is exceptionally complete.

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 coverage is 0%, so the description fully compensates. It explains each parameter (x1, y1, x2, y2, doc_id, stroke, stroke_width, object_id, parent_id), notes that line is unfilled (no fill), and describes default behavior (unpainted, parent_id default). This adds critical meaning.

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 it creates a line segment with specific endpoints (x1,y1 to x2,y2). It distinguishes from sibling tools like create_polyline (multi-segment open) and create_polygon (closed shape), fulfilling the need for specificity.

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?

Explicitly tells when to use: 'a single straight segment'. Provides direct alternatives: use create_polyline for multi-segment open runs and create_polygon for closed shapes. This gives clear decision guidance.

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