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

With no annotations, the description carries the full burden. It discloses that this is a mutation (applies) and details server-side verification of signature, expiry, single-use, plan checksum, and drift. This gives the agent important context about safety and failure conditions, though it does not describe the response format or exact effects on infrastructure.

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 with zero waste. The primary purpose is stated first, and the security requirements are added in a compact, informative second sentence.

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 mutation tool with security prerequisites and no output schema, the description covers the essential usage context: what it does, when it can be used (with valid approval), and what verifications occur. It is missing details on response/return value and any prerequisites like having a plan already generated, but given sibling tools and the absence of output schema, it is largely complete.

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 explains the purpose of approvalId and approvalToken (minted by human approval, verifies signature/expiry/etc.), but does not explain workspaceId at all. It adds some meaning but leaves a key parameter undocumented.

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 ('runs') and resource ('terraform apply'), and explicitly claims to be the only tool that does so, clearly distinguishing it from siblings. The approval requirement is also front-loaded.

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 makes clear that this is the tool to use when applying a Terraform plan, and its requirement for a valid approval token implies it should only be used after planning and approval. It does not explicitly name alternatives for planning (like tf_plan), but the 'only tool' phrasing provides explicit exclusion of other siblings for apply.

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 of behavioral disclosure. It mentions polling and returning a token once approved, but does not state whether the call is read-only, what happens when approval is still pending, whether it blocks or returns immediately, or if repeated calls are safe. This leaves significant ambiguity for a tool that lacks any annotation context.

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 two sentences with no redundancy. The core action is front-loaded, and the token return is stated clearly. It is concise and structured effectively, though it could be slightly more specific about the pending state.

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 one-parameter tool, the description covers the basic purpose and result. However, it omits details about the response when approval is not yet granted, and without an output schema, the description should clarify the return structure. It doesn't mention whether the call blocks or is a non-blocking poll. These gaps make it only partially complete for an agent to use 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?

The schema has one required parameter (approvalId) with 0% description coverage. The description never mentions this parameter or how it relates to the pending approval. The parameter name is somewhat self-explanatory, but the description does not confirm that approvalId is the identifier of the approval being polled, nor does it clarify the expected format beyond the schema's uuid type. This is a gap since the description should tie the parameter to the tool's purpose.

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 clearly states the action (polls), the target (status of a pending approval), and the outcome (returns a signed approvalToken). The verb and resource are specific and distinguish it from sibling tools like tf_request_approval, which presumably creates the approval. It doesn't explicitly name a sibling, but the function is unambiguous.

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 the tool is for polling a pending approval, which suggests using it after an approval request has been made. However, it doesn't explicitly state when to use it versus alternatives (e.g., tf_request_approval) or provide exclusions. The usage context is implied by the phrase 'Polls the status of a pending approval' but no explicit when/when-not guidance is given.

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 burden. It discloses the skip condition when the API key is unset, which is useful, but does not state whether the operation has side effects, requires a prior plan, or what happens if the API key is missing (e.g., returns null vs error). The description is somewhat opaque about the operational details.

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 a single, efficient sentence that front-loads the primary action and outcome, with the conditional placed as a parenthetical. There is no wasted wording 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?

Given the tool's simplicity (one parameter, no output schema), the description covers the core function and the key conditional, but omits the meaning of workspaceId and any prerequisite like requiring a successful tf_plan. This leaves the agent to guess how to invoke it correctly, warranting a middle score.

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?

The input schema has a single parameter (workspaceId) with 0% description coverage, and the tool description does not mention this parameter at all. The agent receives no meaning about what workspaceId is or how to fill it correctly, leaving a critical gap.

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 clearly states the action ('Runs Infracost'), the target ('against the current plan'), and the output ('returns a monthly cost delta'). This distinguishes it from sibling tools that handle planning, approval, or apply phases, making its purpose unambiguous.

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 implicitly indicates it's for cost estimation after a plan exists, and mentions a conditional (skipped if INFRACOST_API_KEY unset), but does not explicitly say when to use it over alternatives like tf_plan or tf_apply. No explicit 'use this instead of X' guidance is provided.

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 of disclosing behavior. It states that it runs init+plan and returns a summary, but it does not explicitly say whether it modifies any state, requires authentication, or is read-only. An agent might assume it applies changes because it says 'runs'—though plan is typically safe, this is not clarified. The description lacks critical side-effect disclosure.

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 a single sentence that front-loads the action and output. Every word earns its place with no wasted verbiage. It is appropriately concise for a single-purpose tool.

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?

