transform_column

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

The description clearly states that the transformation modifies the column in place and appends a Table.TransformColumns step, which is an important behavioral detail. It also enumerates supported operations, adding transparency without annotations, though it omits error handling or data-type-change effects.

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, front-loaded with a clear purpose and followed by a structured operation list. No filler or redundant restatement of the tool's name.

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 description captures the core behavior, supported operations, and the M-specific implementation, sufficient for selecting and invoking the tool. It lacks details on returned output or failure modes, but the simplicity of the operation narrows the gap.

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 already covers column and partitionName meanings, but the description supplies the critical operation semantics: the full supported operation list, grouped by data type. This is essential because the schema's operation property defers to the description and covers 60% 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 identifies a specific verb ('apply'), resource ('scalar function to a column'), and scope ('single-column', 'in place'), and mentions the underlying M operation. It distinguishes from sibling column tools by emphasizing single-column scalar transforms and listing the operation categories.

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 clear context for when to use—single-column Power Query transforms with a fixed set of scalar functions—and implicitly excludes multi-column operations. However, it does not explicitly name alternative tools or state when-not-to-use, so it stops short of full guidance.

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