npm_update_proxy_host

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

With no annotations, the description carries the full behavioral burden and does not meet it. It never says whether this is a partial (PATCH-style) or full-replace update, whether previously set fields omitted from the call are cleared, whether changes require a restart or take effect immediately, or what permissions are needed — all critical for an 18-parameter mutation.

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?

Two short sentences with the core action front-loaded and no filler. The second sentence repeats 'advanced_config' twice in close succession, so it is slightly less tight than it could be, but it is well within an appropriate size.

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 an 18-parameter mutation tool with no annotations and no output schema, the description leaves the important things unsaid: update semantics, reversibility, side effects on dependent hosts, and required permissions. The fully documented schema covers the parameter surface, but the behavioral surface is largely unaddressed.

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 100%, so the baseline is 3. The description does add a small amount of meaning by calling out advanced_config as raw custom nginx configuration and noting that locations carry per-location advanced_config, but the other 16 parameters get no added interpretation.

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 ('Update an existing proxy host') and names two capabilities it supports. It is clearly distinguishable from npm_create_proxy_host / npm_get_proxy_host / npm_delete_proxy_host by name, but the description never references any sibling or scoping condition to make the boundary explicit.

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?

There is no guidance on when to call this versus npm_enable_proxy_host, npm_disable_proxy_host, or npm_create_proxy_host, and no stated prerequisites (e.g. that host_id must reference an existing host obtained from npm_get_proxy_host). Usage is only implied by the word 'update'.

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