Pin a workflow as a tool

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

Annotations already cover the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), so the description's job is to add context. It does: workflows are never exposed by default, unpinning reverses the effect, and the derived tool list is capped. Return-shape detail is absent, but that is minor here.

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 sentences, front-loaded with the action and effect, then the constraint, then the trigger condition. Slightly dense with parentheticals, but every clause carries routing or constraint 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?

With no output schema and full annotation coverage, the description supplies the missing piece — why and when this tool exists relative to writ_run_workflow. Only the workflow vs workflow_id choice and any cap/pagination behavior remain unstated.

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 67% and the description mirrors rather than extends it, restating the pin/unpin toggle and naming the workflow as the target. It adds no disambiguation between workflow and workflow_id, and the undocumented workflow_id param is left untouched.

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 precise verb pair (pin/unpin) plus the concrete resource and effect: creating a derived run_<name> tool on this server. It explicitly contrasts itself with writ_run_workflow, so an agent can distinguish it from the default invocation path.

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 when-to-use ('when the user asks for it, or after saving a workflow the user clearly intends to call as a tool') and an implicit when-not ('pin only the few… the derived list is capped') plus the named alternative writ_run_workflow for non-pinned use.

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