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

The description claims the proposal id is a durable idempotency key and that retries return the same run, but annotations declare idempotentHint=false. This is a direct contradiction between the described behavior and the annotation metadata, which the scoring rules treat as a serious failure.

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 well-structured: it states the action, explains the input-resolution rule, covers idempotency, and describes the two relevant HTTP statuses. Every sentence adds useful information without padding.

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 covers the key operational behaviors: input selection, idempotency, asynchronous completion, and conflict handling. It does not mention how to track the resulting run or what a successful response body contains, but for a fire-and-forget async build tool the provided context is largely sufficient.

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 coverage is 100%, so the baseline is 3. The description adds meaningful semantics beyond the schema by explaining that transformation_proposal_id defaults to the process's live proposal and acts as an idempotency key, giving the agent a better understanding of how the parameter controls execution.

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 clearly states the tool's function: handing an automation proposal off to the workflow-builder pipeline and building an automation from a proposal. It is specific about the resource and action, though it does not explicitly differentiate itself from sibling tools like createAutomation or updateAutomation.

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 provides clear context on how the tool selects its input: it uses transformation_proposal_id when supplied, otherwise the process's live proposal. It does not explicitly state when to use this tool versus alternative automation-creation tools, but the parameter-selection logic is clear.

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