showWorkflow

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

Goes well beyond the annotations by disclosing that the result is an interactive canvas where the user can move, rename, edit and delete nodes, plus the timing of when the canvas should be (re)shown. Mild tension remains with readOnlyHint=true, since the description advertises user-driven editing without clarifying whether those canvas edits flow back to the agent or require a separate editWorkflow call.

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?

Three tight sentences, front-loaded with the capability, followed by when-to-call and when-not-to-call; the trailing tag is the only cosmetic overhead. Every sentence carries decision-relevant information.

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 single-parameter display tool with no output schema, the entry is nearly complete: it covers purpose, timing, and the alternative. The one unresolved point is what the agent should expect after the canvas opens (e.g. whether user edits are persisted or must be re-applied via editWorkflow).

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% and the single parameter (workflow_id) is fully documented in the schema, so the baseline applies. The description adds nothing about the id itself and does not say whether it accepts a draft id versus a published workflow id.

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?

States a specific verb and resource ("Show a workflow ... as an interactive canvas in the chat") and adds the distinguishing detail that the output is a live UI surface with movable/editable nodes. This clearly separates it from getWorkflow (read the draft) and editWorkflow (mutate the model).

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?

Gives explicit trigger conditions ("when the user asks to see a workflow", "once after you finish building or changing one"), an explicit anti-pattern ("Do not call it before every edit"), and names the correct alternative for that case (getWorkflow). Nothing is left to inference.

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