다이어그램 그리기

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

With annotations only declaring readOnlyHint=false/idempotentHint=false/destructiveHint=false, the description carries the full burden of behavioral disclosure and delivers richly. It reveals that the tool uploads to Velog (mutation), that a self-check can refuse to upload and explain the problem, that this gate cannot be disabled, and that rejected outputs are also barred from velog_upload_image. It also discloses auto-layout mechanics (browser-measured node width, canvas, line bends, label positions). This is exactly the kind of value annotations don't provide. No contradiction with 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 longer than average but every block earns its place: purpose first, then mechanics, then the rejection gate, then style tips, then the two value enumerations. The icon/tone lists are verbose but essential since they're the sole source of valid values. The '밋밋하게 나오면 입력이 밋밋한 것이다' (dull input yields dull output) line is a memorable editorial touch that conveys a real constraint.

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?

There is no output schema, so the description correctly states the return contract: 'returns markdown to attach to the post body.' For a complex tool with 10 parameters and nested structures, the description covers the key decision-critical behaviors: auto-layout, rejection gate, and upload semantics. The post_id and subtitle parameters are documented in the schema, so their omission from the description is acceptable.

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 only 50%, so the description must compensate, and it does. It enumerates the valid icon values (alert arrow bell bolt ... terminal user) and tone values (slate gray blue ... rose indigo), which appear nowhere in the schema. It explains the coordinate philosophy ('origin can be anywhere — canvas auto-fits'), how w is measured when omitted, and how to use groups/planes for visual grouping. It adds real semantic value beyond the schema fields.

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 opens with a specific verb-resource pair: 'Draws a configuration/flow diagram, creates a PNG, uploads to Velog, returns markdown.' This clearly distinguishes a diagram-generation tool from the write/read/post siblings. However, it does not explicitly differentiate from the render_* siblings (velog_render_sequence, velog_render_cover); the distinction is only implicit via '구성도·흐름도' (architecture/flow diagram). It does reference velog_upload_image explicitly, which helps.

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 strong how-to-use guidance: give coordinates and let the renderer auto-layout, use icons/tags/groups/planes for a hand-drawn look, align y for straight lines, and expect rejection if the self-check fails. What's missing is explicit when-to-use vs alternative routing — it never says 'for sequence diagrams use velog_render_sequence' or 'for covers use velog_render_cover.' The velog_upload_image mention is only negative (rejected outputs aren't accepted there).

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