add_isolated_release_webresource

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false, so the safety profile is known. The description adds genuinely new behavior: content and membership validation occur before the write, and native dependencies are NOT auto-added — context an agent needs before calling with acknowledge_dependencies. It still omits what the destructive path actually modifies and whether acknowledge_unprotected_write is mandatory.

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?

A single front-loaded sentence with no filler; every clause carries information. It is dense to the point of being terse for a 13-parameter destructive tool, but nothing is redundant.

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, non-idempotent tool with 13 parameters (8 required), no output schema, and near-zero schema documentation, one sentence is not enough. The agent cannot determine profile-parameter relationships or the meaning of the two acknowledge_* flags from this definition alone.

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 only 8% across 13 parameters, so the description bears most of the burden and largely fails. It obliquely gestures at dry_run ('Preview'), content_hash ('content checks'), current_members ('membership checks'), and acknowledge_dependencies ('native dependencies'), but says nothing about source_profile vs target_profile vs isolated_profile, resource_id vs resource_name, or expected_hash vs content_hash.

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 gives a specific verb pair ('Preview or add'), a specific resource ('one reviewed JavaScript resource'), and a specific destination ('a dedicated isolated solution'). This distinguishes it from parallel siblings such as add_isolated_release_field and add_isolated_release_choice, which target different component types, though it never names those siblings explicitly.

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?

'Preview or add' hints that a dry-run mode exists, and 'after content and membership checks' implies prerequisites. However, it gives no explicit when-to-use guidance relative to stage_isolated_webresource_candidate (staging) or publish_isolated_release_component (publication), leaving the agent to infer the position of this tool in the release workflow.

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