Enable built-in variables (🟡 write)

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

Annotations already declare this is a non-read-only, open-world, non-destructive write operation. The description adds useful behavioral context: already-enabled types are harmless, and dry_run=true previews changes. It does not contradict the annotations, though it leaves permission and workspace-default behavior unstated.

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 front-loaded with the purpose and uses only three sentences. The long parenthetical list of types is useful rather than wasteful because the schema provides no enum. It is concise enough for the information conveyed.

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 output schema exists, so return values need not be described. For a write operation with four parameters and no schema descriptions, the description is only partially complete: it explains types and dry_run but omits container and workspace_id semantics. Permissions and open-world implications are partly covered by annotations but not elaborated.

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 carry parameter meaning. It compensates well for the types parameter by listing many valid API types and for dry_run by explaining that true previews changes. However, it does not explain the required container parameter or the optional workspace_id parameter, leaving clear gaps for half the parameters.

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: enable built-in variables by API type. It gives concrete examples (pageUrl, pagePath, referrer, event, etc.), making the operation clear. It does not explicitly differentiate from the sibling gtm_list_built_in_variables, but the enable-vs-list distinction is evident.

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 to use the tool by saying it enables built-in variables, and it notes dry_run=true previews. However, it does not explicitly say when to use this instead of listing variables first, nor does it give any when-not-to-use conditions.

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