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

No annotations are provided, so the description carries the full burden. It discloses the return contract in detail (text vs. base64 blob, field names), which is valuable, but says nothing about whether the call is read-only, what happens on an invalid path, or any permission/rate constraints. Decent disclosure of output shape, silent on operational behaviour.

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?

Front-loaded with the purpose, then the agent-relevant routing warning, then Args/Returns blocks. Every line earns its place, though the explicit Returns block is partly redundant with the existing output schema.

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 single-parameter read tool with an output schema, the definition covers purpose, the source of the path argument, the exclusion for agents, and the return shape. Only failure/error behaviour and the absence of side effects remain unstated.

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 coverage is 0% and the single parameter is bare ('path: string'), so the description must compensate. It does: 'A path from the "files" of a diagram result' tells the agent where the value is sourced from, which is the key semantic an agent needs and is not present in the schema.

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?

States a specific verb and resource ('Return a rendered diagram file's contents') and names the consumer ('to the TerraVision view'), which is clearer than most siblings like render_graph or open_diagram_file. It does not explicitly contrast itself against those siblings, so it stops short of a 5.

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?

Gives an explicit 'when' ('Used by the diagram view in chat apps to load the SVG and the graph JSON') and an explicit 'when not' ('Agents do not need it: read the paths in the result yourself'). This directly routes an agent away from the tool and toward an alternative behaviour, which is exactly the guidance dimension's purpose.

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

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

With no annotations, the description carries the full burden and does well: it discloses the content returned (rules, examples, node types, setup checks), the environment prerequisites (Graphviz, Git, Terraform), and the intended downstream behavior (base the graph on the closest example and keep its level of detail). It does not mention auth or rate limits, which is a minor gap for a read-only reference tool.

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 critical instruction is front-loaded ('Read this once before calling render_graph'), but the middle sentence is a long, tangled clause chain that splices the setup/install check into the list of returned content, hurting readability. The information mostly earns its place, but the structure is not clean.

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?

An output schema exists, so return values need no explanation, and the description still covers what is returned, the usage flow, and drafting guidance. Together with the schema, an agent has enough to call this correctly, though behavioral edges like pagination or error behavior are unaddressed.

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 coverage is 100% and the schema already documents both parameters, including that 'pattern' names an entry from the patterns list. The description's 'call again with pattern to get one' largely restates the schema, adding only the two-phase usage framing, so the baseline 3 is appropriate.

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 states a specific verb and resource: it returns TerraVision graph rules, worked example graphs, per-provider node types, and setup/install status. It clearly positions itself as the prerequisite reference tool before render_graph, though it only differentiates itself from that one sibling and not from the other diagram-generating tools.

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?

It explicitly says to read it once before calling render_graph, and explains the second mode: call again with 'pattern' to fetch a specific pattern graph. It also gives conditional action guidance (if Graphviz or Git is missing, tell the user what to install before drafting a diagram).

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

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

With no annotations, the description carries the behavioral burden and does well: it discloses that Terraform is actually run, variables resolved, count/for_each expanded, and connections inferred, plus a performance shortcut via tfdata.json. It omits credential/permission requirements (cloud credentials are only implied by the planfile/graphfile schema notes) and any failure modes.

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?

Front-loaded with the core verb and resource, then progressively narrower detail (processing, use case, return shapes). Every sentence earns its place, though the explicit return-shape paragraph is somewhat redundant given the output schema exists.

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 complex 9-parameter tool with no annotations, the description covers what the tool does, how heavy it is, the alternative rendering path, and the two return variants. The presence of an output schema means return values needn't be spelled out, so the remaining gap (credentials/auth requirements) is minor.

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 100%, so the schema already documents all nine parameters well, including services_only's guidance and the planfile/graphfile no-credentials case. The description adds little parameter-level detail beyond restating the with-services_only return shape, so the baseline of 3 applies.

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?

Names a specific verb (extract) and resource (cloud architecture of Terraform code) and describes the concrete processing performed: running Terraform, resolving variables, expanding count/for_each, grouping into VPCs/subnets/AZs. It also differentiates from siblings by stating the diagram tools render this same graph.

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?

Gives clear context ('use it to reason about an architecture') and positions the diagram tools as the rendering alternative rather than a duplicate. It also flags the fast path ('A tfdata.json source skips Terraform and returns in seconds'), but does not state explicit when-not conditions beyond that.

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

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

With no annotations, the description carries the full burden and does well: it discloses the underlying terraform init/plan execution, the credential requirement, the multi-minute latency on first call, and the bypass when planfile+graphfile are given. It omits whether files are overwritten or whether repeated calls are idempotent.

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?

Opens with the core action, then layers prerequisites, latency, and return shape in a short, well-ordered block. Given 18 parameters, four tight paragraphs with no filler is proportionate.

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?

No output schema exists, yet the description enumerates the return keys and explains what 'files' and 'path' contain, plus the preview image. Combined with the schema's 100% coverage, an agent has everything needed to call this correctly despite the missing annotations.

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 100% and the per-parameter descriptions are already unusually rich (flows, outfile naming, planfile/graphfile interaction), so the schema does the heavy lifting. The description adds only the usage cue for flows and the .tvg.json node-naming note, which is a marginal gain over structured 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?

States a specific verb and resource ('Render an architecture diagram from Terraform code to a file') and clarifies the diagram is derived from `terraform plan`, so it reflects real deployments. It nods at render_graph as the re-render path, but never distinguishes itself from generate_architecture_graph or generate_interactive_html, which appear to overlap.

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?

Gives concrete conditions: cloud credentials are required unless planfile and graphfile are supplied, and a first call can take minutes because it runs `terraform init`/`plan`. It also advises when to add flows ('when the user asks how requests or data move'). It stops short of saying when to pick this tool over the sibling generators.

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

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

No annotations are provided, so the description carries the full burden, and it does real work: it discloses that the page is self-contained, works offline with no server, and that nodes are clickable and searchable. It stops short of stating credential/permission requirements for the Terraform execution path, which the schema hints at but the description never connects.

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?

Front-loaded with the purpose and behavioral traits, and every sentence about interactivity and prerequisites earns its place. The closing return-value line ({"path", "provider"}) is redundant given an output schema exists, a minor waste.

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 14-parameter tool with a 100% documented schema and an output schema, the description supplies what the structured fields cannot: the interactivity/offline nature, the human-exploration use case, and the sibling routing. Nothing essential to calling it correctly is missing.

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 100%, so the schema already documents all 14 parameters, including the //folder Git URL syntax, varfile behavior, and provider-credential-free planfile/graphfile paths. The description adds no parameter-level detail beyond implying Terraform code is required, which is the correct baseline when the schema does the heavy lifting.

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?

States a specific verb and resource ("Render a self-contained interactive HTML diagram") plus the key property that makes it distinct (interactive, offline, for a human to open). It explicitly contrasts itself with the sibling render_graph for JSON graphs, so an agent can route without opening either schema.

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?

Gives an explicit when-to-use condition ("when someone wants to explore an architecture themselves rather than read a static picture") and names the alternative for the adjacent case (render_graph with format "svg" for a JSON graph). It also states the prerequisite (needs Terraform code).

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

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 per-extension behavior (.png image viewer, .draw.io), the browser fallback when draw.io is not installed, the reveal alternative, the session-scoped path restriction, and the resulting side effect of launching an external app. This is far more than the schema provides.

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?

Front-loaded and free of filler, but the mid-sentence line break before 'Only files returned by...' and the terse, jargon-y phrase 'the result then has browser' slightly obscure an otherwise efficient block of text.

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?

An action tool with real side effects is fully covered: allowed inputs, per-type behavior, the reveal variant, and return keys ('opened', 'reveal', optional 'browser') are all stated. An agent has everything needed to call it correctly, and the output schema only reinforces what is described.

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 coverage is 0%, so the description must compensate, and it does: 'path' is defined as a path from the 'files' of a render_graph or generate_diagram result, and 'reveal' is defined as showing the file in its folder instead of opening it. Both parameters gain meaning absent from the bare schema.

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?

States a specific verb and resource ('Open a rendered diagram file for the user on their own computer'), including where the action happens. It is immediately distinguishable from sibling producers like render_graph and generate_diagram, which create the files rather than open them.

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?

Gives explicit when-to-use ('when the user asks, or when a diagram result's "display" says the app has no diagram view') and an explicit exclusion ('never when "display" says the app is already showing the diagram'). It also restricts inputs to files returned by render_graph or generate_diagram in this session.

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

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.

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.

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.

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.

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.

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.