rush_media_opt

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

With no annotations, the description carries the full burden. It discloses a write side effect ('writes optimized assets with --allow-artifact-write') and the return shape, which is useful. However, it does not explain whether writes modify assets in place, what sanitization entails, or what other permission flags control.

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 a single, efficient sentence that front-loads the main purpose and includes return information without excess. It is appropriately small for the amount of behavioral context it provides.

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?

Despite having an output schema, the tool is complex with 11 parameters and no annotations, so the description must explain more. It omits the required `options` parameter semantics, the purpose of the permission flags, and the meaning of optimize versus sanitize. The return type is covered, but the most confusing invocation details are not.

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 0%, and the description compensates for only path and allow-artifact-write. The required `options` parameter is completely unexplained, and the many boolean flags such as optimize, sanitize, allow_network, and allow_browser receive no semantic clarification.

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 states a specific action ('Audit media assets for CLS and SVG security at <path>') and names the resource and location. The write behavior is also included, making the tool's overall responsibility clear. It does not explicitly differentiate from sibling tools, but the media-asset CLS/SVG focus is distinctive enough.

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?

No guidance is given about when to prefer this tool over alternatives or when not to use it. The description says what the tool does but provides no exclusions, prerequisites, or comparisons to sibling tools such as rush_dead_asset or rush_visual.

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