npm_raw_request

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

With no annotations, the description carries the burden. It discloses that requests are 'authenticated' and that query/body are 'JSON-encoded', which is useful. However, it does not state what the response looks like, whether responses are pass-through, or any side effects beyond what the HTTP method implies, leaving a notable transparency gap.

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 sentences, each earning its place: purpose, path example, and parameter handling. No fluff, front-loaded with the key concept 'Escape hatch', and entirely readable in a single glance.

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?

Given that this is a generic raw request tool with no output schema, the description covers the essentials: authentication, path, method, query, and body. It does not explain the response format or error behavior, but for an escape hatch that presumably passes through the API response, this is a minor omission rather than a critical 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?

The schema only documents 'path', but the description adds crucial meaning: an example path ('/api/nginx/proxy-hosts'), that method must be upper-case, and that query and body are objects that get JSON-encoded. This compensates for the schema's low 25% coverage and clarifies how to use the parameters.

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 clearly states it is an 'Escape hatch' to 'send any authenticated request to the NPM API', which is a specific verb+resource. It distinguishes from the many sibling tools by being the generic raw-request fallback, unlike the specialized list/create/update/delete tools.

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?

The 'Escape hatch' label implies it should be used when no other sibling tool fits a need, which is clear guidance. It provides an example path and explains that method is upper-case and query/body are JSON-encoded, but it does not explicitly name alternative tools or describe when not to use it.

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