df_write_dimension

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

The annotations already declare destructiveHint=true and idempotentHint=true, so the baseline is lower. The description adds valuable behavioral detail: 'mode=replace (PUT) overwrites it and RESETS every optional field you do not pass' and 'mode=update (PATCH) changes only the fields you pass.' This clarifies the destructive semantics beyond the annotation flags.

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 compact and front-loaded, with the critical 'WRITES TO DATAFORGE' header followed by a mode-by-mode breakdown. Each sentence contributes essential information, and the reset vs. patch distinction is clearly separated. No filler or repetition.

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 complexity (25 params, nested connected_source object, no output schema), the description covers the core mode logic but omits several practical details: what the response returns, the behavior of idempotency_key (only in schema), and guidance on which optional fields are relevant to dimensions. It is adequate for basic create/replace/update calls but not fully complete for all edge cases.

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 32%, so the description should compensate. It explains mode and dimension_id semantics, but 25 parameters exist and most optional fields (e.g., required, relevance, visibility, value_options, display_data_type) receive no explanation in either the description or the schema. The description adds meaning only to a small subset of 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: 'WRITES TO DATAFORGE. Create, replace or update a dimension in a project version.' It clearly distinguishes itself from sibling write tools by naming the target resource (dimension) and the three supported operations. The mode breakdown makes the tool's 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 gives clear context for choosing among create, replace, and update modes, including that 'replace and update require dimension_id.' However, it does not explicitly address when to use this tool versus siblings like df_write_measure, df_bulk_write_dimensions, or df_delete_dimension. The intended usage is implied but not explicitly differentiated.

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