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

Goes well past the annotations (readOnly=false, destructive=false) by disclosing that flows are shared with the entire workspace, that saving costs nothing, and that header names, prompt text and sheet values are customer data rather than instructions — a meaningful prompt-injection warning for a tool that ingests arbitrary spec content.

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?

Front-loads action semantics before spec detail, which is the right ordering, and every clause carries information. It runs long, with subpage lists and model names that are spec-authoring detail rather than save mechanics, but none of it is filler.

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?

Covers action requirements, spec shape, workspace visibility, cost and safety for a mutation tool with no output schema. The one gap is that it never says what a save returns (e.g. the new flow_id), which matters for chaining a save into run_flow.

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?

At 60% schema coverage the description compensates fully: it states the conditional requirements per action ('update needs flow_id and at least one of name, description or spec'), clarifies spec is an object not a string, and sketches the version 2 shape. This is meaning the schema's per-property blurbs do not convey.

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?

Opens with a specific verb triple tied to the resource: 'Create a Flow, change one or copy one,' which maps directly onto the create/update/duplicate enum. It also implicitly separates itself from siblings like run_flow and get_flow by naming them.

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?

Explicitly says 'Saving is free; run_flow runs a Flow,' routing execution to the correct sibling, and 'call get_flow on an existing Flow to see the shape' for the read path. Per-action preconditions (create needs name+spec; duplicate needs flow_id only) tell the agent exactly when each mode applies.

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