Given the tool's low complexity (one parameter) but no annotations, no output schema, and no parameter explanation, the description is incomplete. An agent lacks information about when to use it, what the change summary looks like in detail, and any prerequisites. The description covers the core action but omits essential usage and behavioral context.

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?

The only parameter is workspaceId, and its schema gives a pattern but no semantic meaning. The description does not mention or explain workspaceId at all. With 0% schema description coverage, the description should compensate, but it fails to clarify what workspaceId refers to or how it is used. This leaves the agent to guess the parameter's purpose.

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 action ('Runs terraform init+plan') and a concrete output ('returns a resource-level change summary'). This clearly differentiates it from siblings like tf_apply (which applies changes) and tf_cost_estimate (which estimates cost). The verb and resource are explicit.

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 this tool is for planning Terraform changes (init+plan) and producing a change summary, which logically precedes tf_apply. However, it does not explicitly state when to use it versus tf_cost_estimate or tf_policy_check, nor does it mention prerequisites like workspace initialization. The guidance is implied rather than stated.

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 must carry all behavioral disclosure. It mentions the conditional execution of OPA/Conftest, but does not state whether the tool is read-only, what happens on policy violations, or if any state is modified. This leaves the agent uninformed about side effects and failure behavior.

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 a single, well-structured sentence that front-loads the main action and output. There is no extraneous information; every word contributes to the understanding of the tool's function.

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?

The tool appears straightforward, but important context is missing: no mention of required dependencies (like a generated plan), how to interpret the report, or error conditions. Given the lack of annotations and output schema, the description should provide more operational context for the agent to use it safely and effectively.

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 by clarifying the parameter's meaning. It does not mention workspaceId at all, leaving the agent to infer its purpose from the name alone. The simple name and pattern offer some hint, but the description adds no value over 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?

The description clearly states the action ('Runs Checkov and OPA/Conftest') against a specific resource ('current plan') and the outcome ('merged policy report'). This distinguishes it from sibling tools like tf_plan or tf_apply, which serve different purposes. No ambiguity about what the tool does.

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 provides no concrete guidance on when to use this tool versus alternatives. It does not mention prerequisites (e.g., a plan must exist), nor does it indicate scenarios where this tool should be skipped. The only hint is the phrase 'if configured', which is not enough to guide selection.

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 provided, the description carries full responsibility. It mentions the composite nature and output recommendation, but does not disclose whether the operation is read-only, if it modifies state, requires special permissions, or has side effects. It also ignores potential failure states or rate limits. This is a significant transparency 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?

Two sentences with no fluff. The first sentence front-loads the core functionality and output, the second gives actionable usage. Every word 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 composite tool with a single parameter and no output schema, the description covers the main purpose and usage. It names the recommendation values and the intent. However, it lacks details on what a Proposal contains, error conditions, or whether state changes occur—gaps that matter for an agent deciding to call it safely.

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?

The description makes no mention of the workspaceId parameter. Schema coverage is 0%, and the description does not compensate by explaining the parameter's purpose or format. The agent gets no guidance beyond the schema pattern, which is minimal.

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 clearly states the tool runs plan, policy check, and cost estimate together and returns a bundled Proposal with a recommendation. It names specific sub-operations and differentiates from sibling tools like tf_plan, tf_policy_check, tf_cost_estimate by framing as a composite. The verb 'runs' and resource 'Proposal' are explicit.

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 provides explicit timing: 'Call this before tf_request_approval.' This gives a clear context and implies when to use it instead of individual tools. However, it does not explicitly state when not to use it or mention alternatives beyond the approval flow, leaving some inference.

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. It discloses the delivery channel (Slack/CLI), the refusal condition (blocking policy), and the return of an approvalId. It does not mention whether the call blocks, side effects, permission requirements, or what happens on failure beyond 'refuses'. While it gives some key behavior, it is not comprehensive for a mutation-like action with no annotation support.

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 a single, readable sentence that efficiently covers the core action, channels, refusal, and return. It front-loads the primary purpose. No redundancy or filler. It is appropriately compact for the information it conveys.

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?

