Skip to main content
Glama

draw_state_diagram

Create UML state diagrams from specified states, start/end nodes, choices, and transitions; render a PNG and return validation errors so layouts can be corrected.

Instructions

상태도를 그려 PNG와 입력 파일로 저장하고, 검사 결과와 그림을 함께 돌려준다. 시작·끝 점, 상태, 선택 마름모를 전이로 잇고, 상태 안에 상태를 넣는다(복합 상태). 요소는 준 왼쪽 위(left·top) 그대로, 전이는 준 꺾는 점(via)을 따라 그리고, 요소 크기·선 끝·전이 글자 자리만 도구가 정한다. 좌표는 px이고 y는 아래로 커진다.

입력 필드는 인자마다 붙은 설명에 있다.

결과

  • 글: 검사 결과, 요소마다 그린 자리(열쇠와 왼, 위, 폭×높이), 저장한 그림·입력 파일 경로와 그림 픽셀 크기. 자리를 그대로 다음 입력에 넣으면 요소가 움직이지 않는다.

  • 그림: 저장한 PNG. 긴 변이 1568px를 넘으면 그 길이로 줄여 돌려준다(저장한 그림은 줄이지 않는다).

  • 입력 파일: 그림 옆 <file_name>.cysuml.json에 그린 도구 이름(tool)과 이 입력(out_dir만 빼고)을 저장한다. 있던 그림을 고칠 때는 이 파일을 읽어 고친 뒤 out_dir에 그 폴더를 주어 tool의 도구로 다시 그린다 — 그대로 넣으면 같은 그림이 나온다(tool은 도구가 무시한다).

  • elements·relations·file_name이 틀리면 그리지 않고 틀린 곳을 elements[0].left 꼴 자리와 함께 모두 모아 오류로 돌려준다. 시작 점으로 들어오거나 끝 점에서 나가는 전이는 그 밖의 입력이 맞을 때 따로 모아 알린다. 그림이 너무 커서 PNG로 그릴 수 없거나 저장할 폴더에 쓸 수 없을 때도 오류로 돌려준다.

AI가 배치하는 그림(클래스도·패키지도 등)을 그리는 흐름 — 검사에 합격할 때까지 되풀이한다:

  1. 요소(클래스도에서는 상자)의 자리(left·top)와, 필요하면 관계선의 꺾는 점(via)을 정해 그린다.

  2. 돌려받은 검사 결과와 그림을 본다. 불합격 항목마다 걸린 요소, 자리(논리 좌표 왼, 위, 폭×높이), 고치는 법이 붙는다. 고치는 법은 종류마다 다르니(요소를 옮긴다, 꺾는 점을 고친다, 두 요소를 떼어 놓는다 등) 항목에 적힌 대로 고친다.

  3. 고친 입력을 같은 file_name으로 다시 그린다(파일을 덮어쓴다). 관계 이름은 도구가 그 관계의 선 위에 얹는다(이름 앞뒤로 선이 끊긴다). 얹을 빈 자리가 없는 이름(선이 짧아 이름 앞이나 뒤에 선이 거의 보이지 않을 때도)과 같은 요소로 돌아오는 선의 이름은 선 옆에 두고, 얹으면 그림 전체에서 걸리는 곳이 더 많아질 때는 모든 이름을 선 옆에 둔다. 다중도는 선 끝 옆에 둔다. 선끼리 엇갈린 곳, 표기 규칙 알림(관계 규칙이 있는 도구에서 뜻을 확인해 볼 관계), 그림 크기는 알림이라 불합격이 아니다. 다만 엇갈림은 적을수록 읽기 좋다.

불합격(선이 요소나 글자를 지나는 등 문서에 넣을 수 없는 그림) 14가지: 요소끼리 겹치거나 붙음, 안의 요소가 바깥 요소의 칸 밖으로 나가거나 테두리·이름 칸에 붙음, 선이 그 선과 상관없는 요소를 지나감, 선이 끝 요소의 몸통 밖 자리(이름 칸 등)나 끝을 품은 요소의 이름 칸을 지나감, 선이 끝을 품은 요소의 테두리를 따라감, 선이 끝 요소 테두리에 붙어 감, 선 끝 모양이 그 선의 다른 끝 요소 테두리에 붙음, 선 끝 모양이 그 끝의 요소 안으로 들어감, 선끼리 포개지거나 선이 왔던 길을 되짚음, 선이 선 끝 모양에 닿음, 선 끝 모양끼리 겹침, 선이 선 글자(관계 이름·다중도 등)를 지나감(이름이 얹힌 그 관계의 선 구간은 빼고), 선 글자가 요소에 겹침, 선 글자끼리 겹침.

