TerraVision

by patrickchugh

Overview Schema Source Related Servers Discussions Admin

Python

Local

diagram_guide

Read this once before calling render_graph.

Instructions

Read this once before calling render_graph.

Returns the TerraVision graph rules (types to prefer, containers, what is drawn and what is hidden), worked example graphs, every node type for the provider, and in "setup" whether Graphviz, Git and Terraform are installed: if Graphviz or Git is missing, tell the user what to install before drafting a diagram. Base your graph on the closest example and keep its level of detail: availability zones, public and private subnets, NAT gateways routed to the internet, and shared services in their group. It also lists the gallery, 19 architect-designed diagrams per cloud (streaming, MLOps, IoT, hybrid networks, multi-region, SaaS, payments, security and more); call again with example to get one with its CIDR ranges, labels and flows. And it lists patterns (EKS, SageMaker, Step Functions, GKE, AKS and more) drawn from TerraVision's output for real Terraform; call again with pattern to get one.

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": {
      "provider": "<provider>"
    },
    "name": "diagram_guide"
  }
}

Input Schema

Name	Required	Description
`example`	No	Name of a design from the "gallery" list, to fetch its graph with its title, CIDR ranges, arrow labels and flows as render_graph arguments.
`pattern`	No	Name of a pattern from the "patterns" list, to fetch that graph.
`provider`	Yes	"aws", "azure" or "gcp". One provider per diagram.

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv0.56.0Oct 22, 2026

addedInput schema / properties / example

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Name of a design from the \"gallery\" list, to fetch its graph with its title, CIDR ranges, arrow labels and flows as render_graph arguments.",
+  "title": "Example"
+}

First observedv0.52.0Oct 4, 2026

TDQS

A4.1/5.0

Behavior4/5

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

With no annotations, the description carries the disclosure burden and does so well for a read-only reference tool: it reveals that it probes the local environment (Graphviz, Git, Terraform) and prescribes a user-facing action when prerequisites are absent. It also implies repeat calls are cheap and expected for drill-down. It stops short of 5 only because it never explicitly frames the operation as read-only/non-mutating.

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

Conciseness3/5

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

Front-loaded correctly with the key instruction, but bloated in the middle: the 19-design topic enumeration ("streaming, MLOps, IoT, ... security and more") is low-value filler, and the trailing "And it lists patterns..." sentence has a tacked-on feel. The length is partly justified by the multi-part return, yet several clauses could be trimmed without losing signal.

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

Completeness4/5

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

An output schema exists, so the heavy return-value narration is technically surplus, but it usefully tells the agent how to act on the setup result and how to follow up with the drill-down parameters. Between the schema and the description, an agent knows what comes back and what to do next; only the read-only nature goes unstated.

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, but the description adds real meaning: it explains that "example" and "pattern" must be names drawn from the gallery/patterns lists this same call returns, and that the returned example carries CIDR ranges, labels and flows. That sequential relationship between the no-arg call and the parameterized call is not derivable from the schema alone.

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?

States precisely what it returns: TerraVision graph rules, worked examples, node types per provider, install status in "setup", plus gallery and pattern lists. It names the sibling it serves (render_graph), so the agent can place it in the workflow. It falls short of 5 because the tool bundles several distinct resources (rules, setup check, catalog, drill-down) without a single crisp verb+resource framing.

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?

Gives explicit sequencing: "Read this once before calling render_graph", then "call again with example" or "call again with pattern" to drill into a specific entry. It also tells the agent what to do with the setup result (tell the user what to install if Graphviz or Git is missing). Nothing about when to invoke it, or with which parameter, is left to inference.

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

Deploy Server