stage_plugin

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

Annotations already declare readOnlyHint=false and openWorldHint=true, but the description adds the crucial behavioral facts: installing executes third-party code on the user's machine, a two-phase confirm gate protects the user, and removal clears the plugin's keys everywhere. The destructiveHint=false annotation is consistent because this only stages changes (apply_changes actually applies them), so no contradiction arises.

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 highest-risk fact (third-party code execution) and the required safety protocol. Every clause earns its place; no filler or restated schema fields.

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?

With an output schema present, return-value explanation isn't needed, and the description still previews the inspection payload (author, version, checksum, AI-assisted flag). For a mutation-capable, open-world tool it covers operations, the safety workflow, and side effects such as key clearing, leaving no material gap.

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?

At 60% schema coverage, the description compensates by explaining the confirm flag's two meanings (inspect vs stage) and enumerating the operation set (install/update/remove). It also names find_plugins for the plugin_id, though it doesn't clarify the source/url relationship beyond what the schema already documents.

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 triplet plus resource: "Install, update or remove a plugin." An agent can immediately tell this manages plugin lifecycle, distinct from siblings like find_plugins (discovery) and get_plugin_settings (configuration). No ambiguity about the resource or the operations available.

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?

Gives an explicit conditional workflow: call with confirm=false first, show the user what was found, and only stage with confirm=true after they agree. It also routes the agent to find_plugins for catalogue ids, naming the sibling alternative. Nothing is left to inference about when and how to invoke it.

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