Given there is no output schema and no annotations, the description should provide sufficient context for an agent to call the tool correctly. It explains the overall flow (send for approval, get approvalId), but omits details like what happens if the plan is missing, whether the call is synchronous or asynchronous, error conditions beyond 'refuses', and the exact nature of the returned approvalId (format or type). For a tool that triggers a human approval process, these are important gaps.

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 50%; only overridePolicy has a description, while workspaceId lacks any. The tool description does not clarify workspaceId, nor does it explicitly explain overridePolicy's purpose beyond what the schema already states. The mention of 'Refuses if policy findings are blocking' indirectly relates to policy, but does not map to parameter semantics. The description adds little value over the schema and fails to compensate for the missing workspaceId documentation.

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 clear action ('Sends the current plan for human approval') with the specific resource being the current plan. It also adds useful detail about the two delivery channels (Slack or CLI) and the refusal condition. It does not explicitly distinguish itself from tf_check_approval_status, but the mention of returning an approvalId to poll implies the next step, so the purpose is unambiguous.

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 it should be used after a plan exists and after policy checks (since it refuses on blocking findings). However, it does not explicitly state when to use it versus tf_plan, tf_policy_check, or tf_apply. It mentions returning an approvalId to poll, hinting at tf_check_approval_status but without naming it. This is enough to orient an agent but lacks explicit exclusions or alternatives.

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 present, the description carries the full burden of disclosing side effects and behavior. It says the tool copies/checks out a project into a sandboxed workdir, but it does not state whether an existing workdir is overwritten, whether this operation is destructive, what happens on re-initialization, or whether it creates a new workspace. The term 'sandboxed' hints at isolation but does not clarify the mutation profile.

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 a single efficient sentence with no filler, and the primary action is front-loaded. It is appropriately short for a simple tool, though it is terse enough to omit valuable behavioral details. Structurally it earns its place without 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?

Given no annotations, no output schema, and a non-trivial setup operation, the description is incomplete for safe and correct invocation. It does not explain what a successful initialization returns, how the workspaceId relates to the sandboxed workdir, or whether an empty workspace can be created (which the schema's sourceDir description does mention). An agent would need to infer too much about prerequisites and side effects.

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 only 50%, and the description does not compensate for the gap. workspaceId has no description beyond a regex pattern, and the tool description does not clarify its role as the target workspace identifier. sourceDir is explained only in the schema, not in the tool description, so the description adds no parameter-level meaning beyond what structured fields already provide.

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 clear action — checks out or copies a Terraform project into a sandboxed workdir — with a specific resource and destination. It distinguishes this setup tool from the planning/apply/write siblings by implying workspace preparation, though it does not explicitly name an alternative. The compound verb 'checks out/copies' is slightly ambiguous but still conveys the purpose.

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 provides no guidance on when to use this tool versus alternatives such as tf_write_file or tf_plan. There is no mention of prerequisites, ordering, or exclusions. The only usage hint is the schema's note about omitting sourceDir to create an empty workspace, which is parameter-level guidance rather than tool-selection guidance.

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 must carry the behavioral disclosure burden. It discloses that writes go into a sandboxed workspace, which is useful, but it does not mention whether the write overwrites an existing file, how paths are validated, or what side effects occur. The core write behavior is clear, but edge behaviors are not.

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?

A single, front-loaded sentence conveys the operation, resource type, and usage context with zero waste. The parenthetical adds relevant context without 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 simple three-parameter write tool, the description gives enough to understand the primary action. However, it omits return value behavior, overwrite semantics, and path restrictions. Since there is no output schema and no annotations, these omissions are noticeable but not fatal for a straightforward write operation.

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, but it gives no parameter-level detail. The parameter names (workspaceId, relativePath, content) are self-explanatory and the tool name reinforces the write-file purpose, but the description does not define path semantics or content formatting.

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 uses a specific verb (Writes) and resource (.tf/.tfvars file), and scopes the write to a sandboxed workspace. This clearly differentiates it from all sibling tf_* workflow tools, none of which perform file writes.

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 parenthetical '(for agents with no native filesystem access)' gives an explicit condition for when this tool is appropriate. It does not name alternatives or exclusion cases, but no sibling tool competes for the same write-file role, so the guidance is sufficient.

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