df_write_dimension_group

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

Annotations already declare readOnlyHint=false, destructiveHint=true, and idempotentHint=true, so the safety profile is covered. The description adds that primary_key is 'the source object of the group's key column,' which is modest behavioral context. It does not contradict the annotations and adds no disclosure about destructive replace behavior beyond what the schema's mode description already states.

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 short sentences with minimal waste, and the 'WRITES TO DATAFORGE' warning is front-loaded. However, that opening phrase is largely redundant with the tool's name and the rest of the sentence, and the primary_key clarification is so terse ('source object of the group's key column') that it is somewhat cryptic rather than illuminating.

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 9-parameter mutation tool with nested objects, no output schema, and destructive semantics, the description is thin. It does not clarify when dimension_group_id is needed (presumably for replace/update modes), how this cooperates with runtime membership tools like df_set_group_dimensions, or what the effect of omitting optional fields in each mode is. The schema covers some of this, but the description itself leaves an agent under-informed for correct invocation.

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 67%, with mode, primary_key, idempotency_key, project_id, and version_id already described. The description adds one meaningful clarification—that primary_key is the source object of the key column—which goes slightly beyond the schema's 'physical location' phrasing. But it adds nothing about underscripted parameters like dimension_group_id, name, or dimensions.

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: 'Create, replace or update a dimension group.' This clearly identifies the write operation and resource type. However, it does not differentiate from sibling tools like df_set_group_dimensions or df_write_dimension beyond the resource name itself, so an agent could still conflate related write 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?

There is no guidance on when to use this tool versus alternatives such as df_set_group_dimensions (for membership changes) or df_bulk_write_dimensions. No conditions, exclusions, or prerequisites are stated—the description only says what the tool does, not when to choose it. The 'WRITES TO DATAFORGE' opener adds no usage context.

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