상태도 배치 요령:

  • 시작 점을 위나 왼쪽에 두고, 전이가 한 방향(위에서 아래나 왼쪽에서 오른쪽)으로 흐르게 상태를 차례로 놓는다.

  • 되돌아가는 전이는 꺾는 점(via)으로 상태들 바깥을 돌게 한다 — 곧게 그으면 가는 전이와 포개지거나 다른 상태를 지난다.

  • 같은 상태로 돌아오는 전이(자기 전이)는 상태 오른쪽 변 25px 밖에 꺾는 점 둘(상태 가운데 높이에서 12px 위와 12px 아래)을 준다 — 선이 오른쪽 변에서 비스듬히 나갔다 들어오는 고리가 된다. 윗변 가운데와 오른쪽 변 가운데로 드나드는 다른 전이가 없으면 꺾는 점 셋(상태 가운데 x로 윗변 30px 위, 그 높이로 오른쪽 변 25px 밖, 그 x로 상태 가운데 높이)으로 오른쪽 위 모서리를 도는 네모 고리로 그려도 된다.

  • 선택 마름모로 가는 전이와 거기서 갈라지는 전이는 마름모 꼭짓점으로 곧게 들고 나게 둔다(가로·세로 선은 꼭짓점에 닿는다).

  • 복합 상태 안의 요소는 이름 칸 아래에 둔다. 복합 상태 안의 상태와 밖의 상태를 잇는 전이는 이름 칸을 지나면 불합격이니, 복합 상태의 왼쪽·오른쪽·아래 테두리로 건너게 둔다.

  • 요소 사이는 전이 글자가 들어갈 만큼 띄운다. 가로 80px·세로 60px쯤에서 시작하고, 글자가 길면 더 띄운다.

  • 요소 크기는 도구가 글자와 안의 요소에 맞춰 늘린다. 그린 크기는 결과의 "요소 자리"에서 보고 다음 입력에 쓴다.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "file_name": "<file_name>",
      "elements": "<elements>"
    },
    "name": "draw_state_diagram"
  }
}

Input Schema

NameRequiredDescriptionDefault
scaleNo출력 배율(기본 1.6, 0.25 이상). 보통은 주지 않는다.
out_dirNo저장할 폴더. 주지 않으면 서버 작업 폴더 아래 diagrams/이고, 상대 경로도 서버 작업 폴더 기준이다.
elementsYes- elements: 요소 목록(하나 이상). - kind(필수): "initial"(시작 점 — 검게 칠한 원), "final"(끝 점 — 과녁 모양), "state"(상태 — 둥근 모서리 상자), "choice"(선택 — 마름모). - name·id: "공용 입력(열쇠·이름)" 절. 상태는 name(필수)을 쓴다. 시작·끝 점과 선택은 이름이 없어 name 대신 id(필수)를 준다. - left·top(필수): 자리의 왼쪽 위. - actions: 상태의 동작 칸 줄 목록. 이름 아래 칸에 받은 그대로 쓴다 — "entry / 초기화"·"do / 감시"·"exit / 정리"처럼 앞말도 쓴다. - in: 이 요소를 품은 상태(복합 상태)의 열쇠. "요소 안에 요소 두기(중첩)" 절. - width·height: 상태 자리의 최소 크기. 글자와 안의 요소에 맞춰 더 늘어난다. 시작 점(지름 20px)·끝 점(지름 24px)·선택 마름모(30×30px)는 크기가 정해져 있다. - 상태의 이름 칸은 위쪽에 이름 줄과 동작 칸을 함께 덮는다. 높이는 이름 한 줄이면 40px이고, 이름 줄이 하나 늘 때마다 15px, 동작 칸이 있으면 10px에 동작 줄마다 15px를 더한다. 복합 상태 안의 요소는 이 칸 아래에 둔다(이름 한 줄·동작 없는 상태면 top + 60부터). 공용 입력(열쇠·이름): - id: 요소의 열쇠. 관계의 from·to와 in이 이 열쇠로 요소를 가리킨다. 주지 않으면 한 줄 이름이 곧 열쇠다. 이름이 여러 줄이거나 이름이 없는 요소, 이름이 같은 요소는 id를 준다. 열쇠는 서로 달라야 한다. - name: 한 줄이면 문자열, 여러 줄이면 줄마다 문자열인 목록(["주문", "관리"]). 도구는 줄을 나누지 않으니 긴 이름은 목록으로 나눈다. 한 줄 안에 줄바꿈 글자는 넣지 못한다. 관계 name도 여러 줄 목록을 받는다. - 관계의 stereotype: «» 없이 이름만(include·extend·deploy·manifest·use 등). 관계 종류를 새로 만들지 않고 어느 관계에든 단다 («deploy»는 의존에). 관계 이름 위 줄에 쓴다. 요소 안에 요소 두기(중첩): - 안의 요소에 in으로 품은 요소의 열쇠를 준다. 여러 겹도 된다. 좌표는 늘 그림 전체 기준이다. - 바깥 요소는 준 왼쪽 위에서 시작해, 안의 요소를 여백 20px를 두고 덮도록 오른쪽·아래로 늘어난다(바깥 요소의 이름 칸이 들어갈 크기보다 작아지지 않는다). 그래서 안의 요소는 바깥 요소의 칸(안의 요소를 두는 곳) 왼쪽·위 테두리에서 20px 이상 들여 놓는다. - 선의 끝 요소를 품은 바깥 요소는 그 선이 안을 지나거나 테두리를 건너도 된다. 다만 테두리를 따라가거나 이름 칸을 지나면 불합격이다. 그 선의 글자도 바깥 요소 안에 놓일 수 있다. 그 밖의 요소는 선이 지나가면 불합격이다. - 품은 요소와 그 안의 요소는 선으로 잇지 않는다.
file_nameYes저장할 파일 이름(확장자 없이). 그림(.png)과 입력 파일(.cysuml.json)에 쓰고, 같은 이름이면 둘 다 덮어쓴다.
relationsNo- relations: 전이 목록(없어도 된다). - kind: "transition". 관계 종류가 하나뿐이라 빼도 된다. - from·to(필수): 요소 열쇠. 화살촉은 늘 to 쪽에 붙는다. 시작 점은 from에만, 끝 점은 to에만 쓴다. - name: 전이 글자. "사건 [조건] / 동작" 꼴을 받은 그대로 쓴다 — 대괄호·빗금도 쓴다(도구가 씌우지 않는다). 길면 줄마다 문자열인 목록으로 나눈다. stereotype: elements 인자 설명의 "공용 입력(열쇠·이름)" 절. - via: 꺾는 점 [[x, y], …]. 선은 요소 가운데에서 첫 꺾는 점(없으면 상대 요소 가운데)으로 가는 선이 요소 테두리와 만나는 곳에서 시작한다. 같은 상태로 돌아오는 전이(자기 전이)는 꺾는 점이 둘 이상 있어야 한다. 화살촉 쪽 끝 구간을 꺾을 때는 그 꺾는 점을 요소 테두리에서 20px 이상 뗀다(앞 구간이 화살촉 쪽으로 비스듬히 되돌아오면 더 뗀다) — 화살촉 길이(10px)만큼만 떼면 꺾은 앞 구간이 화살촉 갈래 끝에 붙어 불합격이다.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.6/5.0
Behavior5/5

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

