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

Annotations already declare readOnly/no-destructive/idempotent/closed-world, so the safety profile is covered. The description adds real behavioral value beyond that: validation happens against the PINNED schema, and the tool flags unknown, read-only and deprecated paths. It does not describe error handling or prerequisites, but the added disclosure is substantial.

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 verb and purpose, followed by one illustrating example and a short second sentence on detected conditions. No filler; every clause carries information.

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?

With no output schema, the description usefully indicates what comes back (flags for unknown/read-only/deprecated paths) and when to invoke it. It leaves "PINNED schema" and result shape (list vs error) partly undefined, but remains usable for a 4-param, fully-documented read-only 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%, so all four parameters (dir, kind, arguments, type_name) are already documented in the schema. The description's example path mainly restates the schema's "dotted paths; nested blocks separated by '.'" convention, adding only marginal meaning.

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 (validate) on a specific resource (argument / nested-block paths) and gives a concrete example path, so the tool's role is unambiguous. It is clearly distinct from siblings like tf_get_schema or tf_search_types, which retrieve rather than check paths.

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?

"before writing them" gives an explicit timing/context for when to call this tool, which is genuinely useful guidance. It stops short of naming alternatives or stating when-not to use it (e.g. vs tf_get_schema for a full schema dump).

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?

Annotations already cover readOnly/idempotent/non-destructive, but the description adds real behavioral value: attributes are pinned to the provider version, computed (read-only) attributes cannot be set, and unlisted arguments do not exist. That materially shapes how an agent writes config after calling this.

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?

Three dense sentences, front-loaded with the core action and the pre-write instruction. Every sentence carries information, with only the trailing kind enumeration being a partial restatement of the schema default.

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 read-only introspection tool with fully documented parameters, the description covers purpose, timing, and the key constraint about computed attributes and unlisted arguments. No output schema exists, yet the description gives no hint of the returned structure beyond 'arguments and nested blocks,' a minor 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 100%, so the schema already documents dir, kind, max_depth, type_name and description_chars. The description only echoes the kind enum values, adding nothing new about the other four parameters. 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?

States a specific verb+resource: returns exact arguments and nested blocks for one type at the pinned provider version, which is clearly distinct from tf_search_types (discovery) and tf_check_arguments (validation). It does not explicitly name those siblings, so the differentiation is inferable rather than stated.

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?

'Use BEFORE writing or editing any resource/data/ephemeral block' gives an explicit timing and trigger condition. It also sets the hard constraint 'only arguments listed here exist.' It stops short of naming an alternative tool or a when-not-to-use condition.

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?

Annotations already declare readOnlyHint/idempotentHint/destructiveHint=false, so safety is covered. The description adds genuine behavioral context beyond that: the data source is .terraform.lock.hcl and it lists only providers locked in THIS directory, which is real scope information. It stops short of describing return format or handling of uninitialized directories.

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?

Three sentences, all front-loaded and purposeful: what it returns, when to call it, what it does not cover, and where to go instead. No filler or redundancy.

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-only listing tool with no output schema, the description covers the return subject (providers and pinned versions), the scope limitation, and the routing to alternatives. Nothing needed to call 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 coverage is 100%; the single dir parameter already documents its default precedence (TERRAFORM_CWD_MCP_DIR, else server working directory). The description's '(default: cwd)' restates this without adding syntax or edge-case detail, so the baseline 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?

States a specific verb (List) plus resource (providers and their PINNED versions) and scopes it to a Terraform root module defaulting to cwd. It also distinguishes itself from registry search, so an agent can separate it from tf_get_schema or a registry lookup without opening the 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?

