Install a userscript into Tampermonkey

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

Annotations supply only readOnlyHint=false, so the description carries the real burden and does so well: it discloses the @name-based de-duplication rule, the measured underlying behavior (saveScript creates a new script per uuid), and the return value (assigned uuid). It omits failure modes (missing header, fetch error on url) and permission/enablement requirements, keeping it out of the 5 tier.

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?

Three tight sentences, front-loaded with the action, followed by input modes and then the de-duplication rationale. The 'because MEASURED saveScript creates a NEW script for every new uuid' aside is slightly jargon-heavy but justifies a non-obvious behavior rather than padding.

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 three-parameter mutation with no output schema, the description covers input modes, idempotency semantics, and the return value, which is most of what an agent needs. It leaves an ambiguity around zero-required-parameter invocation and around error behavior when the @name header is absent or the url fetch fails.

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 100% and each parameter already has a clear description, so the baseline is 3. The description clarifies that code and url are alternatives and that the url path fetches over HTTP first, but it largely restates the schema and never addresses the fact that all three parameters are optional yet at least one of code/url is effectively required.

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 ('Install (or update) a userscript') plus the mechanism ('handing its source to Tampermonkey saveScript'). The install/update framing and the Tampermonkey-specific naming make it easily separable from siblings like browser_tampermonkey_list, browser_tampermonkey_remove, and browser_tampermonkey_set_enabled.

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?

Explains the two input modes ('Pass code for a whole userscript, or url to fetch one over HTTP first') and when duplication occurs versus update. It does not explicitly state prerequisites such as Tampermonkey being installed/enabled, nor point to sibling tools for listing or removing scripts, so it stops short of full when/when-not guidance.

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