ispw_deploy

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

The annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false, so the safety profile is covered. The description adds real value beyond them: it warns that production/target environments are affected and reveals that the call returns an operation ID and status URL, implying an asynchronous job rather than a synchronous mutation.

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 purpose and safety warning are front-loaded well, and the examples section earns its space. However, the opening two sentences restate the same idea ('Deploy ... to target environment' / 'Deploys code to the target environment'), and the Args block largely duplicates descriptions already present in the schema.

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?

An output schema exists, so return values need not be documented, yet the description still mentions operation ID and status URL helpfully. Examples cover the three target types and the scheduling path. What is missing is the async/polling contract and what happens to artifacts already in the target environment, which matters given the destructive hint.

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 reported at 0%, so the description must carry the parameter burden, and it does enumerate every field with types and optionality (srid, target_id, target_type, level, deploy_implementation_time, deploy_active, response_format). The worked examples concretely show correct value shapes, notably target_type='assignment' with a PLAY ID and level='PRD' for releases, which the schema alone does 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?

The description names a specific verb (Deploy) and resource (ISPW assignment, release, or set) plus the destination environment, which is far more precise than a bare 'deploy'. It does not, however, distinguish this from the sibling ispw_promote_assignment, which an agent could reasonably consider an alternative for moving code forward.

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?

'This is typically the final step in the deployment pipeline' and 'Can deploy immediately or schedule for a future time' give useful situational context. There is no explicit 'use this instead of X' routing against ispw_promote_assignment, and no stated prerequisites or conditions under which deployment should be avoided beyond a generic caution.

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