Explicitly says 'Call this first' and gives the reason (code should target versions locked in .terraform.lock.hcl, not the latest release). It also states when NOT to use it ('does not search the registry') and names the alternative server and tools (search_provider_docs / get_latest_provider_version).

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?

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint false, openWorldHint false), so the bar is lower. The description still adds useful mechanics: address resolution runs through .terraform/modules/modules.json (so downloaded registry/git modules resolve), and module calls are validated against what is installed. It does not describe failure behavior when a module is missing.

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 highest-value content (what gets returned), and the second sentence carries the exclusion. The first sentence is dense and parenthetical-heavy, but every clause adds a distinct piece of information rather than filler.

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 convey return content, and it does: it lists the variable attributes surfaced and the presence of outputs and module calls. Combined with the read-only annotations and 100%-covered schema, an agent has enough to call it correctly; only error/missing-module behavior is left implicit.

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 all three parameters (dir, module, description_chars) are already documented in the schema. The description restates the module address forms that the schema already covers, adding essentially no syntax or default detail beyond it. Baseline 3 applies 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?

The description names the resource (a module) and enumerates exactly what it returns: variables (with type expression, required/optional, default, sensitive/nullable/ephemeral, validation count), outputs and module calls. The 'in THIS working directory' scope is a real differentiator, though no sibling tool (e.g. tf_get_schema or tf_check_arguments) is named to sharpen the boundary.

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 states the when (root, local module directory, or installed module address resolved via modules.json) and the when-not with an explicit alternative: 'For public registry modules you have not installed, use the official terraform MCP server.' That is a complete routing rule for an agent deciding between tools.

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?

Annotations already declare the full safety profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint=false), so the description is not the primary carrier of behavior. It adds the useful scoping fact that the search covers only the *pinned* providers, but says nothing about result ordering, caps, or what happens on no match beyond the schema's limit default.

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?

Two short sentences, front-loaded with the action and match semantics; the trailing 'kind: resource | data | ephemeral' is a compact enumeration with no filler. Every clause earns its place.

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 simple name-search tool with no output schema, the description covers the search semantics, scope (pinned providers), and result kind. The return value (a list of matching type names) is self-evident, and safety is fully covered by annotations, so nothing an agent needs to call 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 four parameters (dir, kind, limit, query) including defaults and bounds. The description restates only `query` and the `kind` enum, adding no syntax or format meaning beyond the structured fields. Baseline 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?

States a specific verb ('Find'), the exact resource being searched (resource/data source/ephemeral type names), the matching semantics (substring of `query`), and the scope ('in the pinned providers'). This is distinguishable from siblings like tf_list_providers (lists providers, not type names) and tf_get_schema (fetches a schema for a known type).

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 implies when it is useful (locating a type name by substring), which is clear context, but it never states when not to use it or names the alternative for getting details once a name is found (e.g. tf_get_schema). Usage is inferable rather than explicit.

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?

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered; the description still adds real value by specifying 'never locks, never refreshes' and detailing the redaction policy (Terraform markers, equal values, secret-like names/shapes) plus a footer explaining what was hidden. That is genuine behavioral context beyond the 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?

Three tightly packed sentences: identity and source first, then safety, then redaction behavior. Every sentence carries information an agent needs, with no filler.

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 helps by explaining the read-only nature and the redaction footer that accompanies results. It could say a bit more about result shape (e.g., flattened attribute list, truncation), but it is largely complete for a single-resource read 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 coverage is 100%, so all four parameters (dir, address, include_null, max_value_chars) are documented in the schema with defaults and constraints. The description adds no parameter-level syntax or format information beyond this, so the baseline 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?

