create_diagram

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

With no annotations, the description carries the burden of behavioral disclosure. It reveals that it dispatches to a type-specific diagram tool and states it returns a file path or error message. However, it does not explain side effects like whether files are always written to disk, how output_path interacts with the current workspace, or what error conditions may occur.

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 with a purpose sentence, a short routing explanation, an Args list, and a Returns line. It is efficient and front-loaded. The only minor redundancy is that 'any type of diagram' is followed by an explicit type list, but that list is practically useful.

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?

For a tool with a nested free-form data object and no per-type schemas, the description gives a reasonable high-level overview and points to list_diagram_types, but it does not explicitly instruct the agent to use that tool to learn data structures. The output schema covers return shape, but the per-type data requirements remain a notable gap.

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 0%, so the description must compensate. It usefully enumerates the diagram_type values and explains theme, title, and output_path. The required 'data' parameter, however, is only described as 'Diagram-specific data (varies by type)', which is too vague to guide an agent in constructing valid input without further lookup.

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 clear verb and resource: 'Create any type of diagram with a single unified tool.' It goes further by explaining that it routes to specific diagram tools via the diagram_type parameter, which distinguishes it from the many type-specific siblings like create_flowchart or create_sequence_diagram.

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 establishes clear context for when to use this tool: it is a convenience router that handles many diagram types from one entry point, and it points to list_diagram_types for available types. It does not explicitly state when to prefer a specific sibling tool, but the routing explanation makes the general-purpose use case clear.

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