Run a runbook in Octopus Deploy

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

Annotations already indicate destructiveHint=true and readOnlyHint=false. The description adds valuable behavioral details: the tool runs operational processes, the default snapshot behavior, and the necessity of the confirm parameter to prevent accidental runs. This goes beyond annotations by explaining the execution flow.

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 extremely concise, using three short sentences and a bullet-like structure. The first sentence immediately conveys the core action, and subsequent sentences add essential details without fluff. Every sentence earns its place.

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?

Given the tool's complexity (16 parameters, no output schema), the description covers the most critical aspects: default behavior, tenancy, scheduling, and confirmation. However, it does not describe return values or post-run behavior, which would be helpful for an agent. The presence of annotations offsets some gaps.

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?

All 16 parameters are fully described in the schema (100% coverage). The description adds a summary of key parameters (snapshot, tenancy, confirm) but does not provide new information beyond what the schema already offers. It marginally enhances understanding through contextual grouping.

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 clearly states 'Run a runbook against one or more environments' with a specific verb and resource. It elaborates that runbooks execute operational processes (DB backups, smoke tests, etc.), distinguishing them from deployment tools like deploy_release. This makes the purpose unambiguous and distinct from siblings.

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 provides concrete usage context: default uses published snapshot, tenanted runs require tenants/tags, and a confirm parameter for non-elicitation clients. However, it does not explicitly state when to avoid this tool or mention alternatives, leaving room for improvement in comparative guidance.

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