States a specific verb and resource ('Show one resource instance's attribute values') plus the exact source ('from the current Terraform state (terraform show -json)'). This clearly distinguishes it from siblings like tf_state_addresses, which would list addresses rather than dump an instance's attributes.

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?

Usage is implied rather than stated: the address parameter description points to tf_state_addresses as the source of a valid address, suggesting a follow-on workflow. However, the description itself never says when to use this over alternatives or any when-not conditions. Adequate but with a clear gap.

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?

Annotations already declare readOnly, idempotency and non-destructiveness, yet the description still adds real value: it says it never locks or refreshes, reads S3/GCS/HCP with the server's credentials, and refuses a non-default workspace that does not exist to avoid creating it. These are non-obvious behavioral traits beyond the annotation set; the one gap is no note on pagination/truncation relative to the limit parameter.

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?

Three tight sentences with the core purpose front-loaded and no filler; the remote-backend and workspace caveats follow in decreasing order of importance. Every sentence earns its place.

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, but the tool returns a simple address list, and the description plus annotations cover safety, backend access and the workspace-refusal edge case. A brief note on return shape or large-state truncation would complete it, but nothing essential for correct invocation 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 coverage is 100%, so the schema already documents all four parameters, including the filter substring syntax and id. The description only mirrors this ('optionally filtered') without adding format or edge-case detail, 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?

States a specific verb and resource ('List resource instance addresses in the current Terraform state') and equates it to the known 'terraform state list' command. This is clearly distinguishable from every sibling (providers, types, schema, check_arguments, summarize_plan, module_interface, show_resource, upgrade_impact), which all address different resources.

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 conveys context ('optionally filtered', remote-backend behavior) but never states when to choose this tool over an alternative such as tf_show_resource for inspecting state. There is no explicit when/when-not guidance, so usage is only implied.

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?

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds substantive behavior beyond that: it prints no values, truncates sensitive paths, and omits import IDs, plus it flags that destroy output names renames requiring a moved block. It stops short of describing error behavior when neither plan_file nor plan_json is supplied.

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?

Two sentences, purpose front-loaded before the input discussion, and nearly every clause carries distinct information (section inventory, input provenance, output redaction). It is dense to the point of being clause-heavy, but there is little that could be cut without losing signal.

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?

With no output schema, the description carries the return-value burden and does: it lists the report sections and states that sensitive values are truncated and import IDs omitted. With zero required parameters it still tells the agent which input to pass and where that input comes from, so an agent has enough to call it correctly.

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%, so the baseline is 3, but the description adds real meaning for the two plan inputs: plan_file is a binary from `terraform plan -out` rendered with `terraform show -json` in `dir`, or a plan JSON file, while plan_json is JSON text typically sourced from a specific sibling HCP server call. dir, max_paths, and max_per_section are left to the schema, which documents them adequately.

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?

Opens with a specific verb+resource ("Summarize a saved Terraform plan") and then enumerates exactly what the summary contains: deletes/replaces with the forcing attribute, updates with changed paths, creates, imports, moves, forgets, drift, output changes, and a destroy warning about renames needing a moved block. That level of detail makes it unmistakable versus siblings like tf_state_addresses, tf_show_resource, or tf_upgrade_impact, which all cover different resources or phases.

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?

Clearly states the invocation context: supply plan_file or plan_json, and it names the concrete upstream source of plan_json (the official terraform MCP server's get_plan_json_output(plan_id), with plan_id from get_run_details), which is genuine routing guidance. It does not state when this tool should *not* be used (e.g. for planning an unsaved change, or for examining a single resource, where tf_show_resource would be the pick), so it stops short of explicit exclusions.

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?

Goes well beyond the readOnly/idempotent annotations: it discloses a registry download into a cache, that only temp dirs are written and 'never touches dir', that validation runs on a temp copy, and that the operation becomes offline once the target is downloaded. That is exactly the network/disk side-effect context an agent needs and would not infer from the 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 impact question is front-loaded, the mechanism follows, and the external-tool routing is last. Three dense sentences with no repetition of schema text and no filler.

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?

With no output schema, the description must carry the return-value burden and it does not describe what the impact report contains (format, severity, per-module grouping). Everything else an agent needs — scope, side effects, prerequisites (initialized dir), routing — is present, so the gap is narrow.

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%, so the baseline is 3, but the description adds real meaning: 'this configuration uses' clarifies the default include_unused=false scope, and 'confirms with terraform validate on a temp copy' ties to the validate flag. The 'exact version, not a constraint' intent is also reinforced in prose. It does not, however, explain the dir fallback behavior in the body.

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?

Opens with a specific verb+outcome ('what breaks if a pinned provider is upgraded/downgraded to an exact version'), then names the exact comparison scope (arguments, nested blocks, attribute reads, root and installed modules). An agent can tell it apart from tf_get_schema or tf_check_arguments without opening any 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?

States the trigger context (impact of a version change) and explicitly routes one adjacent need elsewhere: 'For the latest version number or upgrade guides, use the official terraform MCP server.' It does not distinguish itself from the sibling tools (tf_get_schema, tf_check_arguments), so no siblings-specific exclusions are given.

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