Write a plugin's source

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

Annotations only declare destructive=true and idempotent=false; the description adds substantial beyond that: the write is journaled and reversible via undo_writes, js/plugins.js is untouched unless enable is set, enable adds/switches the plugin and fills parameters from @default header values, the header must be written first, and a running game requires a restart. This is rich, non-obvious behavioral disclosure.

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?

Front-loaded with the action and target path, then organized around the gotchas (no compile step, journaling, enable behavior, restart). Dense but nearly every clause carries operational signal; slightly long, though little is wasted.

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 multi-parameter write with no output schema and a nested parameters object, the description covers reversibility, side effects on js/plugins.js, the header-order dependency, and the restart requirement. It could be marginally clearer that text is the complete file contents, but the essentials for correct invocation are present.

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 coverage is only 50% (text and enable are undescribed), so the description carries real weight: it defines the enable semantics (list insertion vs. toggling on) and describes how parameters are populated from header defaults and overridden. name and text are inferable from the path reference and the 'source file' framing, giving an overall above-baseline lift.

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?

Opens with a specific verb+resource and exact target path: 'Create or replace `js/plugins/<name>.js`'. An agent immediately knows this is a full-file write of a plugin source, distinct from read_plugin_source or patch_plugin. It also anchors the concept by comparing to Unity's manage_script.

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?

It gives strong operating context ('MZ plugins are plain JavaScript loaded at boot, so there is no compile step') and explains the enable-to-list path, but never routes the agent explicitly between this and siblings like patch_plugin, enable_plugin, or read_plugin_source. Usage is implied rather than stated as when/when-not.

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