Create Workflow Run

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

Annotations already declare readOnlyHint=false, openWorldHint=true, idempotentHint=false, and destructiveHint=false, so the safety profile is covered. The description adds no behavioral context of its own — nothing about side effects of creating a run, whether runs can be duplicated on retry (non-idempotent), or what happens when workflow conditions fail.

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?

One short sentence with no filler, but the brevity reflects under-specification rather than tight editing; the sentence is not front-loaded with the details an agent actually needs to invoke the tool correctly.

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 is structurally complex — two required params, a nested discriminator-style anyOf, and no output-schema concern — yet the description covers none of that complexity. For a create operation with an open-world, non-idempotent profile, the definition leaves an agent guessing at the key linkage semantics.

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 50%, and the description supplies none of the missing meaning. Most importantly, it never explains that `data.attributes` is a union requiring exactly one of incident_id, post_mortem_id, action_item_id, alert_id, or pulse_id — a semantic an agent cannot easily infer and the single sentence ignores.

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 names a specific verb and resource ('Creates a new workflow run'), so an agent can tell this is a write operation on the workflow-run resource. It does not differentiate from siblings such as list_workflow_runs, create_workflow, or create_workflow_task, and 'from provided data' adds little.

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 versus list_workflow_runs or create_workflow, no preconditions (e.g., the workflow must exist / be enabled), and no mention of when a run should be created with a linked incident, alert, or pulse. Usage must be inferred entirely from the schema.

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