Create Flow

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

Beyond the single destructiveHint=false annotation, the description discloses important behavior: placeholder component keys are accepted, real UUIDs are minted, references are rewritten, the mapping is returned as componentIds, and validation runs on creation. It does not state what happens if validation fails (for example, whether a partial flow is created) or what permissions are required, so it falls short of full behavioral disclosure.

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: creation and validation come first, followed by prerequisites, key-rewriting semantics, and next steps. Every sentence carries information needed to call 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?

For a create tool with a nested object schema and no output schema, the description explains ID minting and the componentIds mapping but not the full return shape, such as the created flow ID or how validation errors are surfaced. It is adequate but leaves meaningful gaps around outcomes and failure behavior.

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, but the description adds non-obvious meaning for the `flow` parameter: keys may be readable placeholders rather than UUIDs and are remapped to real IDs. This materially changes how an agent should construct the input, though other parameters such as `stage` and `custom_fields` are left to the schema.

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 first sentence gives a specific verb and resource ("Create a new Appmixer flow") and adds the validation behavior, which clearly distinguishes it from update_flow, clone_flow, and start_flow. An agent can identify the operation without opening the schema.

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 explicitly names prerequisites and sequencing: read get_flow_authoring_guide first, use get_components for exact types/ports/fields, fix errors with update_flow, then use start_flow. It also makes clear the flow is created stopped, so the agent knows not to expect execution.

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