gtm_update_tag

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

Annotations are absent, so the description carries the full burden of behavioral disclosure and provides almost none. It omits critical traits: the update requires a valid fingerprint for optimistic concurrency (a stale fingerprint fails the write), and in GTM the change is applied to the workspace draft, taking effect only after a version is created or published. The schema hints at locking via the fingerprint parameter, but the description itself adds no behavioral context beyond the literal meaning.

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 single sentence 'Updates an existing tag in GTM' is front-loaded with the verb and resource and contains zero filler. It is efficiently structured, though given the optimistic-locking constraint and six required parameters, the sentence could earn its place further by hinting at the fingerprint prerequisite.

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 six required parameters, a nested tag object, an optimistic-locking fingerprint, no output schema, and no annotations, a one-sentence description is incomplete. An agent is left unaware that a prior read is needed to obtain the fingerprint and that the edit affects a workspace draft requiring version creation/publishing. The GTM lifecycle context that would make this callable correctly is entirely absent.

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 83%, above the 80% threshold, so the baseline of 3 applies. The schema already documents the four ID parameters and the fingerprint ('Tag fingerprint for optimistic locking'), and the description contributes no additional parameter meaning. The nested 'tag' object's sub-properties lack descriptions, but their names (name, type, paused, firingTriggerId, blockingTriggerId) are largely self-explanatory; the description doesn't fill that gap either.

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 'Updates an existing tag in GTM' uses a specific verb and resource, and 'existing' correctly signals that the tag must already be present, distinguishing it from siblings like gtm_create_tag, gtm_get_tag, and gtm_delete_tag. It is unambiguous for basic CRUD routing, though it adds nothing beyond the bare action and doesn't differentiate update semantics from gtm_update_trigger or gtm_update_variable.

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?

No guidance is given on when to use this tool versus alternatives. The description doesn't tell an agent to fetch the tag first (via gtm_get_tag or gtm_list_tags) to obtain the required fingerprint, nor does it contrast update with create for tags that don't exist yet. With six required parameters and a cluster of adjacent CRUD tools, the when-to-use decision is entirely left to inference.

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