ims_command

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

Annotations already declare destructiveHint=true, openWorldHint=true and non-idempotency, so the safety profile is covered. The description does add one genuinely new behavioral fact — that writes are 'gated' — but it never explains how the gate works (is approve_write required first? what happens on rejection?), nor what the command can affect on a live IMS system.

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?

Two short sentences, front-loaded with the action and the console routing, with no filler. The three example commands are mildly redundant with the schema example but serve as a quick syntax anchor, so the cost is small.

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 destructive, open-world write tool with no output schema this is thin: it never says what an agent must do to satisfy the 'gated' requirement, what a rejection looks like, or how follow-up messages relate to collectKey. Parameter documentation is fully handled by the schema, but the operational flow around the gate is missing.

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 description coverage is 100%, so all four parameters are already documented, including the slash-normalization rule and the collectKey follow-up mechanism. The description's command examples and slash prefix note largely restate the schema, so the baseline 3 applies.

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 (issue an IMS command) and the channel it flows through (z/OS system console), which is more than the bare name conveys. It does not distinguish itself from the sibling issue_console_command, so an agent cannot tell from this text alone which console-facing tool to pick.

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 parenthetical '(gated write)' implies the tool is behind an approval flow, and the three example commands sketch the intended use. But there is no explicit when-to-use / when-not-to-use guidance and no pointer to the alternative issue_console_command or to approve_write, leaving the choice to inference.

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