Scale Shape

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

Beyond the sparse annotations, the description discloses important behavior: it produces a standalone Part::Feature, breaks parametric history, hides the source object because its geometry is consumed, and scales about the origin when center is omitted. This gives an agent a strong model of side effects and semantics beyond the annotations.

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 core action, then covers side effects, parameters, and return contract in a compact structured form. Every sentence adds necessary information: units, defaults, pivot behavior, and volume calculation. It is detailed without being redundant.

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 tool has no output schema and sparse annotations, so the description carries full weight. It explains inputs, defaults, side effects, output fields, units, and how the returned factor and volume relate to the source shape. Nothing needed to invoke it correctly is missing.

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?

With schema description coverage at 0%, the description fully compensates by explaining every parameter: handle, factor as scalar or per-axis array with positivity constraint, optional center pivot with origin behavior, and name default. It also clarifies units and return values, so an agent can construct valid calls without schema help.

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: 'Scale a shape uniformly or per-axis, baking a fresh static solid.' It also distinguishes itself from parametric or linked features by explaining it produces a standalone Part::Feature and hides the source object, making its role clear relative to sibling shape 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?

The description gives clear behavioral context: scaling breaks parametric history and consumes the source geometry into the scaled copy. It does not explicitly name an alternative tool or say 'use this instead of X,' but the side-effect warning effectively tells an agent when this tool is appropriate versus a parametric/transform approach.

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