With no annotations, the description carries the full burden and does so: it discloses what is written to disk (<file_name>.png and <file_name>.cysuml.json, overwriting on name collision), the default out_dir, the 1568px downscale of the returned image versus the unscaled saved file, and precise error behavior (nothing is drawn; all errors are collected with locations like elements[0].left; unreachable initial/final transitions are reported separately). It goes further by enumerating the 14 disqualifying conditions and separating them from non-failing warnings (crossings, notation notices, size), which is exactly the behavioral context annotations would otherwise supply.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Length is high, but it is front-loaded (what it does, then '결과', then the drawing loop, then layout tips, then the failure list) and each block serves the iterate-until-valid workflow rather than repeating the schema. The 14-item failure enumeration is the weakest section for size, yet it is the checklist the fix loop depends on, so the bulk is largely earned.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 5-parameter tool with no output schema and no annotations, the description covers everything an agent needs: the shape of the returned text/image/file, error and warning semantics, nesting rules, auto-sizing of elements, and the redraw-from-saved-input path. Nothing material about invoking it correctly or interpreting its result is left to inference.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3; the description adds genuine meaning beyond it by fixing the coordinate system ('좌표는 px이고 y는 아래로 커진다') and by stating that positions fed back unchanged from '요소 자리' produce an unmoved element, which ties the output fields to the input semantics. It otherwise defers to per-argument schema text ('입력 필드는 인자마다 붙은 설명에 있다'), which is honest but leaves the core parameter detail in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The first sentence names a specific verb and artifact: '상태도를 그려 PNG와 입력 파일로 저장하고, 검사 결과와 그림을 함께 돌려준다' — draw a state diagram, persist PNG plus input file, return validation results and the image. The resource ('상태도', with initial/final/state/choice/composite-state vocabulary) cleanly separates it from the sibling draw_*_diagram tools without needing to name them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It supplies an explicit iterate-until-passing workflow (place elements → read failures and their fix instructions → redraw with the same file_name to overwrite), plus concrete when-to guidance inside '상태도 배치 요령' (route back-transitions via via points, self-transitions at 25px outside the right edge, how to keep transitions to/from choice diamonds straight). It never states an explicit when-not or names a sibling as the alternative, so it stops short of 5.

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