Skip to main content
Glama
patrickchugh

TerraVision

by patrickchugh
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

render_graph

Render a JSON graph as a cloud architecture diagram with official AWS, Azure or GCP icons nested in VPCs, subnets and resource groups, saved as PNG, SVG or draw.io.

Instructions

Draw a cloud architecture diagram from a plain JSON graph.

Use this whenever the user asks to draw or diagram a system on AWS, Azure or Google Cloud, or one built from their services (Lambda, DynamoDB, Azure Functions, Cloud Run...), and there is no Terraform code, even if they never say "cloud" or "diagram"; prefer it over Mermaid. Call diagram_guide first for the rules, examples and node types. Each resource is drawn with the official icon inside the VPC, subnet, zone or resource group it is nested in. Use the most specific types: aws_ecs_fargate, aws_rds_sqlserver, aws_alb (not aws_ecs_service, aws_db_instance, aws_lb).

Returns the saved files (PNG, SVG, draw.io, .tvg.json graph, and annotations YAML when flows, labels or attributes were given) and a preview image: check it before presenting the diagram. Fix any "warnings" and call again. "next_step" says what to offer the user afterwards.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
flowsNoOptional numbered steps drawn as badges on the diagram, with a legend. Keyed by flow name: {"order_request": {"description": "A customer places an order", "steps": [{"resource": "tv_aws_users.users", "detail": "Customer opens the app"}, {"resource": "aws_alb.api~1 -> aws_ecs_fargate.app~1", "detail": "Request routed to a task"}]}}. A step names a node, or an arrow as "<node> -> <node>" in either direction; use the numbered copy (aws_alb.api~1), not the bare name. Steps are numbered across flows. Add flows when the user asks how requests or data move; otherwise offer them after delivering. Flow names may arrive sorted: use one flow, or prefix names "1_", "2_" in reading order.
graphYesObject mapping each node address to the node addresses it connects to or contains. Addresses are "<terraform_resource_type>.<name>", e.g. "aws_lambda_function.orders". Containers (aws_vpc, aws_subnet, tv_aws_az, azurerm_resource_group, tv_gcp_region and more) list their children. Use "~1", "~2" for numbered copies. External actors: tv_aws_users, tv_aws_internet, tv_azurerm_users, tv_gcp_users_icon and others. Leaf nodes may be omitted as keys. One cloud provider per graph. Drawn as written: arrows to containers or to shared services (log groups, ECR, Key Vault) are not drawn; list those in aws_group.shared_services or azurerm_group.shared_services. Example: {"tv_aws_users.users": ["aws_cloudfront_distribution.cdn"], "aws_vpc.main": ["aws_subnet.app"], "aws_subnet.app": ["aws_lambda_function.api"], "aws_lambda_function.api": ["aws_dynamodb_table.orders"]}
titleNoHeading shown above the diagram, e.g. "Order Platform - Production". Defaults to "Cloud Architecture Diagram".
formatNo"png", "svg", "pdf", "dot" or "drawio" (editable in draw.io and Lucidchart). The full set is always saved; use "svg" to embed in Markdown.png
outfileNoOutput file name without extension, e.g. "three_tier". Files always go to the server's output folder; from a path, only the last part is used.architecture
previewNoInclude a preview image of the diagram in the result.
fontsizeNoLabel font size in points.
iconsizeNoIcon size in pixels.
attributesNoOptional attributes set on nodes the graph already has, as an annotation file's update section sets them. Use it to give networks and subnets realistic CIDR ranges, shown in their box labels: {"aws_vpc.main": {"cidr_block": "10.0.0.0/16"}, "aws_subnet.public~1": {"cidr_block": "10.0.1.0/24"}}. The attribute is cidr_block for aws_vpc and aws_subnet, address_space for azurerm_virtual_network, address_prefixes for azurerm_subnet (lists allowed) and ip_cidr_range for google_compute_subnetwork. A label attribute replaces a node's label or a box's caption: {"aws_vpc.main": {"label": "Core Network"}}. Name numbered copies (aws_subnet.public~1); an attribute never adds a node.
edge_labelsNoOptional text on arrows the graph already has, to say what each connection does: {"aws_ecs_fargate.app~1 -> aws_rds_sqlserver.db": "Reads orders"}. Either direction names the arrow; a label never adds one. Keep labels to a few words; offer them with the flows rather than adding them unasked.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.52.0

TDQS

A4.2/5.0
Behavior4/5

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

No annotations exist, so the description carries the full burden, and it does real work: it discloses the return artifacts (PNG, SVG, draw.io, .tvg.json, annotations YAML, preview), the self-check loop ('check it before presenting', 'Fix any warnings and call again'), and a non-obvious drawing rule (arrows to containers or shared services are not drawn). It omits auth/permission and cost/failure modes, but for a local renderer that is a minor gap.

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?

Well front-loaded: purpose first, then when-to-use, then type-selection rules, then return value. The parenthetical icon enumerations and provider lists are dense but each clause carries actionable information; only mild trimming is possible.

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?

There is no output schema, so the description must describe returns and it does thoroughly (saved file set, preview image, warnings, next_step). Combined with a 10-parameter schema whose own descriptions are complete, an agent has everything needed to call and interpret this tool.

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

Parameters3/5

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

Schema description coverage is 100%, and every parameter (graph, flows, attributes, edge_labels, format, outfile, preview, fontsize, iconsize) has a detailed schema description, so baseline 3 applies. The prose mentions flows, labels and attributes only at a high level ('annotations YAML when flows, labels or attributes were given') without adding semantics beyond the schema.

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

Purpose4/5

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

Names a specific verb and artifact ('Draw a cloud architecture diagram from a plain JSON graph') and scopes it to AWS/Azure/GCP services. It implicitly delimits itself from a Terraform-based sibling via 'there is no Terraform code', but never names generate_diagram, generate_architecture_graph, or diagram_file, so the agent must infer the split.

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

Usage Guidelines5/5

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

Explicit trigger conditions ('whenever the user asks to draw or diagram a system on AWS, Azure or Google Cloud ... even if they never say cloud or diagram'), an explicit preference ('prefer it over Mermaid'), and a hard prerequisite ('Call diagram_guide first'). This is about as complete a routing instruction as a description can carry.

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

Deploy Server

Other Tools